Knowledge Bases - Get

Service:: Search Service

API Version:: 2025-11-01-preview

Retrieves an knowledge base definition.

GET {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2025-11-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The endpoint URL of the search service.
knowledgeBaseName	path	True	string	The name of the knowledge base to retrieve.
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.

Responses

Name	Type	Description
200 OK	KnowledgeBase
Other Status Codes	ErrorResponse	Error response.

Examples

SearchServiceGetKnowledgeBase

Sample request

HTTP

GET https://previewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2025-11-01-preview

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": "<redacted>",
        "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
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: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	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: 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	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: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort

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: 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 - Get

URI Parameters

Request Header

Responses

Examples

SearchServiceGetKnowledgeBase

Sample request

Sample response

Definitions

AzureActiveDirectoryApplicationCredentials

AzureOpenAIEmbeddingSkill

AzureOpenAIModelName

AzureOpenAIParameters

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

InputFieldMappingEntry

KnowledgeBase

KnowledgeBaseAzureOpenAIModel

KnowledgeBaseModelKind

KnowledgeRetrievalLowReasoningEffort

KnowledgeRetrievalMediumReasoningEffort

KnowledgeRetrievalMinimalReasoningEffort

KnowledgeRetrievalOutputMode

KnowledgeRetrievalReasoningEffortKind

KnowledgeSourceReference

OutputFieldMappingEntry

SearchIndexerDataNoneIdentity

SearchIndexerDataUserAssignedIdentity

SearchResourceEncryptionKey