Azure AI Search REST API

Azure AI Search provides powerful full-text search, vector search, semantic ranking, and agentic retrieval capabilities through a comprehensive REST API.

Authentication

Azure AI Search supports two authentication methods:

API Key Authentication

api-key: YOUR-ADMIN-KEY

Microsoft Entra ID (Recommended)

Authorization: Bearer <ENTRA-TOKEN>

To get a Microsoft Entra ID token:

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Base URL

https://{search-service-name}.search.windows.net

Indexes

Create Index

Create a new search index with fields, vector configurations, and semantic settings. Endpoint:

PUT /indexes/{index-name}?api-version=2025-11-01-preview

string

required

Unique name for the index

array

required

Field definitions with:

name: Field name
type: Data type (Edm.String, Edm.Int32, Collection(Edm.Single))
key: Boolean indicating if this is the key field
searchable: Boolean for full-text search
filterable: Boolean for filtering

object

Vector search configuration:

profiles: Vector search profiles
algorithms: HNSW or other algorithms
vectorizers: Embedding model configuration

object

Semantic search configuration:

configurations: Semantic ranking configurations
prioritizedFields: Fields to prioritize for semantic search

Request Example:

{
  "name": "earth-at-night",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true
    },
    {
      "name": "page_chunk",
      "type": "Edm.String",
      "searchable": true
    },
    {
      "name": "page_embedding_text_3_large",
      "type": "Collection(Edm.Single)",
      "stored": false,
      "dimensions": 3072,
      "vectorSearchProfile": "hnsw_text_3_large"
    },
    {
      "name": "page_number",
      "type": "Edm.Int32",
      "filterable": true
    }
  ],
  "semantic": {
    "defaultConfiguration": "semantic_config",
    "configurations": [
      {
        "name": "semantic_config",
        "prioritizedFields": {
          "prioritizedContentFields": [
            {"fieldName": "page_chunk"}
          ]
        }
      }
    ]
  },
  "vectorSearch": {
    "profiles": [
      {
        "name": "hnsw_text_3_large",
        "algorithm": "alg",
        "vectorizer": "azure_openai_text_3_large"
      }
    ],
    "algorithms": [
      {
        "name": "alg",
        "kind": "hnsw"
      }
    ],
    "vectorizers": [
      {
        "name": "azure_openai_text_3_large",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://your-openai.openai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    ]
  }
}

Upload Documents

Add or update documents in an index. Endpoint:

POST /indexes/{index-name}/docs/index?api-version=2025-11-01-preview

array

required

Array of document objects with:

@search.action: Action type (upload, merge, mergeOrUpload, delete)
Field values matching index schema

Request Example:

{
  "value": [
    {
      "@search.action": "upload",
      "id": "doc1",
      "page_chunk": "Phoenix is a major city in Arizona with a distinctive urban grid pattern visible at night.",
      "page_embedding_text_3_large": [-0.002984, 0.000750, -0.004804, ...],
      "page_number": 104
    },
    {
      "@search.action": "upload",
      "id": "doc2",
      "page_chunk": "The Phoenix metropolitan area includes Glendale and Peoria, connected by Grand Avenue.",
      "page_embedding_text_3_large": [-0.012408, -0.010935, -0.017997, ...],
      "page_number": 105
    }
  ]
}

Search

Search Documents

Perform full-text, vector, or hybrid search queries. Endpoint:

POST /indexes/{index-name}/docs/search?api-version=2025-11-01-preview

string

Full-text search query

string

OData filter expression (e.g., page_number ge 100)

string

Comma-separated list of fields to return

integer

Number of results to return (default: 50)

integer

Number of results to skip for pagination

array

Vector search queries with:

kind: Query type (vector, text)
vector: Embedding vector
fields: Vector fields to search
k: Number of nearest neighbors

string

Name of semantic configuration to use

Full-Text Search:

{
  "search": "Phoenix urban development",
  "select": "id,page_chunk,page_number",
  "top": 5
}

Vector Search:

{
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [-0.002984, 0.000750, ...],
      "fields": "page_embedding_text_3_large",
      "k": 5
    }
  ]
}

Hybrid Search:

{
  "search": "Phoenix urban grid",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [-0.002984, 0.000750, ...],
      "fields": "page_embedding_text_3_large",
      "k": 5
    }
  ],
  "semanticConfiguration": "semantic_config",
  "top": 5
}

Response:

{
  "@odata.context": "https://your-service.search.windows.net/indexes('earth-at-night')/$metadata#docs(*)",
  "value": [
    {
      "@search.score": 0.9543,
      "id": "doc1",
      "page_chunk": "Phoenix is a major city...",
      "page_number": 104
    }
  ]
}

