Share via

REST API versions (Azure AI Search)

  • Article

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.

Screenshot of the version selector.

Stable versions

API version Specification API updates
2024-07-01 (Latest) Swagger specification Release note
2023-11-01 Swagger specification Release note
2020-06-30 Swagger specification Release note
2019-05-06 Swagger specification Adds complex types.

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-11-01-preview (Latest) Swagger specification Release note
2024-09-01-preview Swagger specification Release note
2024-05-01-preview Swagger specification Release note
2024-03-01-preview 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

Release notes

2024-11-01-preview

This preview builds on the 2024-09-01-preview and is inclusive of all features currently in preview. You can upgrade from 2024-09-01-preview to 2024-11-01-preview with minimal code changes. For more information, see Upgrade the REST APIs.

Update Applicable REST API
Query rewrite in the semantic reranker, used to refine queries sent to the L2 ranker. Search Documents, new QueryRewritesType property in the request.
Document Layout skill used to analyze a document for structure. Create or Update Skillset, new DocumentIntelligenceLayoutSkill skill.
Managed identity for attaching an Azure AI multiservice resource. Create or Update Skillset, new AIServicesAccountIdentity property.
Markdown parsing mode, used for indexing Markdown files in Azure Storage. Create or Update Indexer, new markdown parsing mode.
Rescoring options for compressed vectors, used for rescoring with original vectors instead of compressed vectors. Applies to HNSW and exhaustive KNN vector algorithms, using binary and scalar compression. Create or Update Index, new rescoringOptions properties. A new enableRescoring property maps to rerankWithOriginalVectors introduced in 2024-03-01-preview.

2024-09-01-preview

This preview builds on the 2024-05-01-preview and is inclusive of all features currently in preview. You can upgrade from 2024-05-01-preview to 2024-09-01-preview with no code changes required. For more information, see Upgrade the REST APIs.

Update Applicable REST API
Truncated dimensions for text-embedding-3-small and text-embedding-3-large models retrained on Matryoshka Representation Learning (MRL) quantization. Create or Update Index, new truncationDimension parameter
Subscores or scoring details for unpacking hybrid search results scored by Reciprocal Rank Fusion (RRF). Search Documents, new debug parameter and query subscore definitions in the response.
Target filtering to the vector portion of a hybrid search query. Search Documents, new filterOverride parameter in RawVectorQuery, VectorizableTextQuery, VectorizableImageUrlQuery, VectorizableImageBinaryQuery.
Token chunking in Text Split skill, instead of just characters. Create or Update Skillset, new unit parameter and other token-related properties.

2024-07-01

This version provides generally available updates for integrated vectorization (skills and vectorizers), scalar quantization, and binary quantization. See What's new in Azure AI Search for details.

Update Applicable REST API
Generally available - vector data types Create or Update Index
Generally available - vector quantization properties for built-in scalar or binary quantization in a search index. Create or Update Index
Generally available - 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. Create or Update Index
Generally available - VectorizableTextQuery parameters for relevance tuning. Hybrid query parameters (MaxTextSizeRecall) are still in preview. Search Documents
Generally available - AzureOpenAIEmbedding skill to support more models than just text-embedding-ada-002 for integrated vectorization during indexing. Set the model name and dimensions properties to target a specific model. Create or Update Skillset
Generally available - Azure OpenAI embedding vectorizer for integrated vectorization during queries. Vectorizer properties support more models. Create or Update 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. All versions

2024-05-01-preview

This preview adds support for OneLake indexing, relevance tuning, and deeper integration with more embedding models during indexing and queries. It builds on the 2024-03-01-preview and is inclusive of all features currently in preview.

To upgrade from 2024-03-01-preview or 2023-10-01-preview, update the AzureOpenAIEmbedding skill or vectorizer to include the model name and dimensions. To upgrade from 2023-07-01-preview (deprecated) or for step-by-step instructions, see Upgrade REST APIs.

Here are the updates in this preview. We also recommend What's new in Azure AI Search.

Update Applicable REST API
Indexer data source for OneLake files and shortcuts. Create or Update Datasource
Collection(Edm.Byte), a binary data type for embedding models that support them. Vector field definitions support this data type. Create or Update Index
Multiple vector and hybrid query parameters for relevance tuning. Set thresholds to exclude low scoring results. Weight vector queries. For hybrid queries, set maximum documents to retrieve in the text portion of a hybrid query. Search Documents
New Azure AI Vision skill for multimodal integrated vectorization during indexing. This skill calls the multimodal API of Azure AI Vision. Create or Update Skillset
New Azure AI Vision vectorizer for multimodal queries. A vectorizer is specified in index definitions, but used during query execution. Create or Update Index
Updated AzureOpenAIEmbedding skill to support more models than just text-embedding-ada-002 for integrated vectorization during indexing. Set the model name and dimensions properties to target a specific model. Create or Update Skillset
Updated Azure OpenAI embedding vectorizer for integrated vectorization during queries. Vectorizer properties support more models. Create or Update 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. All versions

2024-03-01-preview

This preview version builds on 2023-10-01-preview by adding preview APIs that improve vector storage. See What's new in Azure AI Search for details.

Update Applicable REST API
New narrow data types for vector fields if you have embedding models that support them or quantization logic that outputs smaller vectors. Create or Update Index
New vector quantization properties for built-in vector compression in a search index. Create or Update 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. Create or Update 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. All versions

2023-11-01

This version provides generally available features. See What's new in Azure AI Search for details.

Update Applicable REST API
Semantic ranking in Search Post requests. Search Documents
Vector search configuration for indexing vector fields Create or Update Index
Vector queries in Search Post requests. Search Documents
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. All versions

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

Do not use this API version. Deprecation of this preview version was announced on April 15, 2024 and is no longer supported after July 8, 2024. For help with migration, see Upgrade REST APIs in Azure AI Search.

This version introduced vector support and uses a vector configuration that's incompatible with newer API versions.

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