Semantic Search with Azure AI Search REST API | Meaning-Based RAG Queries

RAG PIPELINE — SEMANTIC SEARCH

Semantic Search

Run a semantic ranking search against your Azure AI Search index. Unlike keyword search, semantic search uses Microsoft's language models to understand the meaning of the query and re-rank the top BM25 results by contextual relevance. It can also return semantic captions — highlighted key passages from matching documents — making it highly effective for RAG retrieval.

POST · Azure AI Search Semantic Ranking · L2 Re-rank Variables: azureAiSearch_ResourceName, azureAISearch_IndexName, azureAISearch_Key

Endpoint

POST https://{{azureAiSearch_ResourceName}}.search.windows.net/indexes/{{azureAISearch_IndexName}}/docs/search?api-version=2025-05-01-preview

Prerequisite Semantic search requires a Semantic Configuration to be enabled on your Azure AI Search index. Go to your index settings in the Azure portal and enable semantic ranker with a configuration named default.

Postman Collection Variables Required

Set these variables in the Postman collection before calling this API azureAiSearch_ResourceName — Your Azure AI Search resource name
azureAISearch_IndexName — The name of your Azure AI Search index
azureAISearch_Key — Your Azure AI Search API key

Authentication

Azure AI Search API Key

Header: api-key{{azureAISearch_Key}}

Request Body

Field	Type	Required	Description
search	String	Required	The natural language query to search for. Write it as a complete question for best semantic results.
queryType	String	Required	Must be `"semantic"` to enable semantic ranking.
semanticConfiguration	String	Required	Name of the semantic configuration on your index. Use `"default"` if you set it up with the default name.
select	String	Optional	Comma-separated fields to return. Example: `"section,content"`.
top	Integer	Optional	Number of results. Use `3`–`5` for RAG context retrieval.

Request Body (from Postman collection)

{
  "search"               : "How do I configure Azure AI Search with OutSystems?",
  "queryType"            : "semantic",
  "semanticConfiguration": "default",
  "select"               : "section,content",
  "top"                  : 5
}

Sample Request

cURL

curl -X POST \
  -H "api-key: <your-azure-search-key>" \
  -H "Content-Type: application/json" \
  -d '{"search":"How do I configure Azure AI Search?","queryType":"semantic","semanticConfiguration":"default","select":"section,content","top":5}' \
  "https://<resource>.search.windows.net/indexes/<index>/docs/search?api-version=2025-05-01-preview"

Response — 200 OK

Semantic Score vs BM25 Score Results include both @search.score (BM25 relevance) and @search.rerankerScore (semantic score, 0–4). Sort by @search.rerankerScore for best semantic ranking order.

Sample Response

{
  "value": [
    {
      "@search.score"         : 4.28,
      "@search.rerankerScore" : 2.91,
      "section"               : "Configuring the Search Service",
      "content"               : "To configure Azure AI Search with OutSystems..."
    }
  ]
}

Error Responses

200

OK — Search results returned with semantic re-ranking.

400

Bad Request — Semantic configuration not found on index, or queryType is not "semantic".

401

Unauthorized — Invalid or missing api-key.

403

Forbidden — Semantic ranker tier not enabled on this Azure AI Search resource (requires Standard S1+).

404

Not Found — Index not found.