HTTP API Reference

Embeddings Index API reference

Reference documentation for the Embeddings Index HTTP endpoints.

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

Deprecation notice

The Embeddings Index API is deprecated and will be sunset in a future release. We recommend migrating to the new Embeddings feature, now natively available within Sanity datasets.
The new Embeddings feature offers a more integrated experience with improved performance and full support going forward. No new features or fixes will be made to this package.

Migrate today: Dataset Embeddings documentation

If you have questions or need migration support, please open a discussion or reach out in the Sanity Community.

This is a paid feature

This feature is available in the Growth plan.

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

Want to get started?

Embeddings index introduction

Embeddings allow you to search for what your documents are about. Use the Embeddings Index API to build LLM agents or to enable semantic search.

Authentication

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

200

The list of embeddings indexes was successfully retrieved

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

200

The embeddings index was successfully created

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

200

The embeddings index was successfully retrieved

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

200

The embeddings index was successfully deleted

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
      • 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

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