Share via

Management REST API reference (Azure AI Search)

  • Article

The Management REST APIs of Azure AI Search (formerly known as Azure Cognitive Search) provide programmatic access to administrative operations:

  • Create, update, and delete a search service
  • Retrieve search service information
  • Create, regenerate, or retrieve api-keys (query or admin keys)
  • Add or remove replicas and partitions (adjust capacity)
  • Configure a search service to use a private endpoint
  • Enable or disable Azure role-based access control

For data plane tasks, such as creating and querying an index, use the Search Service REST APIs instead.

How to work with the management REST APIs

To fully administer your service programmatically, you work with two APIs: the Management REST API of Azure AI Search documented here, plus the common Azure Resource Manager REST API.

The Resource Manager API is used for general-purpose operations that aren't service specific, such as querying subscription data, listing geo-locations, and so forth. All Resource Manager API calls are authenticated using Microsoft Entra ID. You must have membership and a role assignment in a Microsoft Entra tenant to make Resource Manager API calls.

Versioned API docs

REST API docs are now versioned. When you open an API reference page, select the API version from the dropdown filter.

Screenshot of the version selector.

Permissions and access control

Administration rights are conveyed through built-in roles in Microsoft Entra ID:

  • Owner or Contributor assignments are required for most tasks.
  • Reader role has limited access to service information (GET operations, except for API keys, which require Owner or Contributor permissions).

For more information, see Role-based access control in Azure AI Search.

A best practice is to assign roles to groups rather than individual users. An Azure subscription owner or global administrator manages these assignments. For more information, see Assign Microsoft Entra roles to groups.

Connect to the management endpoint

When setting up the connection, start with the Resource Manager endpoint https://management.azure.com and then add the subscription ID, provider (Microsoft.Search), and API version. Operations are specified in the body of the request.

A fully specified endpoint has the following components:

https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2020-08-01

The following clients are commonly used to call the management REST APIs:

Client Instructions and examples
Azure PowerShell using the Az.Search module Manage Azure AI Search using Azure PowerShell
Azure Command-Line Interface (CLI) Manage Azure AI Search using the Azure CLI
Visual Studio Code with the REST client Manage Azure AI Search using REST

You can also manage a search service using the Azure portal.

Management APIs in other SDKs

The REST APIs are foundational to Azure AI Search, and any changes to the programming model are reflected in the REST APIs first.

Alternatives include the following Azure SDKs, which are independently updated on separate release schedules:

See also