> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/azure-ai-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure AI Search REST API

> REST API reference for Azure AI Search indexes, queries, and agentic retrieval

# 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

```bash theme={null}
api-key: YOUR-ADMIN-KEY
```

### Microsoft Entra ID (Recommended)

```bash theme={null}
Authorization: Bearer <ENTRA-TOKEN>
```

To get a Microsoft Entra ID token:

```bash theme={null}
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
```

<ParamField path="index-name" type="string" required>
  Unique name for the index
</ParamField>

<ParamField body="fields" type="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
</ParamField>

<ParamField body="vectorSearch" type="object">
  Vector search configuration:

  * `profiles`: Vector search profiles
  * `algorithms`: HNSW or other algorithms
  * `vectorizers`: Embedding model configuration
</ParamField>

<ParamField body="semantic" type="object">
  Semantic search configuration:

  * `configurations`: Semantic ranking configurations
  * `prioritizedFields`: Fields to prioritize for semantic search
</ParamField>

**Request Example:**

```json theme={null}
{
  "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
```

<ParamField body="value" type="array" required>
  Array of document objects with:

  * `@search.action`: Action type (`upload`, `merge`, `mergeOrUpload`, `delete`)
  * Field values matching index schema
</ParamField>

**Request Example:**

```json theme={null}
{
  "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
```

<ParamField body="search" type="string">
  Full-text search query
</ParamField>

<ParamField body="filter" type="string">
  OData filter expression (e.g., `page_number ge 100`)
</ParamField>

<ParamField body="select" type="string">
  Comma-separated list of fields to return
</ParamField>

<ParamField body="top" type="integer">
  Number of results to return (default: 50)
</ParamField>

<ParamField body="skip" type="integer">
  Number of results to skip for pagination
</ParamField>

<ParamField body="vectorQueries" type="array">
  Vector search queries with:

  * `kind`: Query type (`vector`, `text`)
  * `vector`: Embedding vector
  * `fields`: Vector fields to search
  * `k`: Number of nearest neighbors
</ParamField>

<ParamField body="semanticConfiguration" type="string">
  Name of semantic configuration to use
</ParamField>

**Full-Text Search:**

```json theme={null}
{
  "search": "Phoenix urban development",
  "select": "id,page_chunk,page_number",
  "top": 5
}
```

**Vector Search:**

```json theme={null}
{
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [-0.002984, 0.000750, ...],
      "fields": "page_embedding_text_3_large",
      "k": 5
    }
  ]
}
```

**Hybrid Search:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "@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
```

<ParamField body="name" type="string" required>
  Knowledge source name
</ParamField>

<ParamField body="kind" type="string" required>
  Source type: `searchIndex`, `blob`, `sharepointOnline`, `web`
</ParamField>

<ParamField body="searchIndexParameters" type="object">
  For `searchIndex` kind:

  * `searchIndexName`: Index name
  * `sourceDataFields`: Fields to retrieve
</ParamField>

**Request:**

```json theme={null}
{
  "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
```

<ParamField body="name" type="string" required>
  Knowledge base name
</ParamField>

<ParamField body="knowledgeSources" type="array" required>
  Array of knowledge source names
</ParamField>

<ParamField body="outputMode" type="string">
  Output mode: `rawContent` or `answerSynthesis`
</ParamField>

<ParamField body="answerSynthesisConfiguration" type="object">
  Configuration for answer synthesis:

  * `resourceUri`: Azure OpenAI endpoint
  * `deploymentId`: Model deployment name
  * `modelName`: Model name
</ParamField>

**Request:**

```json theme={null}
{
  "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
```

<ParamField body="query" type="string" required>
  Natural language query
</ParamField>

<ParamField body="maxResults" type="integer">
  Maximum number of results to return
</ParamField>

**Request:**

```json theme={null}
{
  "query": "What cities are visible in Phoenix metropolitan area at night?",
  "maxResults": 5
}
```

**Response:**

```json theme={null}
{
  "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
```

<ParamField body="search" type="string" required>
  Partial search text
</ParamField>

<ParamField body="suggesterName" type="string" required>
  Name of suggester to use
</ParamField>

<ParamField body="top" type="integer">
  Number of suggestions to return
</ParamField>

## Index Statistics

### Get Index Statistics

Retrieve document count and storage size.

**Endpoint:**

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

**Response:**

```json theme={null}
{
  "documentCount": 1250,
  "storageSize": 52428800
}
```

## Error Responses

All errors return standard format:

```json theme={null}
{
  "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

## Related Resources

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdk/python">
    Azure AI Search Python client library
  </Card>

  <Card title=".NET SDK" icon="code" href="/sdk/dotnet">
    Azure AI Search .NET SDK
  </Card>
</CardGroup>