Knowledge Bases - Create Or Update

Service:: Search Service

API Version:: 2025-11-01-preview

Creates a new knowledge base or updates a knowledge base if it already exists.

PUT https:///knowledgebases('{knowledgeBaseName}')?api-version=2025-11-01-preview

URI Parameters

Name	In	Required	Type	Description
knowledgeBaseName	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
Accept	True	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	Prefer	For HTTP PUT requests, instructs the service to return the created/updated resource on success.
x-ms-client-request-id		string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name	Required	Type	Description
knowledgeSources	True	KnowledgeSourceReference[]	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.
description		string	The description of the knowledge base.
encryptionKey		SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault.
models		KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contains configuration options on how to connect to AI models.
outputMode		KnowledgeRetrievalOutputMode	The output mode for the knowledge base.
retrievalInstructions		string	Instructions considered by the knowledge base when developing query plan.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	The retrieval reasoning effort configuration.

Responses

Name	Type	Description
200 OK	KnowledgeBase	The request has succeeded.
201 Created	KnowledgeBase	The request has succeeded and a new resource has been created as a result.
Other Status Codes	ErrorResponse	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

HTTP

PUT https:///knowledgebases('base-preview-test')?api-version=2025-11-01-preview





{
  "name": "base-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      },
      "kind": "azureOpenAI"
    }
  ],
  "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.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis."
}

Sample response

Status code:: 200

{
  "@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",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Status code:: 201

{
  "@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",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Definitions

Name	Description
Accept	The Accept header.
AzureOpenAIModelName	The Azure Open AI model name that will be called.
AzureOpenAIVectorizerParameters	Specifies the parameters for connecting to the Azure OpenAI resource.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
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.).
KnowledgeBase	Represents a knowledge base definition.
KnowledgeBaseAzureOpenAIModel	Specifies the Azure OpenAI resource used to do query planning.
KnowledgeBaseModelKind	The AI model to be used for query planning.
KnowledgeRetrievalLowReasoningEffort	Run knowledge retrieval with low reasoning effort.
KnowledgeRetrievalMediumReasoningEffort	Run knowledge retrieval with medium reasoning effort.
KnowledgeRetrievalMinimalReasoningEffort	Run knowledge retrieval with minimal reasoning effort.
KnowledgeRetrievalOutputMode	The output configuration for this retrieval.
KnowledgeRetrievalReasoningEffortKind	The amount of effort to use during retrieval.
KnowledgeSourceReference	Reference to a knowledge source.
Prefer	For HTTP PUT requests, instructs the service to return the created/updated resource on success.
SearchIndexerDataNoneIdentity	Clears the identity property of a datasource.
SearchIndexerDataUserAssignedIdentity	Specifies the identity for a datasource to use.
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.

Accept

Enumeration

The Accept header.

Value	Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

Enumeration

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.

AzureOpenAIVectorizerParameters

Object

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: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	The user-assigned managed identity used for outbound connections.
deploymentId	string	ID of the Azure OpenAI model deployment on the designated resource.
modelName	AzureOpenAIModelName	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.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info		The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

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	ErrorDetail	The error object.

KnowledgeBase

Object

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.
description	string	The description of the knowledge base.
encryptionKey	SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault.
knowledgeSources	KnowledgeSourceReference[]	Knowledge sources referenced by this knowledge base.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	Contains configuration options on how to connect to AI models.
name	string	The name of the knowledge base.
outputMode	KnowledgeRetrievalOutputMode	The output mode for the knowledge base.
retrievalInstructions	string	Instructions considered by the knowledge base when developing query plan.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	The retrieval reasoning effort configuration.

KnowledgeBaseAzureOpenAIModel

Object

Specifies the Azure OpenAI resource used to do query planning.

Name	Type	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parameters.
kind	string: azureOpenAI	The AI model to be used for query planning.

KnowledgeBaseModelKind

Enumeration

The AI model to be used for query planning.

Value	Description
azureOpenAI	Use Azure Open AI models for query planning.

KnowledgeRetrievalLowReasoningEffort

Object

Run knowledge retrieval with low reasoning effort.

Name	Type	Description
kind	string: low	The kind of reasoning effort.

KnowledgeRetrievalMediumReasoningEffort

Object

Run knowledge retrieval with medium reasoning effort.

Name	Type	Description
kind	string: medium	The kind of reasoning effort.

KnowledgeRetrievalMinimalReasoningEffort

Object

Run knowledge retrieval with minimal reasoning effort.

Name	Type	Description
kind	string: minimal	The kind of reasoning effort.

KnowledgeRetrievalOutputMode

Enumeration

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

Enumeration

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.

KnowledgeSourceReference

Object

Reference to a knowledge source.

Name	Type	Description
name	string	The name of the knowledge source.

Prefer

Enumeration

For HTTP PUT requests, instructs the service to return the created/updated resource on success.

Value	Description
return=representation

SearchIndexerDataNoneIdentity

Object

Clears the identity property of a datasource.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	A URI fragment specifying the type of identity.

SearchIndexerDataUserAssignedIdentity

Object

Specifies the identity for a datasource to use.

Name	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	A URI fragment specifying the type of 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

Object

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	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: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	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.
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 `https://my-keyvault-name.vault.azure.net`.

Share via

Knowledge Bases - Create Or Update

URI Parameters

Request Header

Request Body

Responses

Security

api-key

OAuth2Auth

Scopes

Examples

SearchServiceCreateOrUpdateKnowledgeBase

Sample request

Sample response

Definitions

Accept

AzureOpenAIModelName

AzureOpenAIVectorizerParameters

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

KnowledgeBase

KnowledgeBaseAzureOpenAIModel

KnowledgeBaseModelKind

KnowledgeRetrievalLowReasoningEffort

KnowledgeRetrievalMediumReasoningEffort

KnowledgeRetrievalMinimalReasoningEffort

KnowledgeRetrievalOutputMode

KnowledgeRetrievalReasoningEffortKind

KnowledgeSourceReference

Prefer

SearchIndexerDataNoneIdentity

SearchIndexerDataUserAssignedIdentity

SearchResourceEncryptionKey