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.
Expand Reference > Data Plane.
Open an API reference page.
Select the API version from the dropdown filter on the top left.
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.
vectorSearchhas definitions foralgorithms,profiles, andvectorizers:algorithmscontinues to supporthnswand now also supportseknn, 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 replacesalgorithmConfigurationswithin thevectorSearchproperty in 2023-07-01-Preview.profilesis 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.vectorizersis visible, but currently ignored.
On vector fields,
vectorSearchProfilereplacesvectorSearchConfiguration. ThevectorSearchProfileproperty 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
vectorSearchProfileas long as the profile specifies the exact same algorithm previously specified invectorSearchConfiguration. 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".
vectorQueriesreplacesvectorsin 2023-07-01-PreviewvectorQueries.vectorsreplacesvectors.valuesin 2023-07-01-Preview.The vector query is now a polymorphic structure.
kindmust 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.vectorFilterModeis 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:
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).
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)