REST API versions (Azure AI Search)

This article lists the current and past versions of the Search REST APIs for Azure AI Search.

Versioned API docs

REST API docs are now versioned. When you open an API reference page, a version selector appears above the table of contents.

  1. Expand Reference > Data Plane.

  2. Select an API reference page.

  3. Choose an API version from the dropdown filter on the top left.

    Screenshot of the version selector.

Stable versions

API version Specification API updates
2023-11-01 (Latest) Swagger specification Release note
2020-06-30 Swagger specification Release note
2019-05-06 Swagger specification Adds complex types.
2017-11-11 Swagger specification Adds skillsets and AI enrichment.
2016-09-01 Swagger specification Adds indexers.
2015-02-28 Unsupported after 10-10-2020 First generally available release.

Preview versions

Preview versions are released to test new functionality, gather feedback, and discover and fix issues. Preview APIs are available under Supplemental Terms of Use for Microsoft Azure Previews.

API version Specification API updates
2023-10-01-Preview Swagger specification Release note
2023-07-01-Preview Swagger specification Release note
2021-04-30-Preview Swagger specification Release note
2020-06-30-Preview Swagger specification Release note
2019-05-06-Preview Swagger specification Release note
2017-11-11-Preview Swagger specification Preview version associated with stable version.
2016-09-01-Preview Swagger specification Preview version associated with stable version.
2015-02-28-Preview Unsupported after 10-10-2020 Preview version associated with stable version.
2014-10-20-Preview Unsupported after 10-10-2020 Second public preview.
2014-07-31-Preview Unsupported after 10-10-2020 First public preview.

Release notes

2023-11-01

This version provides generally available features, including:

  • Semantic ranking in Search Post requests.
  • Vector search indexing in Create or Update Index requests, and vector queries in Search Post requests.

2023-10-01-Preview

This version includes all features introduced in previous previews, plus additions and modifications to vector search APIs. Updates to the vector search APIs are a breaking change from 2023-07-01-Preview. See Add vector fields and Create a vector query for migration help.

If you plan to use the new prefiltering capability, you must use an index created after 2023-10-01.

Create or Update Index:

  • vectorSearch has definitions for algorithms, profiles, and vectorizers:

    • algorithms continues to support hnsw and now also supports eknn, in reference to Hierarchical Navigable Small World (HNSW) and exhaustive K-nearest neighbors (eKNN). Within the algorithm section, you can define multiple named combinations of HNSW and eKNN parameters. This replaces algorithmConfigurations within the vectorSearch property in 2023-07-01-Preview.

    • profiles is a new definition that specifies the algorithm configuration. For example, suppose you have algorithm configurations named HNSW-1, HSNW-2, eKNN-1. A profile might specify HNSW-1.

    • vectorizers is visible, but currently ignored.

  • On vector fields, vectorSearchProfile replaces vectorSearchConfiguration. The vectorSearchProfile property specifies which vector search profile to use on the field.

  • On indexes created prior to this API version, upon calling 2023-10-01-Preview API, in your request, you must change the field to specify a vectorSearchProfile as long as the profile specifies the exact same algorithm previously specified in vectorSearchConfiguration. For example, if the existing field definition specifies "vectorSearchConfiguration": "myHnsw", you must replace it with "vectorSearchProfile": "your profile name", and the profile must be defined to reference the same "algorithm": "myHnsw".

Search Documents:

  • vectorQueries replaces vectors in 2023-07-01-Preview

  • vectorQueries.vectors replaces vectors.values in 2023-07-01-Preview.

  • The vector query is now a polymorphic structure. kind must be specified to denote the type of vector query being requested.

    • "kind": "vector" means the query is a vector, so the caller should have already vectorized the search query string into a vector embedding.
  • "exhaustive": "true" is a new property specifies whether to do an exhaustive (brute-force) k-nearest neighbor search across all vectors within the vector index.

  • vectorFilterMode is a new parameter for specifying prefiltering (default for indexes created after 2023-10-01) or postfiltering (default on previous indexes) in the query.

2023-07-01-Preview

This version includes all features introduced in previous previews, plus vector search support:

  • In the search index, assign Collection(Edm.Single) data type on fields that contain an array of single-precision floating point numbers. This is the data type for the new vector search capability, used to store one generated embedding per document field. Also in the search index, specify vector configuration properties. See Create or Update Index for these APIs.

  • Indexing workloads are updated to accept vector data. See Add, Update, or Delete Documents.

  • Query parameters for vector search. See Search Documents for these parameters.

  • Get Service Statistics: returns vector index quota and usage for the service.

  • Get Index Statistics: returns vector index quota and usage for the search index.

2021-04-30-Preview

This preview version includes all of the features introduced in 2020-06-30-Preview, plus additions to the following APIs:

2020-06-30

This version provides generally available features, including:

  • Azure role-based access control for data plane operations
  • Relevance scoring (BM25)
  • Knowledge stores
  • Indexer data source for Azure Data Lake Storage (ADLS) Gen2
  • Custom Entity Lookup skill
  • Indexers running under a system or user-managed identity via Microsoft Entra ID

2020-06-30-Preview

This preview version includes all of the features introduced in 2019-05-06-Preview, plus the following additions:

  • Semantic search, a premium feature that runs on Standard tier services and that invokes semantic ranking.
  • Indexer data source for Power Query Connectors
  • Indexer data source for MySQL
  • Indexer data source for Cosmos DB Gremlin API
  • Indexer data source for SharePoint Online
  • Normalizer property for text normalization, for case-insensitive filtering, faceting and sorting
  • Reset Documents for indexer-based indexing to specifically refresh specific documents by ID
  • Entity Linking cognitive skill (v3)
  • Entity Recognition cognitive skill (v3)
  • Sentiment Analysis cognitive skill (v3)

2019-05-06-Preview

  • Indexer data source support for Cosmos DB MongoDB API
  • Indexer data source for native blob soft delete in Blob Storage
  • featuresMode parameter that returns detailed information about a relevance score
  • Azure Machine Learning (AML) cognitive skill
  • Personal identification detection cognitive skill
  • Cache enriched documents to preserve and reuse image processing (and other AI enrichments)

See also