Create a knowledge base in Foundry IQ (Azure AI Search)

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-01 for the GA REST contract, including model-backed planning and answer synthesis. Use 2026-11-01-preview for 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 low or medium planning, answer synthesis, and web summarization. A knowledge base that uses an existing search index or file source can use minimal effort and extractiveData without 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.Documents package:

    • For the SDK definition-management examples, the latest preview package: dotnet add package Azure.Search.Documents --prerelease

    • For 2026-10-01, the latest stable package: dotnet add package Azure.Search.Documents

  • For keyless authentication, the Azure.Identity package: dotnet add package Azure.Identity

  • Required azure-search-documents package:

    • For the SDK definition-management examples, the latest preview package: pip install --pre azure-search-documents

    • For 2026-10-01, the latest stable package: pip install azure-search-documents

  • For keyless authentication, the azure-identity package: 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 older 2026-04-01 examples retain their narrower contract.

  • For keyless authentication, include a Microsoft Entra ID token in the Authorization header 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. modelName selects Search capabilities, not the actual provider deployment. The compatible contract has no dated modelVersion property.
  • On create, supply exactly one nonempty headers map or managedIdentityAudience. authIdentity is 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 omitted headers only 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 omit headers entirely. Explicit null, 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 managedIdentityAudience and 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.

  1. Follow Call the retrieve action using REST and the same <knowledge-base-name> you configured above. Send the POST to https://<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.
  2. In the request body, supply messages containing a role: "user" message whose content array contains a type: "text" item and your question in text. Set retrievalReasoningEffort to {"kind": "low"}, outputMode to "extractiveData", and includeActivity to true. Low reasoning effort exercises LLM query planning; minimal retrieval doesn't verify this connection.
  3. Confirm successful retrieval and inspect the activity array for modelQueryPlanning and 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.
  4. 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.

  1. Enable role-based access control on Foundry IQ.

  2. Configure Foundry IQ to use a managed identity.

  3. 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.

  4. For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use DefaultAzureCredential instead of AzureKeyCredential in 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());
    
  1. Enable role-based access control on Foundry IQ.

  2. Configure Foundry IQ to use a managed identity.

  3. 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.

  4. For local testing, follow the steps in Quickstart: Connect without keys to sign in to a specific subscription and tenant. Use DefaultAzureCredential instead of AzureKeyCredential in 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())
    
  1. Enable role-based access control on Foundry IQ.

  2. Configure Foundry IQ to use a managed identity.

  3. 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.

  4. 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:

  1. The corresponding value on the retrieve request.
  2. The value in the knowledge base retrieveDefaults object.
  3. 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:

  1. Send an OPTIONS preflight to this knowledge base's retrieve route using api-version=2026-10-01. Set Origin to https://myapp.example.com, request the POST method, and identify the headers your retrieve request uses.
  2. 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.
  3. Repeat with an unconfigured custom origin. Expect no CORS permission for that origin; don't infer the result from a particular denial status code.
  4. 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