Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Note
Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.
Important
Features or capabilities marked (preview) in this article are in Public Preview and are subject to the Supplemental Terms of Use for Microsoft Azure Previews. For preview terms specific to Foundry IQ (Azure AI Search), see Preview functionality. For terms that apply when you use supported non-Microsoft models, see Third-party models.
In Foundry IQ (Azure AI Search), a knowledge base is a top-level object that orchestrates agentic retrieval. It defines which knowledge sources to query and the default behavior for retrieval operations. At query time, the retrieve method targets the knowledge base to run the configured retrieval pipeline.
A knowledge base specifies:
One or more knowledge sources that point to searchable content.
An optional LLM for query planning, answer synthesis, or web content summarization. Supported tasks vary by API version and knowledge source type.
Custom properties that control routing, source selection, and object encryption.
Usage support
| Azure portal | Microsoft Foundry portal | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Prerequisites
Foundry IQ in any region that provides agentic retrieval. If you use a managed identity for role-based access to deployed models, your Foundry IQ service must be on the Basic tier or higher.
One or more knowledge sources. Use
2026-10-01for the GA REST contract, including model-backed planning and answer synthesis. Use2026-11-01-previewfor preview knowledge sources and features.(Conditional) For a native Azure OpenAI connection, a supported LLM deployment. For a customer-controlled model endpoint through Azure API Management, see Connect through Azure API Management (preview). An LLM is required for
lowormediumplanning, answer synthesis, and web summarization. A knowledge base that uses an existing search index or file source can useminimaleffort andextractiveDatawithout a model or retrieval and answer instructions.Permission to create knowledge bases. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an admin API key.
For native LLM managed-identity authentication, assign Cognitive Services OpenAI User to the selected Search managed identity on the parent Azure OpenAI or Microsoft Foundry resource that hosts the deployment and matches
resourceUri. Don't assign this model-access role on the Foundry IQ service, a Foundry project, or an individual deployment. Compatible gateway custom audiences require their own authorization configuration; don't assume the same role applies. See Compatible authentication.
Required
Azure.Search.Documentspackage:For the SDK definition-management examples, the latest preview package:
dotnet add package Azure.Search.Documents --prereleaseFor
2026-10-01, the latest stable package:dotnet add package Azure.Search.Documents
For keyless authentication, the
Azure.Identitypackage:dotnet add package Azure.Identity
Required
azure-search-documentspackage:For the SDK definition-management examples, the latest preview package:
pip install --pre azure-search-documentsFor
2026-10-01, the latest stable package:pip install azure-search-documents
For keyless authentication, the
azure-identitypackage:pip install azure-identity
Required Search Service REST API version:
For preview features: 2026-11-01-preview
For the GA contract described in this article:
2026-10-01. The older2026-04-01examples retain their narrower contract.
For keyless authentication, include a Microsoft Entra ID token in the
Authorizationheader of each HTTP request.
Supported models
Use one of the following LLMs from Azure OpenAI in Foundry Models. Azure OpenAI determines regional availability for the deployment you select. For deployment instructions, see Deploy Microsoft Foundry Models in the Foundry portal.
The GPT-4 family is deprecated. For model lifecycle guidance, retirement dates, and current status, see Model retirement and deprecation and Model retirement schedule - Microsoft Foundry.
| Model | Supported API versions |
|---|---|
gpt-4o (deprecated) |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-4o-mini (deprecated) |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-4.1 (deprecated) |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-4.1-mini (deprecated) |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-4.1-nano (deprecated) |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-5 |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview |
gpt-5-mini |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview, 2026-10-01 |
gpt-5-nano |
2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview, 2026-10-01 |
gpt-5.1 |
2026-05-01-preview, 2026-08-01-preview |
gpt-5.2 |
2026-05-01-preview, 2026-08-01-preview |
gpt-5.4 |
2026-05-01-preview, 2026-08-01-preview, 2026-10-01 |
gpt-5.4-mini |
2026-05-01-preview, 2026-08-01-preview, 2026-10-01 |
gpt-5.4-nano |
2026-05-01-preview, 2026-08-01-preview, 2026-10-01 |
gpt-5.5 |
2026-08-01-preview, 2026-10-01 |
gpt-5.6-sol |
2026-08-01-preview, 2026-10-01 |
gpt-5.6-terra |
2026-08-01-preview, 2026-10-01 |
gpt-5.6-luna |
2026-08-01-preview, 2026-10-01 |
gpt-6-astra |
2026-11-01-preview |
gpt-6-sol |
2026-11-01-preview |
gpt-6-luna |
2026-11-01-preview |
gpt-6.1-sol |
2026-11-01-preview |
All model profiles in the preceding table support 2026-11-01-preview.
For 2026-11-01-preview, Microsoft Retriever 1 is a parameterless planning model configured as {"kind":"microsoftRetriever1"}. It doesn't require a customer model connection. A knowledge base that only uses Microsoft Retriever 1 supports minimal reasoning and extractive output, not external answer synthesis. See Use Microsoft Retriever 1.
For native Azure OpenAI models in the GPT-6 family, configure an existing deployment with azureOpenAIParameters.resourceUri, deploymentId, and the exact supported modelName. The deployment ID and model name are distinct values.
Connect through Azure API Management (preview)
Note
OpenAI-compatible knowledge base model connections require 2026-11-01-preview. They aren't supported by 2026-10-01.
Knowledge base models with kind set to azureOpenAI require a native Azure OpenAI or Microsoft Foundry endpoint. For an API Management (APIM) or custom-domain endpoint, set kind to openAICompatible and configure openAICompatibleParameters.
To switch an existing model connection, replace azureOpenAIParameters with openAICompatibleParameters in the same model entry. Supply uri and fresh authentication using either headers or an explicit managedIdentityAudience, as described below. Update the existing knowledge base with 2026-11-01-preview or a later supported preview version; you don't need to recreate it.
Set uri to the complete HTTPS POST endpoint, including its path and required query parameters. Search sends requests to this URL as provided and doesn't follow redirects.
Set modelName to a supported Search chat-model profile. It determines Search's capabilities, limits, and protocol, not the gateway's actual deployment. Existing chat-model profiles use Chat Completions; GPT-6 profiles use Responses. The endpoint must support the selected protocol. Search omits model from the outbound retrieval request body, so the URI or gateway must select the actual model and supply any provider-required model identifier. Embedding models and arbitrary provider protocols aren't supported.
GPT-5.6 Chat Completions can't combine tools with reasoning. Search omits reasoning_effort for these tool requests, but Azure OpenAI defaults an omitted value to medium. If your gateway routes a GPT-5.6 profile to an Azure OpenAI GPT-5.6 deployment, set reasoning_effort to none when the request includes tools. See Tool calling with reasoning models.
For Responses, the endpoint must support stateless tool continuation, not just an initial response. Search sends store set to false and requests reasoning.encrypted_content.
Choose one authentication mode:
| Mode | Connection settings |
|---|---|
| Headers | Set headers to a nonempty string-to-string map of endpoint authentication headers. Don't also set managedIdentityAudience or authIdentity. |
| Managed identity | Set managedIdentityAudience to the bare canonical application GUID of your third-party Microsoft Entra application, not a Microsoft first-party application. Don't include an api:// prefix or /.default suffix, and don't set headers. Omit authIdentity to use the Foundry IQ service's system-assigned identity. For a user-assigned identity, set its @odata.type to #Microsoft.Azure.Search.DataUserAssignedIdentity and userAssignedIdentity to its full resource ID. That identity must already be assigned to the Foundry IQ service. |
Both authentication header names and values are secret, write-only settings and aren't returned in API representations. On update, omitted headers can carry forward only for the same resource and model binding, exact URI, unchanged supported model profile, and unchanged authentication identity and mode. Supply fresh credentials when the binding changes; don't rely on header preservation after reordering the models array.
Compatible models aren't supported in knowledge bases with Web knowledge sources, even when the endpoint URL looks like a native Azure OpenAI URL. These connections are also blocked when the Foundry IQ service's dataExfiltrationProtections includes All.
For a responses profile, use an endpoint that supports responses and stateless tool continuation. For example, send the same PUT operation with this body:
{
"name": "<knowledge-base-name>",
"knowledgeSources": [
{ "name": "<knowledge-source-name>" }
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://<gateway-host>/openai/v1/responses",
"modelName": "gpt-6.1-sol",
"managedIdentityAudience": "11111111-2222-3333-4444-555555555555"
}
}
]
}
Replace the example GUID with the receiving application's bare canonical Microsoft Entra application ID. Don't use api://, a scope, /.default, or the Cognitive Services audience. This example uses the Foundry IQ service's system-assigned identity. To select an attached user-assigned identity, add the supported identity object.
Search sends store:false and continuation structures that include encrypted reasoning content and function-call inputs and outputs. The endpoint must preserve these structures. As with compatible chat completions, Search omits outbound model. Unlike this compatible flow, native GPT-6 knowledge base retrieval sends the deployment ID as model to /openai/v1/responses. Don't assume fallback to chat completions.
Connection and update requirements
- Supply the complete absolute HTTPS POST URL, including path and query parameters. Search doesn't append an operation or API version and doesn't follow redirects, even to the same host. Don't include credentials or URL fragments.
- Use exact canonical profile names from Supported models.
modelNameselects Search capabilities, not the actual provider deployment. The compatible contract has no datedmodelVersionproperty. - On create, supply exactly one nonempty
headersmap ormanagedIdentityAudience.authIdentityis allowed only with the latter. Empty headers, both modes, or no mode are invalid. - In
2026-11-01-preview, a same-KB read-to-PUT update can preserve omittedheadersonly for an existing valid header-authenticated compatible model binding. Keep the model kind, exact URI (including path and query text), profile, and identity configuration unchanged, and omitheadersentirely. Explicitnull, an empty map, or per-header redaction strings aren't the omitted-property update pattern. - Copying, renaming, or changing the destination, profile, or identity requires fresh authentication. To rotate headers, supply the replacement map in the complete KB definition. To change to managed identity, configure
managedIdentityAudienceand the selected identity explicitly. A rejected update leaves existing credentials unchanged. - Private connectivity requires a route from the actual execution host. An API Management Gateway shared private link alone doesn't establish compatible KB private-route support.
GET output omits compatible headers; it doesn't back up those credentials. Don't send <redacted> or <unchanged> as gateway credentials. A new KB has no stored headers to inherit from a copied definition. Validate and supply target authentication before creation, rather than creating an invalid intermediate KB.
First, create a header-authenticated KB by using PUT https://<search-service>.search.windows.net/knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview, your Search authentication, and Content-Type: application/json. Replace the placeholders in the following body with your values, omit description, and add a nonempty openAICompatibleParameters.headers map containing the gateway's authentication headers and credentials.
After creation succeeds, submit the following body to the same PUT URL, using the same substituted values but omitting headers. The update changes the description and retains the stored headers. Keep the KB name, source, model kind, exact URI, and profile unchanged:
{
"name": "<knowledge-base-name>",
"description": "Updated description",
"knowledgeSources": [
{ "name": "<knowledge-source-name>" }
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>",
"modelName": "gpt-5.4"
}
}
]
}
Reference: Knowledge Bases - Create Or Update.
For authentication examples, credential transitions, security responsibilities, and troubleshooting, see Use API Management with Foundry IQ model calls.
Verify the retrieval model connection
A successful KB create or GET verifies configuration, not an outbound model call. Use a test question about content in the KB's existing knowledge sources.
- Follow Call the retrieve action using REST and the same
<knowledge-base-name>you configured above. Send the POST tohttps://<search-service>.search.windows.net/knowledgebases('<knowledge-base-name>')/retrieve?api-version=2026-11-01-preview, using your existing Search authentication. Use November preview for this check rather than the versions in the guide's retained examples. - In the request body, supply
messagescontaining arole: "user"message whosecontentarray contains atype: "text"item and your question intext. SetretrievalReasoningEffortto{"kind": "low"},outputModeto"extractiveData", andincludeActivitytotrue. Low reasoning effort exercises LLM query planning; minimal retrieval doesn't verify this connection. - Confirm successful retrieval and inspect the activity array for
modelQueryPlanningand token usage where returned. Review retrieved content for the test question. For a gateway connection, confirm the intended operation path, backend routing, and profile-selected protocol in sanitized gateway telemetry. For Responses, verify that tool continuation succeeds without dropping encrypted reasoning or function-call structures. - After rotating a header credential, repeat the same retrieve request and confirm the gateway accepts the replacement. Then GET and PUT the unchanged definition of the same KB with November preview. Headers remain absent from GET; retrieval should still succeed when the binding, exact endpoint, profile, and identity are unchanged. If a configuration update is rejected, verify that retrieval still works with the previously stored credentials.
Record only nonsecret outcomes, status codes, and activity metadata. Don't log credential header names or values, access tokens, or sensitive request and response content. These checks verify your configured connection, not provider-wide availability or private-route eligibility.
Configure access
If your knowledge base uses an Azure OpenAI model, Foundry IQ needs access to it. We recommend Microsoft Entra ID for authentication and role-based access for authorization. To assign roles, you must be an Owner or User Access Administrator. If you can't use roles, use key-based authentication instead.
On your model provider, assign Cognitive Services User to the managed identity of your Foundry IQ service. If you're testing locally, assign the same role to your user account.
For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use
DefaultAzureCredentialinstead ofAzureKeyCredentialin each request, which should be similar to the following example.// Authenticate using roles using Azure.Search.Documents.Indexes; using Azure.Identity; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
On your model provider, assign Cognitive Services User to the managed identity of your Foundry IQ service. If you're testing locally, assign the same role to your user account.
For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use
DefaultAzureCredentialinstead ofAzureKeyCredentialin each request, which should be similar to the following example.# Authenticate using roles from azure.identity import DefaultAzureCredential index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
On your model provider, assign Cognitive Services User to the managed identity of your Foundry IQ service. If you're testing locally, assign the same role to your user account.
For local testing, follow the steps in Quickstart: Connect without keys to get a personal access token for a specific subscription and tenant. Specify your access token in each request, which should be similar to the following example.
# List indexes using roles GET {{search-endpoint}}/indexes?api-version=2026-10-01 Content-Type: application/json Authorization: Bearer {{search-access-token}}
The SDK definition-management examples use an admin API key. For the recommended keyless setup, see Configure access.
Check for existing knowledge bases
A knowledge base is a top-level, reusable object. Knowing about existing knowledge bases is helpful for either reuse or naming new objects.
List knowledge bases with the definition client for your chosen API version. The Python example iterates the native paged listing. The C# example uses a prefix search and a page size of 10.
using System;
using System.Collections.Generic;
using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
endpoint, new AzureKeyCredential(key));
var knowledgeBases = new List<KnowledgeBase>();
await foreach (var kb in indexClient.GetKnowledgeBasesAsync(
search: "sdk-", pageSize: 10, searchType: ListingSearchType.Prefix))
{
knowledgeBases.Add(kb);
}
Reference: SearchIndexClient
import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
knowledge_bases = list(index_client.list_knowledge_bases())
Reference: SearchIndexClient
# List knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version={{api-version}}&$select=name
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Reference: Knowledge Bases - List
Read an existing knowledge base by name and inspect selected definition properties. Use the names from the SDK creation examples, or substitute a knowledge base you can read.
using System;
using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
endpoint, new AzureKeyCredential(key));
var kb = (await indexClient.GetKnowledgeBaseAsync("<knowledge-base-name>")).Value;
Reference: SearchIndexClient
import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
kb = index_client.get_knowledge_base("<knowledge-base-name>")
Reference: SearchIndexClient
# Get knowledge base
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Reference: Knowledge Bases - Get
The following JSON is an example response for a knowledge base.
{
"name": "my-kb",
"description": "A sample knowledge base.",
"retrievalInstructions": null,
"answerInstructions": null,
"outputMode": null,
"knowledgeSources": [
{
"name": "my-blob-ks"
}
],
"models": [],
"encryptionKey": null,
"retrievalReasoningEffort": {
"kind": "low"
}
}
Note
Read and write definitions using the contract for your target API version. Preview-only properties aren't part of the 2026-10-01 schema. For version-specific changes, see Migrate agentic retrieval code.
Create a knowledge base
Important
The older 2026-04-01 API version supports minimal, extractive retrieval, but not model-backed planning or answer synthesis. These capabilities are available in the GA 2026-10-01 REST contract. Don't migrate a preview definition by changing only its API version.
A knowledge base connects one or more knowledge sources (searchable content) to an optional LLM from Azure OpenAI in Foundry Models. Omit models to create a model-free knowledge base. The properties you set establish defaults for query execution and the retrieval response.
After you create a knowledge base, you can update its properties, including switching a native model connection to an APIM or custom-domain endpoint. If the knowledge base is in use, updates take effect on the next retrieval.
Use an existing, populated search index knowledge source and credentials authorized to create a knowledge base. Replace {{search-endpoint}}, {{knowledge-source-name}}, and {{search-token}} with your inputs. This example creates a model-free knowledge base for extractive retrieval.
PUT {{search-endpoint}}/knowledgebases('core-minimal-kb')?api-version=2026-10-01
Content-Type: application/json
Authorization: Bearer {{search-token}}
{
"name": "core-minimal-kb",
"knowledgeSources": [
{ "name": "{{knowledge-source-name}}" }
],
"retrievalReasoningEffort": {
"kind": "minimal"
},
"outputMode": "extractiveData"
}
Reference: Knowledge Bases - Create or Update
In this contract, each knowledgeSources entry contains only name. Store source configuration, such as searchIndexParameters.baseFilter, on the knowledge source. Set request-specific options, such as alwaysQuerySource and failOnError, in retrieve-time knowledgeSourceParams, not in KB membership entries.
auto, retrieveDefaults, and neverQuerySource aren't part of the GA contract.
Next, retrieve with 2026-10-01 REST.
Configure default retrieve limits (preview)
Starting with the 2026-08-01-preview API version, you can use the optional retrieveDefaults object to store request-wide defaults on a knowledge base.
retrieveDefaults isn't available in 2026-10-01. In that GA contract, set limits on the retrieve request and use maxOutputSizeInTokens for the token budget.
For the preview examples, each stored property applies only when a request omits the corresponding request field:
| Stored property | Retrieve request field |
|---|---|
maxRuntimeInSeconds |
maxRuntimeInSeconds |
maxOutputDocuments |
maxOutputDocuments |
maxOutputSizeInTokens |
maxOutputSize |
The output token budget uses different property names when stored and overridden. Set maxOutputSizeInTokens in retrieveDefaults, and use maxOutputSize in a retrieve request.
The effective value for each property is determined independently in this order:
- The corresponding value on the retrieve request.
- The value in the knowledge base
retrieveDefaultsobject. - The service default when the property is absent at both levels.
The following example uses an existing search index knowledge source named your-knowledge-source. It stores a 45-second runtime budget, a maximum of eight output documents, and a 12,000-token output budget.
using System;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
string searchEndpoint = "<search-endpoint>";
var indexClient = new SearchIndexClient(
new Uri(searchEndpoint),
new DefaultAzureCredential());
var knowledgeBase = new KnowledgeBase(
"your-knowledge-base",
new[] { new KnowledgeSourceReference("your-knowledge-source") })
{
Description = "A knowledge base for product support content.",
RetrieveDefaults = new KnowledgeBaseRetrieveDefaults
{
MaxRuntimeInSeconds = 45,
MaxOutputDocuments = 8,
MaxOutputSizeInTokens = 12000
}
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Reference: SearchIndexClient, SearchClientOptions.ServiceVersion, KnowledgeBase
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
KnowledgeBase,
KnowledgeBaseRetrieveDefaults,
KnowledgeSourceReference,
)
search_endpoint = "<search-endpoint>"
index_client = SearchIndexClient(
endpoint=search_endpoint,
credential=DefaultAzureCredential(),
)
knowledge_base = KnowledgeBase(
name="your-knowledge-base",
description="A knowledge base for product support content.",
knowledge_sources=[
KnowledgeSourceReference(name="your-knowledge-source"),
],
retrieve_defaults=KnowledgeBaseRetrieveDefaults(
max_runtime_in_seconds=45,
max_output_documents=8,
max_output_size_in_tokens=12000,
),
)
index_client.create_or_update_knowledge_base(knowledge_base)
Reference: SearchIndexClient, KnowledgeBase
PUT {{search-endpoint}}/knowledgebases/your-knowledge-base?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"name": "your-knowledge-base",
"description": "A knowledge base for product support content.",
"knowledgeSources": [
{
"name": "your-knowledge-source"
}
],
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
}
}
Reference: Knowledge Bases - Create or Update
To override stored values for one request, set the corresponding maxRuntimeInSeconds, maxOutputDocuments, and maxOutputSize fields in the preview retrieve request.
Configure CORS for browser-based retrieve calls
Important
Cross-origin resource sharing (CORS) allows browser-based applications to request data directly from the service. Depending on your CORS configuration, external web pages might access or invoke the service and its data by using the user's browser context. This access can create security threats. Enabling CORS is at your own risk.
Starting with the 2026-05-01-preview API version, a knowledge base can define corsOptions for browser-based applications that call the retrieve action directly from JavaScript. The CORS policy identifies which browser origins can send retrieve requests to the knowledge base.
CORS is also supported in 2026-10-01. When you omit corsOptions, default portal origins remain allowed, but an unconfigured custom origin isn't allowed. CORS controls browser access, not authorization: callers still need permission to retrieve content.
Use a list of trusted origins, or a single "*" value. Don't mix "*" with other origins. maxAgeInSeconds controls preflight caching, accepts nonnegative values, and defaults to five minutes.
For GA REST, use an existing, populated search index knowledge source named product-docs-ks and credentials authorized to create a knowledge base.
PUT {{search-endpoint}}/knowledgebases('browser-chat-kb')?api-version=2026-10-01
Content-Type: application/json
Authorization: Bearer {{search-token}}
{
"name": "browser-chat-kb",
"knowledgeSources": [
{ "name": "product-docs-ks" }
],
"retrievalReasoningEffort": {
"kind": "minimal"
},
"outputMode": "extractiveData",
"corsOptions": {
"allowedOrigins": ["https://myapp.example.com"],
"maxAgeInSeconds": 300
}
}
Reference: Knowledge Bases - Create or Update
To check the CORS policy separately:
- Send an OPTIONS preflight to this knowledge base's retrieve route using
api-version=2026-10-01. SetOrigintohttps://myapp.example.com, request the POST method, and identify the headers your retrieve request uses. - Inspect the response's allowed-origin and preflight-cache headers. For this configured origin, expect the policy to allow the origin and use the configured 300-second preflight cache age.
- Repeat with an unconfigured custom origin. Expect no CORS permission for that origin; don't infer the result from a particular denial status code.
- Send an authorized retrieve request separately. Policy creation or preflight doesn't grant content access. HTTP preflight checks don't establish browser behavior or the caller's document permissions.
The SDK examples update an existing knowledge base. Use only a knowledge base you intend to change. Each example reads the existing model, changes stored configuration, saves it, and reads it back. These definition operations don't verify HTTP or browser CORS enforcement.
Retain the existing allowed origins and change the description and preflight cache age to 120 seconds. The knowledge base must already define CorsOptions.
using System;
using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
endpoint, new AzureKeyCredential(key));
var kb = (await indexClient.GetKnowledgeBaseAsync("<knowledge-base-name>")).Value;
kb.Description = "Updated CORS configuration.";
kb.CorsOptions.MaxAgeInSeconds = 120;
var updated = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(kb)).Value;
var readback = (await indexClient.GetKnowledgeBaseAsync(updated.Name)).Value;
Reference: CorsOptions, KnowledgeBase
Set the intended allowed origin and a 60-second preflight cache age.
import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import CorsOptions
index_client = SearchIndexClient(
endpoint=os.environ["SEARCH_ENDPOINT"],
credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
kb = index_client.get_knowledge_base("<knowledge-base-name>")
kb.cors_options = CorsOptions(
allowed_origins=["https://myapp.example.com"],
max_age_in_seconds=60,
)
updated = index_client.create_or_update_knowledge_base(kb)
readback = index_client.get_knowledge_base(updated.name)
Reference: CorsOptions, KnowledgeBase
PUT {{search-endpoint}}/knowledgebases/browser-chat-kb?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"name": "browser-chat-kb",
"description": "A knowledge base that allows one browser app origin.",
"knowledgeSources": [
{
"name": "product-docs-ks"
}
],
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
}
}
Query a knowledge base
To verify a configured model connection, call the retrieve action by using the same API version and knowledge base configuration. Use an LLM-backed request and check nonsecret model activity and gateway routing, if applicable. A successful create or GET request alone doesn't verify a model invocation. For ordinary queries, use the retrieve action or MCP endpoint.
Delete a knowledge base
If you no longer need the knowledge base or need to rebuild it on your Foundry IQ service, run the following code to delete the object.
// Delete a knowledge base
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(
new Uri(searchEndpoint), credential);
await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
Reference: SearchIndexClient
# Delete a knowledge base
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(
endpoint="<search-endpoint>",
credential=DefaultAzureCredential(),
)
index_client.delete_knowledge_base("<knowledge-base-name>")
Reference: SearchIndexClient
# Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{search-access-token}}
Reference: Knowledge Bases - Delete