Share via

Knowledge Bases - Create

Service:
Search Service
API Version:
2025-11-01-preview

Creates a new knowledge base.

POST {endpoint}/knowledgebases?api-version=2025-11-01-preview

URI Parameters

Name In Required Type Description
endpoint
 path True

string

The endpoint URL of the search service.
api-version
 query True

string

Client Api Version.

Request Header

Name Required Type Description
x-ms-client-request-id

string (uuid)

The tracking ID sent with the request to help with debugging.

Request Body

Name Required Type Description
knowledgeSources True

KnowledgeSourceReference[]

name True

string

The name of the knowledge knowledge base.
@odata.etag

string

The ETag of the knowledge base.
answerInstructions

string

Instructions considered by the knowledge 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. This key is used to provide an additional level of encryption-at-rest for your knowledge base definition when you want full assurance that no one, not even Microsoft, can decrypt them. Once you have encrypted your knowledge base definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your knowledge base definition will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.
models KnowledgeBaseModel[]:

KnowledgeBaseAzureOpenAIModel[]

Contains configuration options on how to connect to AI models.
outputMode

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.
retrievalInstructions

string

Instructions considered by the knowledge knowledge base when developing query plan.
retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

Responses

Name Type Description
201 Created

KnowledgeBase

Successfully created an knowledge base
Other Status Codes

ErrorResponse

Error response.

Examples

SearchServiceCreateKnowledgeBase

Sample request

POST https://previewexampleservice.search.windows.net/knowledgebases?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-4.1-nano"
      },
      "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:
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-4.1-nano"
      }
    }
  ],
  "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
AzureActiveDirectoryApplicationCredentials

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.
AzureOpenAIEmbeddingSkill

Allows you to generate a vector embedding for a given text input using the Azure OpenAI resource.
AzureOpenAIModelName

The Azure Open AI model name that will be called.
AzureOpenAIParameters

Specifies the parameters for connecting to the Azure OpenAI resource.
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Error response
InputFieldMappingEntry

Input field mapping for a skill.
KnowledgeBase
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
OutputFieldMappingEntry

Output field mapping for a skill.
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.

AzureActiveDirectoryApplicationCredentials

Object

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.

Name Type Description
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.
applicationSecret

string

The authentication key of the specified AAD application.

AzureOpenAIEmbeddingSkill

Object

Allows you to generate a vector embedding for a given text input using the Azure OpenAI resource.

Name Type Description
@odata.type string:

#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

A URI fragment specifying the type of skill.
apiKey

string

API key of the designated Azure OpenAI resource.
authIdentity SearchIndexerDataIdentity:

The user-assigned managed identity used for outbound connections.
context

string

Represents the level at which operations take place, such as the document root or document content (for example, /document or /document/content). The default is /document.
deploymentId

string

ID of the Azure OpenAI model deployment on the designated resource.
description

string

The description of the skill which describes the inputs, outputs, and usage of the skill.
dimensions

integer (int32)

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.
inputs

InputFieldMappingEntry[]

Inputs of the skills could be a column in the source data set, or the output of an upstream skill.
modelName

AzureOpenAIModelName

The name of the embedding model that is deployed at the provided deploymentId path.
name

string

The name of the skill which uniquely identifies it within the skillset. A skill with no name defined will be given a default name of its 1-based index in the skills array, prefixed with the character '#'.
outputs

OutputFieldMappingEntry[]

The output of a skill is either a field in a search index, or a value that can be consumed as an input by another skill.
resourceUri

string (uri)

The resource URI of the Azure OpenAI resource.

AzureOpenAIModelName

Enumeration

The Azure Open AI model name that will be called.

Value Description
text-embedding-ada-002
text-embedding-3-large
text-embedding-3-small
gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-mini
gpt-4.1-nano
gpt-5
gpt-5-mini
gpt-5-nano

AzureOpenAIParameters

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:

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

object

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

Error response

Name Type Description
error

ErrorDetail

The error object.

InputFieldMappingEntry

Object

Input field mapping for a skill.

Name Type Description
inputs

InputFieldMappingEntry[]

The recursive inputs used when creating a complex type.
name

string

The name of the input.
source

string

The source of the input.
sourceContext

string

The source context used for selecting recursive inputs.

KnowledgeBase

Object
Name Type Description
@odata.etag

string

The ETag of the knowledge base.
answerInstructions

string

Instructions considered by the knowledge 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. This key is used to provide an additional level of encryption-at-rest for your knowledge base definition when you want full assurance that no one, not even Microsoft, can decrypt them. Once you have encrypted your knowledge base definition, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your knowledge base definition will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.
knowledgeSources

KnowledgeSourceReference[]

models KnowledgeBaseModel[]:

KnowledgeBaseAzureOpenAIModel[]

Contains configuration options on how to connect to AI models.
name

string

The name of the knowledge knowledge base.
outputMode

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.
retrievalInstructions

string

Instructions considered by the knowledge knowledge base when developing query plan.
retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

KnowledgeBaseAzureOpenAIModel

Object

Specifies the Azure OpenAI resource used to do query planning.

Name Type Description
azureOpenAIParameters AzureOpenAIParameters:

AzureOpenAIEmbeddingSkill

Contains the parameters specific to Azure OpenAI model endpoint.
kind string:

azureOpenAI

The type of AI model.

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
Name Type Description
name

string

The name of the knowledge source.

OutputFieldMappingEntry

Object

Output field mapping for a skill.

Name Type Description
name

string

The name of the output defined by the skill.
targetName

string

The target name of the output. It is optional and default to name.

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

AzureActiveDirectoryApplicationCredentials

Optional Azure Active Directory credentials used for accessing your Azure Key Vault. Not required if using managed identity instead.
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.
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.