Azure AI Search Data Sources API

openapi: 3.2.0
info:
  title: Azure AI Search Datasources API
  version: '2026-10-01'
  description: Client that can be used to manage and query indexes and documents, as well as manage other resources, on a search service.
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- ApiKeyAuth: []
- OAuth2Auth:
  - https://search.azure.com/.default
tags:
- name: Data Sources
paths:
  /datasources:
    get:
      operationId: DataSources_List
      description: Lists all datasources available for a search service.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      - name: Accept
        in: header
        description: The Accept header.
        required: false
        x-ms-enum:
          modelAsString: false
        x-ms-client-name: accept
        schema:
          type: string
          enum:
          - application/json;odata.metadata=minimal
      - name: $select
        in: query
        description: Selects which top-level properties to retrieve. Specified as a comma-separated list of JSON property names, or '*' for all properties. The default is all properties.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: search
        in: query
        description: A string used to narrow down the listing so that fewer results need to be paged through. If omitted or an empty string is passed, no narrowing is applied.
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        description: The maximum number of items to return in a single page. The server enforces a maximum; if omitted, the server determines a suitable default.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 3000
          minimum: 1
      - name: searchType
        in: query
        description: Specifies how the search parameter is interpreted. Currently only 'prefix' is supported.
        required: false
        x-ms-enum:
          name: ListingSearchType
          modelAsString: true
          values:
          - name: Prefix
            value: prefix
            description: Matches items whose name starts with the value of the search parameter.
        schema:
          type: string
          enum:
          - prefix
          default: prefix
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataSourcesResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
      tags:
      - Data Sources
      summary: Data sources list
      x-summary-source: derived
    post:
      operationId: DataSources_Create
      description: Creates a new datasource.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      - name: Accept
        in: header
        description: The Accept header.
        required: false
        x-ms-enum:
          modelAsString: false
        x-ms-client-name: accept
        schema:
          type: string
          enum:
          - application/json;odata.metadata=minimal
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIndexerDataSource'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchIndexerDataSource'
        description: The definition of the datasource to create.
        required: true
      tags:
      - Data Sources
      summary: Data sources create
      x-summary-source: derived
