Azure AI Search REST API reference

Article
11/14/2023

Azure AI Search (formerly known as Azure Cognitive Search) is a fully managed cloud search service that provides information retrieval over user-owned content.

Data plane REST APIs are used for indexing and query workflows.

Control plane operations are accessed through a separate Management REST API.

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.

Key concepts

Azure AI Search has the concepts of search services, indexes, documents, indexers, data sources, skillsets, and synonym maps.

A search service hosts index, indexers, data sources, skillsets, and synonym maps as top-level objects.
A search index provides persistent storage of search documents. Search documents are your data, articulated as a collection of fields, loaded from external sources and pushed to an index to make it searchable.
A search indexer adds automation, reading data in native formats and serializing it into JSON.
An indexer has a data source and points to an index.
An indexer might also have a skillset that adds AI enrichment and integrated vectorization to the indexing pipeline. Skillsets are always attached to an indexer. They invoke machine learning to extract or chunk text, vectorize content, infer features, or add structure to content so that it can be indexed by a search service.

Altogether, you can create the following objects on a search service:

Objects	Description
Data sources	A data source connection used by an indexer to retrieve and refresh documents for indexing. Data sources have a `type`. You can use the Microsoft-provided connections for Azure, or third-party connectors through partners. See Data sources gallery for the full list.
Documents	Conceptually, a document is an entity in your index. Mapping this concept to more familiar database equivalents: a search index equates to a table, and documents are roughly equivalent to rows in a table. Documents exist only in an index, and are retrieved only through queries that target the documents collection (`/docs`) of an index. All operations performed on the collection such as uploading, merging, deleting, or querying documents take place in the context of a single index, so the URL format document operations will always include `/indexes/[index name]/docs` for a given index name.
Indexes	An index is stored on your search service and populated with JSON documents that are indexed and tokenized for information retrieval. The fields collection of an index defines the structure of the search document. Fields have a name, data types, and attributes that determine how it's used. For example, `searchable` fields are used in full text search, and thus tokenized during indexing. An index also defines other constructs, such as scoring profiles for relevance tuning, suggesters, semantic configurations, and custom analyzers.
Indexers	Indexers provide indexing automation. An indexer connects to a data source, reads in the data, and passes it to a search engine for indexing into a target search index. Indexers read from an external source using connection information in a data source, and serialize the incoming data into JSON search documents. In addition to a data source, an indexer also requires an index. The index specifies the fields and attributes of the search documents.
Skillsets	A skillset adds external processing steps to indexer execution, and is usually used to add AI or deep learning models to analyze or transform content to make it searchable in an index. The contents of a skillset are one or more skills, which can be built-in skills created by Microsoft, custom skills, or a combination of both. Built-in skills exist for image analysis, including OCR, and natural language processing. Other examples of built-in skills include entity recognition, key phrase extraction, chunking text into logical pages, among others. A skillset is high-level standalone object that exists on a level equivalent to indexes, indexers, and data sources, but it's operational only within indexer processing. As a high-level object, you can design a skillset once, and then reference it in multiple indexers.
Synonym maps	A synonym map is service-level object that contains user-defined synonyms. This object is maintained independently from search indexes. Once uploaded, you can point any searchable field to the synonym map (one per field).

Permissions and access control

You can use key-based authentication or role-based through Microsoft Entra ID.

Key-based authentication relies on API keys that are generated for the search service. Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it. You can use an Admin API key for read-write operations or a Query API key for read access to the documents collection of a search index.

Microsoft Entra ID authentication and role-based access control requires that you have an established tenant in Microsoft Entra ID, with security principals and role assignments. Members of the following roles have data plane access. You can create custom roles if the built-in roles are insufficient.

Role	Access
Search Service Contributor	Access to objects, but no access to index content. This role can't query a search index or add, remove, or update documents in a search index. This role is for administrators who need to manage objects, but without the ability to view or access object data.
Search Data Index Contributor	Read-write access to index content. This role is for developers or index owners who need to import, refresh, or query the documents collection of an index.
Search Data Index Reader	Read access to index content. This role is for apps and users who run queries.

When using roles on the connection, your client app presents a bearer token in the authorization header. See Authorize access to a search app using Microsoft Entra ID for help with setting this up.

You can disable key-based authentication or role-based authentication. If you disable role-based authentication, some built-in roles will still have access. See Microsoft Entra ID authentication and role-based access control for Azure AI Search for details.

Calling the APIs

The APIs documented in this section provide access to operations on search data, such as index creation and population, document upload, and queries. When calling APIs, keep the following points in mind:

Requests must be issued over HTTPS (on the default port 443).
Request URIs must include the api-version. The value must be set to a supported version, formatted as shown in this example: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30
Request headers must include either an api-key or a bearer token for authenticated connections. Optionally, you can set the Accept HTTP header. If the content type header isn't set, the default is assumed to be application/json.