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. Make sure the API reference is from the Reference > Data Plane folder.

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
2024-03-01-Preview (Latest)	Swagger specification	Release note
2023-10-01-Preview	Swagger specification	Release note
2023-07-01-Preview (deprecated)	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 (retired)	Unsupported after 10-10-2020	Preview version associated with stable version.
2014-10-20-Preview (retired)	Unsupported after 10-10-2020	Second public preview.
2014-07-31-Preview (retired)	Unsupported after 10-10-2020	First public preview.

Release notes

2024-03-01-Preview

This preview version builds on 2023-10-01-preview by adding the following preview APIs that help you save space:

• New narrow data types for vector fields if you have embedding models that support them or quantization logic that outputs smaller vectors.
• New vector quantization properties for built-in vector compression in a search index.
• New boolean stored property on a vector field that determines whether an extra copy of the field is stored. The extra copy is the retrievable content of that field. If you don't store it, the field is still used in queries, but can't be returned in a search result. You can set this property to conserve space on your search service or vector quota in a search index.
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

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.
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

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 defined in an index but used at query time to embed a text query string. A vectorizer references an embedding model. The search service makes a call to the embedding model to vectorize the text query string, and then passes the result to the search engine for a vector query.

• 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.

Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

2023-07-01-Preview

Important

Deprecation of this preview version was announced on April 15, 2024 and it will be retired on July 8, 2024. For help with migration, see Upgrade REST APIs in Azure AI Search.

This version has features from 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.
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

2021-04-30-Preview

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

• Index alias adds a secondary name used for referencing indexes in query and indexing requests. Alias operations include create, update, delete, get, and list.
• Managed identities for outbound connections. New values for connection strings in Create or Update Data Source support connections using Microsoft Entra ID authentication and roles instead of hard-coded database credentials or keys.
• Managed identity support is also supported for key vault connections, for search solutions that supplement default encryption with customer-managed encryption.
• More languages for the Text Translation cognitive skill.
• More queryLanguages for semantic search and speller in Search Documents (preview).
• A captions parameter to optionally request captions from semantic search in Search Documents (preview).
• Semantic configurations are specified in Create or Update Index. A semantic configuration determines which fields should be used for semantic ranking, captions, highlights, and answers.
• A semanticConfiguration parameter that is required for semantic queries in Search Documents (preview).
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

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
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

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)
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

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)
• Effective March 29, 2024: GET responses no longer return connection strings or keys. See Breaking change for client code that reads connection information for details.

See also

• Create a search service
• Quickstart: Create an Azure AI Search index using REST APIs