Knowledge Bases - Create Or Update
Creates a new knowledge base or updates a knowledge base if it already exists.
PUT {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-11-01-preview
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
The endpoint URL of the search service. |
|
knowledge
|
path | True |
string |
The name of the knowledge base. |
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
Request Header
| Name | Required | Type | Description |
|---|---|---|---|
| x-ms-client-request-id |
string (uuid) |
An opaque, globally-unique, client-generated string identifier for the request. |
|
| Accept |
The Accept header. |
||
| If-Match |
string |
Defines the If-Match condition. The operation will be performed only if the ETag on the server matches this value. |
|
| If-None-Match |
string |
Defines the If-None-Match condition. The operation will be performed only if the ETag on the server does not match this value. |
|
| Prefer | True |
For HTTP PUT requests, instructs the service to return the created/updated resource on success. |
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| knowledgeSources | True |
Knowledge sources referenced by this knowledge base. |
|
| name | True |
string |
The name of the knowledge base. |
| @odata.etag |
string |
The ETag of the knowledge base. |
|
| answerInstructions |
string |
Instructions considered by the knowledge base when generating answers. |
|
| corsOptions |
Options to control Cross-Origin Resource Sharing (CORS) for the knowledge base. |
||
| description |
string |
The description of the knowledge base. |
|
| encryptionKey |
A description of an encryption key that you create in Azure Key Vault. |
||
| models | KnowledgeBaseModel[]: |
Contains configuration options on how to connect to AI models. |
|
| outputMode |
The output mode for the knowledge base. |
||
| retrievalInstructions |
string |
Instructions considered by the knowledge base when developing query plan. |
|
| retrievalReasoningEffort | KnowledgeRetrievalReasoningEffort: |
The retrieval reasoning effort configuration. |
|
| retrieveDefaults |
Persisted request-wide retrieve defaults for this knowledge base. These values apply to retrieve requests that omit the corresponding fields; request-time values take precedence when present. |
||
| tags |
object |
User-defined key-value pairs for categorizing the knowledge base and attributing its usage and costs. |
|
| tools |
Named retrieval tools, each limited to a subset of this knowledge base's sources. When configured, MCP advertises these tools in addition to the built-in knowledge_base_retrieve tool, which retrieves from the full knowledge base. Omitting tools or supplying an empty array in this API version clears existing tools. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
The request has succeeded. |
|
| 201 Created |
The request has succeeded and a new resource has been created as a result. |
|
| Other Status Codes |
An unexpected error response. |
Security
api-key
Type:
apiKey
In:
header
OAuth2Auth
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Scopes
| Name | Description |
|---|---|
| https://search.azure.com/.default |
Examples
SearchServiceCreateOrUpdateKnowledgeBase
Sample request
PUT https://typespecpreviewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2026-11-01-preview
{
"name": "base-preview-test",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://test-sample.openai.azure.com/",
"deploymentId": "myDeployment",
"apiKey": "api-key",
"modelName": "gpt-4o-mini"
}
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"outputMode": "extractiveData",
"@odata.etag": "0x1234568AE7E58A1",
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"description": "Description of the knowledge base.",
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
}
}
Sample response
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "base-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://test-sample.openai.azure.com/",
"deploymentId": "myDeployment",
"apiKey": "api-key",
"modelName": "gpt-4o-mini"
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "base-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://test-sample.openai.azure.com/",
"deploymentId": "myDeployment",
"apiKey": "api-key",
"modelName": "gpt-4o-mini"
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
SearchServiceCreateOrUpdateKnowledgeBaseMicrosoftRetriever1
Sample request
PUT https://typespecpreviewexampleservice.search.windows.net/knowledgebases('travel-knowledgebase')?api-version=2026-11-01-preview
{
"name": "travel-knowledgebase",
"knowledgeSources": [
{
"name": "hotels"
}
],
"models": [
{
"kind": "microsoftRetriever1"
}
],
"outputMode": "extractiveData",
"description": "Find hotels using Microsoft Retriever 1."
}
Sample response
{
"name": "travel-knowledgebase",
"knowledgeSources": [
{
"name": "hotels"
}
],
"models": [
{
"kind": "microsoftRetriever1"
}
],
"outputMode": "extractiveData",
"description": "Find hotels using Microsoft Retriever 1."
}
{
"name": "travel-knowledgebase",
"knowledgeSources": [
{
"name": "hotels"
}
],
"models": [
{
"kind": "microsoftRetriever1"
}
],
"outputMode": "extractiveData",
"description": "Find hotels using Microsoft Retriever 1."
}
SearchServiceCreateOrUpdateKnowledgeBaseOpenAICompatible
Sample request
PUT https://typespecpreviewexampleservice.search.windows.net/knowledgebases('compatible-model-preview-test')?api-version=2026-11-01-preview
{
"name": "compatible-model-preview-test",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini",
"headers": {
"api-key": "EXAMPLE-NOT-A-REAL-SECRET"
}
}
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"outputMode": "extractiveData",
"@odata.etag": "0x1234568AE7E58A1",
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"description": "Description of the knowledge base.",
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
}
}
Sample response
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "compatible-model-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini"
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "compatible-model-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini"
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
SearchServiceCreateOrUpdateKnowledgeBaseOpenAICompatibleUserAssignedIdentity
Sample request
PUT https://typespecpreviewexampleservice.search.windows.net/knowledgebases('compatible-model-preview-test')?api-version=2026-11-01-preview
{
"name": "compatible-model-preview-test",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini",
"managedIdentityAudience": "11111111-2222-3333-4444-555555555555",
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/search-identities/providers/Microsoft.ManagedIdentity/userAssignedIdentities/catalog-model-caller"
}
}
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"outputMode": "extractiveData",
"@odata.etag": "0x1234568AE7E58A1",
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"description": "Description of the knowledge base.",
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
}
}
Sample response
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "compatible-model-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini",
"managedIdentityAudience": "11111111-2222-3333-4444-555555555555",
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/search-identities/providers/Microsoft.ManagedIdentity/userAssignedIdentities/catalog-model-caller"
}
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "compatible-model-preview-test",
"description": "Description of the knowledge base.",
"retrievalInstructions": "Instructions for retrieval for the knowledge base.",
"answerInstructions": "Instructions for answer synthesis.",
"outputMode": "extractiveData",
"knowledgeSources": [
{
"name": "ks-preview-test"
}
],
"models": [
{
"kind": "openAICompatible",
"openAICompatibleParameters": {
"uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
"modelName": "gpt-4.1-mini",
"managedIdentityAudience": "11111111-2222-3333-4444-555555555555",
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/search-identities/providers/Microsoft.ManagedIdentity/userAssignedIdentities/catalog-model-caller"
}
}
}
],
"encryptionKey": {
"keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
"keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
"keyVaultUri": "https://myKeyVault.vault.azure.net",
"isServiceLevelKey": false,
"accessCredentials": {
"applicationId": "00000000-0000-0000-0000-000000000000",
"applicationSecret": "<applicationSecret>"
}
},
"tags": {
"businessUnit": "Contoso Engineering Department",
"costCenter": "ABC-123",
"owner": "Contoso"
},
"retrievalReasoningEffort": {
"kind": "low"
},
"corsOptions": {
"allowedOrigins": [
"https://myapp.example.com"
],
"maxAgeInSeconds": 300
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 45,
"maxOutputDocuments": 8,
"maxOutputSizeInTokens": 12000
},
"tools": [
{
"name": "product-search",
"description": "Search product documentation.",
"knowledgeSources": [
{
"name": "ks-preview-test",
"alwaysQuerySource": false,
"filterAddOn": "id ne null",
"maxOutputDocuments": 50,
"failOnError": true
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputDocuments": 2,
"maxOutputSizeInTokens": 5000
}
}
]
}
Definitions
| Name | Description |
|---|---|
| Accept |
The Accept header. |
|
Azure |
The Azure Open AI model name that will be called. |
|
Azure |
Specifies the parameters for connecting to the Azure OpenAI resource. |
|
Cors |
Defines options to control Cross-Origin Resource Sharing (CORS) for an index. |
|
Error |
The resource management error additional info. |
|
Error |
The error detail. |
|
Error |
Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.). |
|
Knowledge |
Represents a knowledge base definition. |
|
Knowledge |
Specifies the Azure OpenAI resource used to do query planning. |
|
Knowledge |
Specifies Microsoft Retriever 1 used for query planning and retrieval. |
|
Knowledge |
The AI model to be used for query planning. |
|
Knowledge |
Specifies a customer-controlled OpenAI-compatible model for knowledge base retrieval or Minimal-mode knowledge source image verbalization. For retrieval, the model profile selects Chat Completions or Responses. Not supported for Standard/CU extraction or knowledge bases with Web knowledge sources. |
|
Knowledge |
Connection parameters for an OpenAI-compatible Chat Completions or Responses endpoint. Creation requires exactly one of nonempty headers or managedIdentityAudience. Updates can omit headers to preserve credentials for an unchanged connection and model profile. |
|
Knowledge |
Persisted request-wide defaults for knowledge base retrieve requests. Each value provides the default for the matching retrieve-request field; service defaults apply when unset, and request-time values take precedence when present. |
|
Knowledge |
A named retrieval tool with a customer-provided description and a subset of its knowledge base's sources. |
|
Knowledge |
A reference to an existing knowledge source and a selected subset of persisted retrieval defaults, not the complete request-time parameter model. The referenced source determines the kind; incompatible defaults are rejected when the knowledge base is saved. Explicit retrieve-request values take precedence, except filters are combined with AND. |
|
Knowledge |
Automatically select the reasoning effort during retrieval. The service seeds every request at the cheapest tier and escalates only as far as needed, up to the service's maximum available tier. |
|
Knowledge |
Run knowledge retrieval with low reasoning effort. |
|
Knowledge |
Run knowledge retrieval with medium reasoning effort. |
|
Knowledge |
Run knowledge retrieval with minimal reasoning effort. |
|
Knowledge |
The output configuration for this retrieval. |
|
Knowledge |
The amount of effort to use during retrieval. |
|
Knowledge |
Reference to a knowledge source. |
| Prefer |
For HTTP PUT requests, instructs the service to return the created/updated resource on success. |
|
Search |
Clears the identity property of a datasource. |
|
Search |
Specifies the identity for a datasource to use. |
|
Search |
A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps. |
Accept
The Accept header.
| Value | Description |
|---|---|
| application/json;odata.metadata=minimal |
AzureOpenAIModelName
The Azure Open AI model name that will be called.
| Value | Description |
|---|---|
| text-embedding-ada-002 |
TextEmbeddingAda002 model. |
| text-embedding-3-large |
TextEmbedding3Large model. |
| text-embedding-3-small |
TextEmbedding3Small model. |
| gpt-4o |
Gpt4o model. |
| gpt-4o-mini |
Gpt4oMini model. |
| gpt-4.1 |
Gpt41 model. |
| gpt-4.1-mini |
Gpt41Mini model. |
| gpt-4.1-nano |
Gpt41Nano model. |
| gpt-5 |
Gpt5 model. |
| gpt-5-mini |
Gpt5Mini model. |
| gpt-5-nano |
Gpt5Nano model. |
| gpt-5.1 |
Gpt51 model. |
| gpt-5.2 |
Gpt52 model. |
| gpt-5.4 |
Gpt54 model. |
| gpt-5.4-mini |
Gpt54Mini model. |
| gpt-5.4-nano |
Gpt54Nano model. |
| gpt-5.5 |
Gpt55 model. |
| gpt-5.6-sol |
Gpt56Sol model. |
| gpt-5.6-terra |
Gpt56Terra model. |
| gpt-5.6-luna |
Gpt56Luna model. |
| gpt-6-astra |
Gpt6Astra model. |
| gpt-6-sol |
Gpt6Sol model. |
| gpt-6-luna |
Gpt6Luna model. |
| gpt-6.1-sol |
Gpt61Sol model. |
AzureOpenAIVectorizerParameters
Specifies the parameters for connecting to the Azure OpenAI resource.
| Name | Type | Description |
|---|---|---|
| apiKey |
string |
API key of the designated Azure OpenAI resource. |
| authIdentity | SearchIndexerDataIdentity: |
The user-assigned managed identity used for outbound connections. |
| deploymentId |
string |
ID of the Azure OpenAI model deployment on the designated resource. |
| modelName |
The name of the embedding model that is deployed at the provided deploymentId path. |
|
| resourceUri |
string (uri) |
The resource URI of the Azure OpenAI resource. |
CorsOptions
Defines options to control Cross-Origin Resource Sharing (CORS) for an index.
| Name | Type | Description |
|---|---|---|
| allowedOrigins |
string[] |
The list of origins from which JavaScript code will be granted access to your index. Can contain a list of hosts of the form {protocol}://{fully-qualified-domain-name}[:{port#}], or a single '*' to allow all origins (not recommended). |
| maxAgeInSeconds |
integer (int64) |
The duration for which browsers should cache CORS preflight responses. Defaults to 5 minutes. |
ErrorAdditionalInfo
The resource management error additional info.
| Name | Type | Description |
|---|---|---|
| info |
searchservice.knowledgebases.createorupdate |
The additional info. |
| type |
string |
The additional info type. |
ErrorDetail
The error detail.
| Name | Type | Description |
|---|---|---|
| additionalInfo |
The error additional info. |
|
| code |
string |
The error code. |
| details |
The error details. |
|
| message |
string |
The error message. |
| target |
string |
The error target. |
ErrorResponse
Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
KnowledgeBase
Represents a knowledge base definition.
| Name | Type | Description |
|---|---|---|
| @odata.etag |
string |
The ETag of the knowledge base. |
| answerInstructions |
string |
Instructions considered by the knowledge base when generating answers. |
| corsOptions |
Options to control Cross-Origin Resource Sharing (CORS) for the knowledge base. |
|
| description |
string |
The description of the knowledge base. |
| encryptionKey |
A description of an encryption key that you create in Azure Key Vault. |
|
| knowledgeSources |
Knowledge sources referenced by this knowledge base. |
|
| models | KnowledgeBaseModel[]: |
Contains configuration options on how to connect to AI models. |
| name |
string |
The name of the knowledge base. |
| outputMode |
The output mode for the knowledge base. |
|
| retrievalInstructions |
string |
Instructions considered by the knowledge base when developing query plan. |
| retrievalReasoningEffort | KnowledgeRetrievalReasoningEffort: |
The retrieval reasoning effort configuration. |
| retrieveDefaults |
Persisted request-wide retrieve defaults for this knowledge base. These values apply to retrieve requests that omit the corresponding fields; request-time values take precedence when present. |
|
| tags |
object |
User-defined key-value pairs for categorizing the knowledge base and attributing its usage and costs. |
| tools |
Named retrieval tools, each limited to a subset of this knowledge base's sources. When configured, MCP advertises these tools in addition to the built-in knowledge_base_retrieve tool, which retrieves from the full knowledge base. Omitting tools or supplying an empty array in this API version clears existing tools. |
KnowledgeBaseAzureOpenAIModel
Specifies the Azure OpenAI resource used to do query planning.
| Name | Type | Description |
|---|---|---|
| azureOpenAIParameters |
Azure OpenAI parameters. |
|
| kind |
string:
azure |
The AI model to be used for query planning. |
KnowledgeBaseMicrosoftRetriever1Model
Specifies Microsoft Retriever 1 used for query planning and retrieval.
| Name | Type | Description |
|---|---|---|
| kind |
string:
microsoft |
The AI model to be used for query planning. |
KnowledgeBaseModelKind
The AI model to be used for query planning.
| Value | Description |
|---|---|
| azureOpenAI |
Use Azure Open AI models for query planning. |
| openAICompatible |
Use a customer-controlled OpenAI-compatible endpoint for knowledge base retrieval or knowledge source image verbalization. |
| microsoftRetriever1 |
Use Microsoft Retriever 1 for query planning and retrieval. |
KnowledgeBaseOpenAICompatibleModel
Specifies a customer-controlled OpenAI-compatible model for knowledge base retrieval or Minimal-mode knowledge source image verbalization. For retrieval, the model profile selects Chat Completions or Responses. Not supported for Standard/CU extraction or knowledge bases with Web knowledge sources.
| Name | Type | Description |
|---|---|---|
| kind |
string:
open |
The AI model to be used for query planning. |
| openAICompatibleParameters |
Connection and authentication parameters for the OpenAI-compatible endpoint. |
KnowledgeBaseOpenAICompatibleParameters
Connection parameters for an OpenAI-compatible Chat Completions or Responses endpoint. Creation requires exactly one of nonempty headers or managedIdentityAudience. Updates can omit headers to preserve credentials for an unchanged connection and model profile.
| Name | Type | Description |
|---|---|---|
| authIdentity | SearchIndexerDataIdentity: |
The user-assigned managed identity used to acquire a token for managedIdentityAudience. Omit to use the search service's system-assigned identity. Allowed only with managedIdentityAudience. |
| headers |
object (password) |
Nonempty stored HTTP headers for endpoint authentication. Both names and values are secret and are never returned in responses. Empty maps are invalid. Mutually exclusive with managedIdentityAudience and authIdentity. On update, omitted headers are preserved only on the same resource and model binding when the exact endpoint, model profile, and authentication identity are unchanged; otherwise, supply fresh credentials. |
| managedIdentityAudience |
string |
The bare canonical application GUID of the customer's third-party Microsoft Entra application for managed identity authentication. Do not include an api:// prefix or /.default suffix. Mutually exclusive with headers. |
| modelName |
A supported chat model name that determines Search's capabilities and limits. For knowledge source image verbalization, this is sent as the model selector in the request body; the URI path selects Chat Completions or Responses independently of this name. For knowledge base retrieval, GPT-6 model profiles use Responses and existing model profiles use Chat Completions; the endpoint must support the selected protocol, including stateless tool continuation for Responses. The retrieval request body omits model; the URI or gateway selects the actual model and supplies any required provider model identifier. Embedding models and arbitrary provider protocols are not supported. |
|
| uri |
string (uri) |
The complete HTTPS POST URL, including path and query parameters. Sent unchanged without appending a path or API version; redirects are not followed. For knowledge base retrieval, the endpoint must accept the model profile's Chat Completions or Responses protocol. For knowledge source image verbalization, the URI path must end in /chat/completions or /responses; query parameters do not select the protocol. |
KnowledgeBaseRetrieveDefaults
Persisted request-wide defaults for knowledge base retrieve requests. Each value provides the default for the matching retrieve-request field; service defaults apply when unset, and request-time values take precedence when present.
| Name | Type | Description |
|---|---|---|
| maxOutputDocuments |
integer (int32) |
The default maximum number of documents in the retrieve output. |
| maxOutputSizeInTokens |
integer (int32) |
The default maximum size, in tokens, of the content in the retrieve output. |
| maxRuntimeInSeconds |
integer (int32) |
The default maximum runtime in seconds for a retrieve request. |
KnowledgeBaseTool
A named retrieval tool with a customer-provided description and a subset of its knowledge base's sources.
| Name | Type | Description |
|---|---|---|
| description |
string minLength: 1maxLength: 1024 |
A nonempty description of when to use the tool, at most 1024 characters. Advertised verbatim in the MCP catalog. |
| knowledgeSources |
A nonempty list of unique source references. Each source must belong to the knowledge base. Different tools may reference the same source. |
|
| name |
string minLength: 2maxLength: 64 pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])$ |
The unique, case-sensitive tool name. Contains 2 to 64 lowercase ASCII letters, digits, or hyphens, with no leading or trailing hyphen. |
| retrievalReasoningEffort | KnowledgeRetrievalReasoningEffort: |
Overrides the knowledge base's reasoning effort for this tool. Explicit retrieve-request values take precedence. |
| retrieveDefaults |
Retrieve defaults that override the knowledge base's defaults for this tool. Explicit retrieve-request values take precedence. |
KnowledgeBaseToolKnowledgeSourceReference
A reference to an existing knowledge source and a selected subset of persisted retrieval defaults, not the complete request-time parameter model. The referenced source determines the kind; incompatible defaults are rejected when the knowledge base is saved. Explicit retrieve-request values take precedence, except filters are combined with AND.
| Name | Type | Description |
|---|---|---|
| alwaysQuerySource |
boolean |
Whether the source must be queried. Not supported for MCP server sources. An explicit request exclusion takes precedence. |
| failOnError |
boolean |
Whether retrieval should fail if this source encounters an error. |
| filterAddOn |
string |
An additional OData filter for search index sources. Rejected for unsupported source kinds when the knowledge base is saved. Combined with source and request filters using AND. |
| maxOutputDocuments |
integer (int32) minimum: 50maximum: 200 |
The maximum number of documents retrieved from this source, between 50 and 200. |
| name |
string minLength: 1 |
The name of a knowledge source in the knowledge base. |
| rerankerThreshold |
number (float) |
The minimum reranker score for returned documents. Requires reranking to be enabled. |
KnowledgeRetrievalAutoReasoningEffort
Automatically select the reasoning effort during retrieval. The service seeds every request at the cheapest tier and escalates only as far as needed, up to the service's maximum available tier.
| Name | Type | Description |
|---|---|---|
| kind |
string:
auto |
The kind of reasoning effort. |
KnowledgeRetrievalLowReasoningEffort
Run knowledge retrieval with low reasoning effort.
| Name | Type | Description |
|---|---|---|
| kind |
string:
low |
The kind of reasoning effort. |
KnowledgeRetrievalMediumReasoningEffort
Run knowledge retrieval with medium reasoning effort.
| Name | Type | Description |
|---|---|---|
| kind |
string:
medium |
The kind of reasoning effort. |
KnowledgeRetrievalMinimalReasoningEffort
Run knowledge retrieval with minimal reasoning effort.
| Name | Type | Description |
|---|---|---|
| kind |
string:
minimal |
The kind of reasoning effort. |
KnowledgeRetrievalOutputMode
The output configuration for this retrieval.
| Value | Description |
|---|---|
| extractiveData |
Return data from the knowledge sources directly without generative alteration. |
| answerSynthesis |
Synthesize an answer for the response payload. |
KnowledgeRetrievalReasoningEffortKind
The amount of effort to use during retrieval.
| Value | Description |
|---|---|
| minimal |
Does not perform any source selections, query planning, or iterative search. |
| low |
Use low reasoning during retrieval. |
| medium |
Use a moderate amount of reasoning during retrieval. |
| auto |
Automatically select the reasoning effort during retrieval, escalating from the cheapest tier only as far as needed. |
KnowledgeSourceReference
Reference to a knowledge source.
| Name | Type | Description |
|---|---|---|
| enableFreshness |
boolean |
Indicates whether freshness-aware retrieval should be enabled for this knowledge source. When true, a freshness scoring profile is applied during retrieval to bias results toward newer documents. |
| enableImageServing |
boolean |
Indicates whether image serving should be enabled for this knowledge source. When true, images extracted during ingestion are delivered to downstream models at query time. |
| name |
string |
The name of the knowledge source. |
Prefer
For HTTP PUT requests, instructs the service to return the created/updated resource on success.
| Value | Description |
|---|---|
| return=representation |
SearchIndexerDataNoneIdentity
Clears the identity property of a datasource.
| Name | Type | Description |
|---|---|---|
| @odata.type |
string:
#Microsoft. |
A URI fragment specifying the type of identity. |
SearchIndexerDataUserAssignedIdentity
Specifies the identity for a datasource to use.
| Name | Type | Description |
|---|---|---|
| @odata.type |
string:
#Microsoft. |
A URI fragment specifying the type of identity. |
| federatedIdentityClientId |
string |
Multi-tenant User-Assigned Managed Identity Support: The client id of the multi-tentant App that has been configured to federate with the user-assigned managed identity. |
| userAssignedIdentity |
string |
The fully qualified Azure resource Id of a user assigned managed identity typically in the form "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" that should have been assigned to the search service. |
SearchResourceEncryptionKey
A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest, such as indexes and synonym maps.
| Name | Type | Default value | Description |
|---|---|---|---|
| accessCredentials.applicationId |
string |
An AAD Application ID that was granted the required access permissions to the Azure Key Vault that is to be used when encrypting your data at rest. The Application ID should not be confused with the Object ID for your AAD Application. |
|
| accessCredentials.applicationSecret |
string |
The authentication key of the specified AAD application. |
|
| identity | SearchIndexerDataIdentity: |
An explicit managed identity to use for this encryption key. If not specified and the access credentials property is null, the system-assigned managed identity is used. On update to the resource, if the explicit identity is unspecified, it remains unchanged. If "none" is specified, the value of this property is cleared. |
|
| isServiceLevelKey |
boolean |
False |
An optional value indicating whether this key is a service-level key. Default is false. |
| keyVaultKeyName |
string |
The name of your Azure Key Vault key to be used to encrypt your data at rest. |
|
| keyVaultKeyVersion |
string |
The version of your Azure Key Vault key to be used to encrypt your data at rest. |
|
| keyVaultUri |
string |
The URI of your Azure Key Vault, also referred to as DNS name, that contains the key to be used to encrypt your data at rest. An example URI might be |