canonical: https://jentic.com/apis/sanity.io/sanity-embeddings-index

# Sanity Embeddings Index API

The Sanity Embeddings Index API builds vector embeddings indexes over the documents in a Sanity dataset and runs semantic search queries against them. An index is defined by a GROQ filter that selects documents, such as _type=='movie', and a GROQ projection that picks the fields to embed, and a query returns matching documentId and type pairs with a relevance score between 0 and 1. Every operation in this spec is marked deprecated, and the API is described as a beta available on the Growth plan and above. Using it sends document data to OpenAI and Pinecone to store the vectors.

## For AI agents

Create, list, inspect, delete, and query Sanity embeddings indexes for semantic document search. Every operation in this spec is deprecated.

## Scope

Does not edit documents, accept your own vectors, or support dataset aliases. Use for creating and querying Sanity embeddings indexes for semantic document search only.

## Capabilities

- Create an embeddings index for a dataset from an indexName, a GROQ filter, and a GROQ projection (deprecated operation)
- Run a semantic text query against an index and get documentId, type, and score results, with maxResults and a document type filter (deprecated operation)
- Track indexing progress through status, startDocumentCount, remainingDocumentCount, and failedDocumentCount (deprecated operation)
- List all embeddings indexes in a dataset or delete one by indexName (deprecated operations)

## Use cases

### AI agent semantic content lookup

An agent answering questions about a site's content needs to find relevant documents by meaning, not exact words. Through Jentic the agent searches for 'semantic search Sanity content', loads the deprecated query operation, and sends a query string with maxResults for an existing index while the Sanity token is injected at call time. It then fetches the returned documentId values to read the matching content.

Example prompt: POST `/embeddings-index/query/production/embeddings-index-movies` with query 'sci-fi adventure with cowboys and aliens' and maxResults 5, then list each documentId with its score

### Related content suggestions

Editors linking related articles benefit from suggestions based on meaning. An index created with a filter such as _type in ['article', 'blogPost'] and a projection of {title, body} embeds just those fields, and queries can narrow results to one or more document types through filter.type.

Example prompt: POST `/embeddings-index/production` with indexName related-articles, filter _type in ['article', 'blogPost'], and projection {title, body}

### Index lifecycle checks

Indexing a large dataset can be slow, so teams need to see progress. Reading an index returns its status, projection, filter, and document counts, and listing returns every index in a dataset. The spec notes the API does not support dataset aliases, so requests must use the real dataset name.

Example prompt: GET `/embeddings-index/production/related-articles` and report status and remainingDocumentCount

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/embeddings-index/query/{dataset}/{indexName}` | Query an embeddings index (deprecated) |
| POST | `/embeddings-index/{dataset}` | Create an embeddings index (deprecated) |
| GET | `/embeddings-index/{dataset}/{indexName}` | Get an embeddings index (deprecated) |
| GET | `/embeddings-index/{dataset}` | Get all embeddings indexes (deprecated) |
| DELETE | `/embeddings-index/{dataset}/{indexName}` | Delete an embeddings index (deprecated) |

## Key resources

- **Embeddings indexes** — Named indexes defined by a GROQ filter and projection, with status and document counts
- **Query results** — Matching documentId and type pairs with a relevance score between 0 and 1

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 23 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 80 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-embeddings-index/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Embeddings Index API by hand means templating the projectId and apiVersion into the host, sending a bearer token, writing valid GROQ filter and projection strings, and using real dataset names because aliases are not supported. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Sanity puts the dataset and index name in the URL path (`/embeddings-index/query/{dataset}/{indexName}`), so a rule can pin your agent to querying one index in one dataset. You choose the operations it may call, so creating or deleting indexes is not included unless you add them.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'semantic search Sanity content' or 'create a Sanity embeddings index', and Jentic returns the matching operation with its input schema.

## Related APIs

- **Sanity HTTP API** — Query Sanity documents with GROQ
- **Pinecone API** — Managed vector database for similarity search
- **OpenAI API** — Generate embeddings and text with OpenAI models
- **Sanity Agent Actions API** — Generate, transform, and translate Sanity documents with LLMs

## FAQ

### Is the Sanity Embeddings Index API deprecated?

Yes. Every operation in this OpenAPI spec is marked deprecated, and the spec also describes the API as a beta whose features and behavior may change without notice. Check https://www.sanity.io/docs/embeddings-index-api-overview for Sanity's current guidance before building on it.

### What authentication does the Sanity Embeddings Index API use?

Per its OpenAPI spec, the Sanity Embeddings Index API uses bearer token authentication with a Sanity token in the Authorization header. Through Jentic the token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### What are the rate limits for the Sanity Embeddings Index API?

The spec says the HTTP API rate limit depends on the OpenAI rate limit, which caps it at about 8,000 tokens per minute. It also notes that creating an index for very large datasets can be slow.

### Does the Sanity Embeddings Index API send my content to third parties?

Yes. The spec notes that using the feature requires Sanity to send data to OpenAI and Pinecone to store vector interpretations of documents. Keep that in mind when choosing the filter and projection for an index.

### Is there a Sanity Embeddings Index MCP server?

You don't need an MCP server to give your agent the Sanity Embeddings Index API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent loads the query or index operation it needs on demand.

### How do I run a semantic search on Sanity content through Jentic?

Search Jentic for 'semantic search Sanity content', load the query operation, and execute POST `/embeddings-index/query/{dataset}/{indexName}` with a query string and optional maxResults. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Embeddings Index API?

Yes. Write a rule that allows only POST `/embeddings-index/query/production/related-articles`, and the agent can search that one index while creating or deleting indexes stays with you. Every call it makes is logged.
