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

index-name

string

required

Unique name for the index

fields

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

vectorSearch

object

Vector search configuration:

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

semantic

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

value

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

filter

string

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

select

string

Comma-separated list of fields to return

top

integer

Number of results to return (default: 50)

skip

integer

Number of results to skip for pagination

vectorQueries

array

Vector search queries with:

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

semanticConfiguration

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

name

string

required

Knowledge source name

kind

string

required

Source type: searchIndex, blob, sharepointOnline, web

searchIndexParameters

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

name

string

required

Knowledge base name

knowledgeSources

array

required

Array of knowledge source names

outputMode

string

Output mode: rawContent or answerSynthesis

answerSynthesisConfiguration

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

query

string

required

Natural language query

maxResults

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

suggesterName

string

required

Name of suggester to use

top

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

Build docs developers (and LLMs) love

REST APIs

SDKs

​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

Build docs developers (and LLMs) love

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