Azure Cognitive Search Service REST API reference

  • Article

Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience over user-owned content. One way to add search capability is through the Search REST APIs, with operations that create and manage indexes, implement search features, and execute queries.

A separate Management REST API is used to create or modify the service itself. Alternatively, you can use the portal for many service and content management tasks. To get started, see Create a search service in Azure portal.

Key concepts

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

  • A search service hosts one or more indexes. It also hosts 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 in the form of JSON documents 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. Optionally, it might also have a skillset that adds AI enrichment to the indexer pipeline. Skillsets are always attached to an indexer. They add machine learning transformations that extract or generate text, or add structure to content so that it can be indexed by a search service.

Altogether, there are five types of operations that can be executed against the service:

Operation Description
Index Create, delete, update, or configure a search index.
Document Add, update, or delete documents in the index, query the index, or look up specific documents by ID.
Indexer Automate aspects of an indexing operation by configuring a data source and an indexer that you can schedule or run on demand. This feature is supported for a limited number of data source types on Azure.
Skillset Part of an AI enrichment workload, a skillset defines a series of enrichment processing that extracts or creates searchable text from unstructured text, application files, or image files. A skillset is invoked by an indexer.
Synonym map A synonym map is service-level resource that contains user-defined synonyms. This resource 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 Azure Active Directory (Azure AD).

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

  • Azure AD authentication and role-based access control requires that you have an established tenant in Azure Active Directory, 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 Azure AD on the connection, your client app presents a bearer token in the authorization header. See Authorize access to a search app using Azure Active Directory for help with setting this up.

You can disable key-based authentication or Azure RBAC. If you disable RBAC, some built-in roles will still have access. See Azure AD authentication and role-based access control for Azure Cognitive 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).

  • Requests must include the api-version in the URI. 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 header isn't set, the default is assumed to be application/json.

See also