Azure Cognitive Search Service REST

Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience to custom applications. One way to add search capability is through a REST API, with operations that create and manage indexes, load data, implement search features, execute queries, and handle results.

A separate REST API is provided for service administration, including provisioning the service or altering capacity. For more information, see Azure Cognitive Search Management REST.

To create the service, see Create an Azure Cognitive Search service.

Key concepts

Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains one or more indexes that provide persistent storage of searchable data, and data is loaded in the form of JSON documents. Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data source to extract and load data into an index.

AI enrichment adds skillsets operations. Skillsets are attached to indexers. Indexer execution is the action that invokes a skillset, with one skillset per indexer.

There are five types of operations that can be executed against the service:

  • Index management operations. Create, delete, update, or configure a search index.

  • Document operations. Add, update, or delete documents in the index, query the index, or look up specific documents by ID.

  • Indexer operations. 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 operations. Part of an AI enrichment workload, a skillset defines a series of enrichment processing. A skillset is consumed by an indexer.

  • Synonym map operations. 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).

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:

  • All APIs must be issued over HTTPS (on the default port 443).

  • Your search service is uniquely identified by a fully-qualified domain name (for example: ``).

  • All API requests must include an api-key that was generated for the search service you provisioned. Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

  • All API requests must include the api-version in the URI. Its value must be set to the version of the current service release, shown in the following example:

    GET https://[search service name]

  • All API requests can optionally set the Accept HTTP header. If the header is not set, the default is assumed to be application/json.


The endpoint for service operations is the URL of the Azure Cognitive Search service you provisioned: https://<yourService>

Authentication and Authorization

Every HTTP request to your search service is authenticated based on two pieces of information: a search service URL and an api-key that provides proof the request is from a trusted entity. There are two types of api-keys for different levels of operation.

Key Description Limits
Admin Admin keys grant full rights to all operations, including the ability to manage the service, get status and object definitions, and create and delete indexes, indexers, and data sources.

Two admin api-keys, referred to as primary and secondary keys in the portal, are automatically generated when the service is created and can be individually regenerated on demand. Having two keys allows you to roll over one key while using the second key for continued access to the service.

Admin keys are only specified in HTTP request headers. You cannot place an admin api-key in a URL.
Maximum of 2 per service
Query Query keys grant read-only access to content within an index (documents), and are typically distributed to client applications that issue search requests.

Query keys are created on demand. You can create them manually in the portal or programmatically via the Management REST API.

Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. Alternatively, you can pass a query key as a parameter on a URL. Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 per service

Visually, there is no distinction between an admin key or query key. Both keys are strings composed of 32 randomly-generated alpha-numeric characters. If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.


It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. For this reason, Azure Cognitive Search will only accept a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. As a general rule, we recommend passing your api-key as a request header.

Authorization in Azure Cognitive Search

Authorization is available for administrative operations via the role-based access controls (RBAC) provided in the Azure portal. RBAC roles are used to set levels of access for service administration in a way that is consistent across all services. For example, viewing sensitive data, such as the admin key, is restricted to the Owner and Contributor roles, whereas viewing service status is available to members of any role.

For its own search-centric operations, Azure Cognitive Search does not provide an authorization model. However, if you have the ability to load an index with document and user associations, you can filter search results based on user identity. For more information, see Security filters for trimming results in Azure Cognitive Search.

See also