components:
  schemas:
    AzureActiveDirectoryApplicationCredentials:
      type: object
      description: Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.
      properties:
        applicationId:
          type: string
          description: 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:
          type: string
          description: The authentication key of the specified AAD application.
      required:
      - applicationId
    DataDeletionDetectionPolicy:
      type: object
      description: Base type for data deletion detection policies.
      properties:
        '@odata.type':
          type: string
          description: The discriminator for derived types.
      discriminator:
        propertyName: '@odata.type'
      required:
      - '@odata.type'
    IndexerPermissionOption:
      type: string
      description: Options with various types of permission data to index.
      enum:
      - userIds
      - groupIds
      - rbacScope
      x-ms-enum:
        name: IndexerPermissionOption
        modelAsString: true
        values:
        - name: UserIds
          value: userIds
          description: Indexer to ingest ACL userIds from data source to index.
        - name: GroupIds
          value: groupIds
          description: Indexer to ingest ACL groupIds from data source to index.
        - name: RbacScope
          value: rbacScope
          description: Indexer to ingest Azure RBAC scope from data source to index.
    ErrorDetail:
      type: object
      description: The error detail.
      properties:
        code:
          type: string
          description: The error code.
          readOnly: true
        message:
          type: string
          description: The error message.
          readOnly: true
        target:
          type: string
          description: The error target.
          readOnly: true
        details:
          type: array
          description: The error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          readOnly: true
        additionalInfo:
          type: array
          description: The error additional info.
          items:
            $ref: '#/components/schemas/ErrorAdditionalInfo'
          readOnly: true
    ListDataSourcesResult:
      type: object
      description: Response from a List Datasources request. If successful, it includes the full definitions of all datasources.
      properties:
        value:
          type: array
          description: The datasources in the Search service.
          items:
            $ref: '#/components/schemas/SearchIndexerDataSource'
          readOnly: true
        '@odata.nextLink':
          type: string
          description: The URL that can be used to fetch the next set of results.
          readOnly: true
      required:
      - value
    SearchIndexerDataIdentity:
      type: object
      description: Abstract base type for data identities.
      properties:
        '@odata.type':
          type: string
          description: A URI fragment specifying the type of identity.
      discriminator:
        propertyName: '@odata.type'
      required:
      - '@odata.type'
    SearchIndexerDataSource:
      type: object
      description: Represents a datasource definition, which can be used to configure an indexer.
      properties:
        name:
          type: string
          description: The name of the datasource.
        description:
          type: string
          description: The description of the datasource.
        type:
          $ref: '#/components/schemas/SearchIndexerDataSourceType'
          description: The type of the datasource.
        credentials:
          $ref: '#/components/schemas/DataSourceCredentials'
          description: Credentials for the datasource.
          x-ms-client-flatten: true
        container:
          $ref: '#/components/schemas/SearchIndexerDataContainer'
          description: The data container for the datasource.
        identity:
          $ref: '#/components/schemas/SearchIndexerDataIdentity'
          description: An explicit managed identity to use for this datasource. If not specified and the connection string is a managed identity, the system-assigned managed identity is used. If not specified, the value remains unchanged. If "none" is specified, the value of this property is cleared.
        indexerPermissionOptions:
          type:
          - array
          - 'null'
          description: Ingestion options with various types of permission data.
          items:
            $ref: '#/components/schemas/IndexerPermissionOption'
        dataChangeDetectionPolicy:
          $ref: '#/components/schemas/DataChangeDetectionPolicy'
          description: The data change detection policy for the datasource.
        dataDeletionDetectionPolicy:
          $ref: '#/components/schemas/DataDeletionDetectionPolicy'
          description: The data deletion detection policy for the datasource.
        '@odata.etag':
          type: string
          description: The ETag of the data source.
          x-ms-client-name: eTag
        encryptionKey:
          $ref: '#/components/schemas/SearchResourceEncryptionKey'
          description: 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 datasource definition when you want full assurance that no one, not even Microsoft, can decrypt your data source definition. Once you have encrypted your data source 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 datasource 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.
      required:
      - name
      - type
      - credentials
      - container
    DataSourceCredentials:
      type: object
      description: Represents credentials that can be used to connect to a datasource.
      properties:
        connectionString:
          type: string
          description: The connection string for the datasource. Set to `<unchanged>` (with brackets) if you don't want the connection string updated. Set to `<redacted>` if you want to remove the connection string value from the datasource.
    SearchIndexerDataContainer:
      type: object
      description: Represents information about the entity (such as Azure SQL table or CosmosDB collection) that will be indexed.
      properties:
        name:
          type: string
          description: The name of the table or view (for Azure SQL data source) or collection (for CosmosDB data source) that will be indexed.
        query:
          type: string
          description: A query that is applied to this data container. The syntax and meaning of this parameter is datasource-specific. Not supported by Azure SQL datasources.
      required:
      - name
    DataChangeDetectionPolicy:
      type: object
      description: Base type for data change detection policies.
      properties:
        '@odata.type':
          type: string
          description: The discriminator for derived types.
      discriminator:
        propertyName: '@odata.type'
      required:
      - '@odata.type'
    ErrorResponse:
      type: object
      description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: The error object.
    SearchResourceEncryptionKey:
      type: object
      description: 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.
      properties:
        keyVaultKeyName:
          type: string
          description: The name of your Azure Key Vault key to be used to encrypt your data at rest.
        keyVaultKeyVersion:
          type: string
          description: The version of your Azure Key Vault key to be used to encrypt your data at rest.
        keyVaultUri:
          type: string
          description: 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`.
        accessCredentials:
          $ref: '#/components/schemas/AzureActiveDirectoryApplicationCredentials'
          description: Optional Azure Active Directory credentials used for accessing your Azure Key Vault. Not required if using managed identity instead.
          x-ms-client-flatten: true
        identity:
          $ref: '#/components/schemas/SearchIndexerDataIdentity'
          description: 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.
      required:
      - keyVaultKeyName
      - keyVaultUri
    ErrorAdditionalInfo:
      type: object
      description: The resource management error additional info.
      properties:
        type:
          type: string
          description: The additional info type.
          readOnly: true
        info:
          type: object
          description: The additional info.
          additionalProperties: {}
          readOnly: true
    SearchIndexerDataSourceType:
      type: string
      description: Defines the type of a datasource.
      enum:
      - azuresql
      - cosmosdb
      - azureblob
      - azuretable
      - mysql
      - adlsgen2
      - onelake
      - sharepoint
      x-ms-enum:
        name: SearchIndexerDataSourceType
        modelAsString: true
        values:
        - name: AzureSql
          value: azuresql
          description: Indicates an Azure SQL datasource.
        - name: CosmosDb
          value: cosmosdb
          description: Indicates a CosmosDB datasource.
        - name: AzureBlob
          value: azureblob
          description: Indicates an Azure Blob datasource.
        - name: AzureTable
          value: azuretable
          description: Indicates an Azure Table datasource.
        - name: MySql
          value: mysql
          description: Indicates a MySql datasource.
        - name: AdlsGen2
          value: adlsgen2
          description: Indicates an ADLS Gen2 datasource.
        - name: OneLake
          value: onelake
          description: Indicates a Microsoft Fabric OneLake datasource.
        - name: SharePoint
          value: sharepoint
          description: Indicates a SharePoint datasource.
  parameters:
    Azure.Core.ClientRequestIdHeader:
      name: x-ms-client-request-id
      in: header
      description: An opaque, globally-unique, client-generated string identifier for the request.
      required: false
      x-ms-parameter-location: method
      x-ms-client-name: clientRequestId
      schema:
        type: string
        format: uuid
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: api-key
      in: header
    OAuth2Auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://search.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: The endpoint URL of the search service.
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true
x-ms-paths:
  /indexes?_overload=listWithSelectedProperties:
    get:
      operationId: Indexes_ListWithSelectedProperties
      description: Lists all indexes available for a search service.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      - name: Accept
        in: header
        description: The Accept header.
        required: false
        type: string
        enum:
        - application/json;odata.metadata=minimal
        x-ms-enum:
          modelAsString: false
        x-ms-client-name: accept
      - name: $select
        in: query
        description: Selects which top-level properties to retrieve. Specified as a comma-separated list of JSON property names, or '*' for all properties. The default is all properties.
        required: false
        type: array
        items:
          type: string
        collectionFormat: csv
      - name: search
        in: query
        description: A string used to narrow down the listing so that fewer results need to be paged through. If omitted or an empty string is passed, no narrowing is applied.
        required: false
        type: string
      - name: pageSize
        in: query
        description: The maximum number of items to return in a single page. The server enforces a maximum; if omitted, the server determines a suitable default.
        required: false
        type: integer
        format: int32
        minimum: 1
        maximum: 3000
      - name: searchType
        in: query
        description: Specifies how the search parameter is interpreted. Currently only 'prefix' is supported.
        required: false
        type: string
        default: prefix
        enum:
        - prefix
        x-ms-enum:
          name: ListingSearchType
          modelAsString: true
          values:
          - name: Prefix
            value: prefix
            description: Matches items whose name starts with the value of the search parameter.
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/ListIndexesSelectedResult'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
  /knowledgebases('{knowledgeBaseName}')/retrieve?_overload=retrieveStream:
    post:
      operationId: KnowledgeRetrieval_RetrieveStream
      description: 'Retrieves relevant data from backing stores and streams progress and results as server-sent

        events.


        Process the response incrementally using server-sent event framing. Each event contains an

        event name and a JSON-encoded data payload. The stream ends with either a `response.completed`

        event or an `error` event. OpenAPI 2.0 represents the response body as a string, so generated

        clients may expose the raw response without typed event parsing. Do not deserialize the

        complete response body as a single JSON document.'
      produces:
      - text/event-stream
      - application/json
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: Accept
        in: header
        description: The Accept header.
        required: true
        type: string
        enum:
        - text/event-stream
        x-ms-enum:
          modelAsString: false
        x-ms-client-name: accept
      - name: knowledgeBaseName
        in: path
        description: The name of the knowledge base.
        required: true
        type: string
      - name: x-ms-query-source-authorization
        in: header
        description: Token identifying the user for which the query is being executed. This token is used to enforce security restrictions on documents.
        required: false
        type: string
        format: password
        x-ms-client-name: querySourceAuthorization
        x-ms-secret: true
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      - name: retrievalRequest
        in: body
        description: The retrieval request to process.
        required: true
        schema:
          $ref: '#/components/schemas/KnowledgeBaseRetrievalRequest'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            type: string
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/ErrorResponse'