Agentic Retrieval

Create Knowledge Source

Create a knowledge source for agentic retrieval. Endpoint:

POST /knowledgesources?api-version=2025-11-01-preview

string

required

Knowledge source name

string

required

Source type: searchIndex, blob, sharepointOnline, web

object

For searchIndex kind:

searchIndexName: Index name
sourceDataFields: Fields to retrieve

Request:

{
  "name": "earth-knowledge-source",
  "description": "NASA Earth at Night e-book pages",
  "kind": "searchIndex",
  "searchIndexParameters": {
    "searchIndexName": "earth-at-night",
    "sourceDataFields": [
      {"name": "id"},
      {"name": "page_chunk"},
      {"name": "page_number"}
    ]
  }
}

Create Knowledge Base

Create a knowledge base that orchestrates agentic retrieval. Endpoint:

POST /knowledgebases?api-version=2025-11-01-preview

string

required

Knowledge base name

array

required

Array of knowledge source names

string

Output mode: rawContent or answerSynthesis

object

Configuration for answer synthesis:

resourceUri: Azure OpenAI endpoint
deploymentId: Model deployment name
modelName: Model name

Request:

{
  "name": "earth-knowledge-base",
  "description": "Knowledge base for Earth at Night queries",
  "knowledgeSources": ["earth-knowledge-source"],
  "outputMode": "answerSynthesis",
  "answerSynthesisConfiguration": {
    "resourceUri": "https://your-openai.openai.azure.com",
    "deploymentId": "gpt-5-mini",
    "modelName": "gpt-5-mini"
  }
}

Query Knowledge Base

Execute an agentic retrieval query. Endpoint:

POST /knowledgebases/{knowledge-base-name}/query?api-version=2025-11-01-preview

string

required

Natural language query

integer

Maximum number of results to return

Request:

{
  "query": "What cities are visible in Phoenix metropolitan area at night?",
  "maxResults": 5
}

Response:

{
  "answer": "The Phoenix metropolitan area visible at night includes Phoenix, Glendale, and Peoria. These cities are connected by Grand Avenue, a major transportation corridor. The grid pattern of streets is clearly visible due to street lighting when viewed from the International Space Station.",
  "sources": [
    {
      "id": "doc1",
      "content": "Phoenix is a major city in Arizona...",
      "relevanceScore": 0.95
    }
  ]
}

Autocomplete

Suggest

Get search suggestions based on partial input. Endpoint:

POST /indexes/{index-name}/docs/suggest?api-version=2025-11-01-preview

string

required

Partial search text

string

required

Name of suggester to use

integer

Number of suggestions to return

Index Statistics

Get Index Statistics

Retrieve document count and storage size. Endpoint:

GET /indexes/{index-name}/stats?api-version=2025-11-01-preview

Response:

{
  "documentCount": 1250,
  "storageSize": 52428800
}

Error Responses

All errors return standard format:

{
  "error": {
    "code": "InvalidRequestParameter",
    "message": "The 'top' parameter must be between 1 and 1000"
  }
}

Rate Limits

Rate limits vary by service tier:

Free: 3 requests per second
Basic: 10 requests per second
Standard: 50 requests per second
Storage Optimized: 100 requests per second

Python SDK

Azure AI Search Python client library

.NET SDK

Azure AI Search .NET SDK

REST APIs

SDKs

Azure AI Search REST API

Azure AI Search REST API

Authentication

API Key Authentication

Microsoft Entra ID (Recommended)

Base URL

Indexes

Create Index

Upload Documents

Search

Search Documents

Agentic Retrieval

Create Knowledge Source

Create Knowledge Base

Query Knowledge Base

Autocomplete

Suggest

Index Statistics

Get Index Statistics

Error Responses

Rate Limits

Python SDK

.NET SDK

​Azure AI Search REST API

​Authentication

​API Key Authentication

​Microsoft Entra ID (Recommended)

​Base URL

​Indexes

​Create Index

​Upload Documents

​Search

​Search Documents

​Agentic Retrieval

​Create Knowledge Source

​Create Knowledge Base

​Query Knowledge Base

​Autocomplete

​Suggest

​Index Statistics

​Get Index Statistics

​Error Responses

​Rate Limits

​Related Resources

Python SDK

.NET SDK

Azure AI Search REST API

Authentication

API Key Authentication

Microsoft Entra ID (Recommended)

Base URL

Indexes

Create Index

Upload Documents

Search

Search Documents

Agentic Retrieval

Create Knowledge Source

Create Knowledge Base

Query Knowledge Base

Autocomplete

Suggest

Index Statistics

Get Index Statistics

Error Responses

Rate Limits

Related Resources