Manage your Azure AI Search service using REST APIs

2025-04-30

Learn how to create and configure an Azure AI Search service using the Management REST APIs. Only the Management REST APIs are guaranteed to provide early access to preview features.

The Management REST API is available in stable and preview versions. Be sure to set a preview API version if you're accessing preview features.

Create or update a service
Enable Azure role-based access control for data plane
Enforce a customer-managed key policy
Disable semantic ranker
Disable workloads that push data to external resources
Create a query key
Regenerate an admin key
List private endpoint connections
List search operations
Delete a search service

All of the Management REST APIs have examples. If a task isn't covered in this article, see the API reference instead.

Prerequisites

An Azure subscription - Create a trial subscription.
Visual Studio Code with a REST client.
Azure CLI to get an access token, as described in the following steps. You must be an owner or administrator in your Azure subscription.

Management REST API calls are authenticated through Microsoft Entra ID. You must provide an access token on the request and permissions to create and configure a resource. In addition to the Azure CLI, you can use Azure PowerShell to create an access token.
1. Open a command shell for Azure CLI.
2. Sign in to your Azure subscription. If you have multiple tenants or subscriptions, make sure you select the correct one.
```
az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
```
3. Get the tenant ID and subscription ID.
```
az account show
```
4. Get an access token.
```
az account get-access-token --query accessToken --output tsv
```
  You should have a tenant ID, subscription ID, and bearer token. You'll paste these values into the .rest or .http file that you create in the next step.

Set up Visual Studio Code

If you're not familiar with the REST client for Visual Studio Code, this section includes setup so that you can complete the tasks in this article.

Start Visual Studio Code and select the Extensions tile.
Search for the REST client and select Install.
Open or create new file named with either a .rest or .http file extension.

Provide variables for the values you retrieved in the previous step.

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

Verify the session is operational by listing search services in your subscription.

 ### List search services
 GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

Select Send request. A response should appear in an adjacent pane. If you have existing search services, they're listed. Otherwise, the list is empty, but as long as the HTTP code is 200 OK, you're ready for the next steps.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: chinanorth2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

Create or update a service

Creates or updates a search service under the current subscription. This example uses variables for the search service name and region, which haven't been defined yet. Either provide the names directly or add new variables to the collection.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "China North",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Upgrade a service

Some Azure AI Search capabilities are only available to new services.

### Upgrade a search service
@resource-group = my-rg
@search-service-name = my-search
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/upgrade?api-version=2025-02-01-preview  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Change pricing tiers

If you need more capacity, you can switch to a higher pricing tier. Currently, you can only move up between Basic and Standard (S1, S2, and S3) tiers. Use the sku property to specify the higher tier.

### Change pricing tiers
@resource-group = my-rg
@search-service-name = my-search
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-02-01-preview HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Create an S3HD service

To create an S3HD service, use a combination of sku and hostingMode properties. Set sku to standard3 and "hostingMode" to HighDensity.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Configure role-based access for data plane

Applies to: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

Configure your search service to recognize an authorization header on data requests that provide an OAuth2 access token.

To use role-based access control for data plane operations, set authOptions to aadOrApiKey and then send the request.

To use role-based access control exclusively, turn off API key authentication by following up with a second request, this time setting disableLocalAuth to true.

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Enforce a customer-managed key policy

If you're using customer-managed encryption, you can enable "encryptionWithCMK" with "enforcement" set to "Enabled" if you want the search service to report its compliance status.

When you enable this policy, any REST calls that create objects containing sensitive data, such as the connection string within a data source, will fail if an encryption key isn't provided: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Disable semantic ranker

Semantic ranker is enabled by default at the free plan that allows up to 1,000 requests per month at no charge. You can lock down the feature at the service level to prevent usage.

### Disable semantic ranker
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Disable workloads that push data to external resources

Azure AI Search writes to external data sources when updating a knowledge store, saving debug session state, or caching enrichments. The following example disables these workloads at the service level.

### Disable external access
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Delete a search service

### Delete a search service
DELETE https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

List admin API keys

### List admin keys
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Regenerate admin API keys

You can only regenerate one admin API key at a time.

### Regnerate admin keys
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Create query API keys

### Create a query key
@query-key-name = myQueryKey
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

List private endpoint connections

### List private endpoint connections
GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

List search operations

### List search operations
GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Next steps

After a search service is configured, your next steps include creating an index or querying an index using the Azure portal, REST APIs, or an Azure SDK.