HTTP API ReferenceLast updated August 5, 2025

Embeddings Index

The Embeddings Index API allows you to create, manage, and query embeddings indexes for semantic search in your Sanity project. Learn more about embeddings indexes.

Embeddings Index API is currently in beta. Features and behavior may change without notice.
Embeddings Index API is available to projects on the Growth plan and above.

Note: Using this feature requires Sanity to send data to OpenAI and Pinecone to store vector interpretations of documents.

Known limitations:

Creating an embeddings index for very large datasets can be slow
The Embeddings Index HTTP API rate limit depends on the OpenAI rate limit, which sets a cap for the HTTP API at about 8,000 tokens per minute
The embeddings-index API does not support dataset aliases - you must use the real dataset name in all requests

Base API server URL

Embeddings Index API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

apiVersionstringdefault: "vX"
API version
projectIdstringdefault: "your-project-id"
Sanity project ID

Endpoints

Get all embeddings indexes

get/embeddings-index/{dataset}

Retrieve a list of all embeddings indexes for the specified dataset

Path parameters

datasetstringrequired
The name of the dataset to use for the request

Responses

Select response

200

The list of embeddings indexes was successfully retrieved

items

statusstring
indexNamestring
projectIdstring
datasetstring
projectionstring
filterstring
createdAtstring (date-time)
updatedAtstring (date-time)
failedDocumentCountinteger
startDocumentCountinteger
remainingDocumentCountinteger
webhookIdstring

Create an embeddings index

post/embeddings-index/{dataset}

Create a new embeddings index for an existing dataset in a Sanity project

Path parameters

datasetstringrequired
The name of the dataset to use for the request

Request body `application/json`

indexNamestringrequired
The name of the embeddings index you want to create
projectionstringrequired
The GROQ projection that defines which fields to include in the embeddings index.
If you don't include a projection, we process the entire document JSON into a less verbose format and embed all of it.
Example: "{title, author}" or "{...}" for all fields
filterstringrequired
The GROQ filter that defines which documents to include in the embeddings index.
The filter must be a valid GROQ filter without the square brackets that wrap the value assigned to _type.
Example: "_type=='movie'" or "_type in ['article', 'blogPost']"

Responses

Select response

200

The embeddings index was successfully created

statusstringrequired
messagestringrequired
indexobjectrequired
Show child attributes
- statusstring
- indexNamestring
- projectIdstring
- datasetstring
- projectionstring
- filterstring
- createdAtstring (date-time)
- updatedAtstring (date-time)
- failedDocumentCountinteger
- startDocumentCountinteger
- remainingDocumentCountinteger
- webhookIdstring

Get an embeddings index

get/embeddings-index/{dataset}/{indexName}

Retrieve a specific embeddings index for an existing database in a Sanity project

Path parameters

datasetstringrequired
The name of the dataset associated with the index
indexNamestringrequired
The name of the embeddings index

Responses

Select response

200

The embeddings index was successfully retrieved

statusstring
indexNamestring
projectIdstring
datasetstring
projectionstring
filterstring
createdAtstring (date-time)
updatedAtstring (date-time)
failedDocumentCountinteger
startDocumentCountinteger
remainingDocumentCountinteger
webhookIdstring

Delete an embeddings index

delete/embeddings-index/{dataset}/{indexName}

Delete a specific embeddings index for an existing database in a Sanity project

Path parameters

datasetstringrequired
The name of the dataset associated with the index
indexNamestringrequired
The name of the embeddings index

Responses

Select response

200

The embeddings index was successfully deleted

statusstring
indexNamestring
projectIdstring
datasetstring
projectionstring
filterstring
createdAtstring (date-time)
updatedAtstring (date-time)
failedDocumentCountinteger
startDocumentCountinteger
remainingDocumentCountinteger
webhookIdstring

Query an embeddings index

post/embeddings-index/query/{dataset}/{indexName}

Query an embeddings index to retrieve documents that are closely related to the input query

Path parameters

datasetstringrequired
The name of the dataset where you want to query the embeddings index
indexNamestringrequired
The name of the embeddings index you want to query

Request body `application/json`

querystringrequired
The text string used to query the embeddings index
maxResultsintegerdefault: 10
Max. number of results to return for each request
filterobject
Optional filter to refine search results by document type.
This allows you to limit the search to specific document types, which can be useful when you have multiple document types in your index.
You can specify either a single document type as a string or an array of document types.
Show child attributes
- type
  Filter results to include only documents of the specified type(s)
  
  Show child attributes
  Select one
  string
  A single document type to filter by
  
  Example:movie

Examplesapplication/json

{ "query": "sci-fi adventure with cowboys and aliens", "maxResults": 10, "filter": { "type": [ "summary", "synopsis", "userReview" ] } }

Responses

Select response

200

The query was successful

items

scorenumberrequired
Relevance score between 0 and 1
valueobjectrequired
Show child attributes
- documentIdstring (uuid)required
  The UUID of the matching document
- typestringrequired
  The type of the matching document

Base API server URL

Variables

Endpoints

Get all embeddings indexes

Path parameters

Responses

items

Create an embeddings index

Path parameters

Request body application/json

Responses

Get an embeddings index

Path parameters

Responses

Delete an embeddings index

Path parameters

Responses

Query an embeddings index

Path parameters

Request body application/json

Responses

items

Request body `application/json`

Request body `application/json`