canonical: https://jentic.com/apis/sanity.io/sanity-doc

# Sanity Doc HTTP Endpoint

The Sanity Doc API fetches the latest version of one or more Sanity documents by ID straight from the backend, bypassing caching and the delay of the query index. A single request takes a comma-separated list of document IDs, and includeAllVersions can add the draft and every release version of each published ID. Any ID that is not returned is listed in omitted with the reason existence or permission, and excludeContent returns only that list to check whether documents exist. It is less scalable than the Query API, so it suits read-after-write checks rather than general content fetching.

## For AI agents

Fetch the freshest version of Sanity documents by ID, including drafts and release versions, and check which IDs exist or are not readable.

## Scope

Does not run GROQ queries, write or publish documents, or serve cached CDN content. Use for fetching the latest version of Sanity documents by ID only.

## Capabilities

- Fetch the most recent write of a Sanity document by ID with getDocuments, without waiting for the query index
- Read several documents in one call by passing a comma-separated list of IDs such as my-doc and drafts.my-doc
- Return the draft and every release version of a published ID with includeAllVersions
- Check whether documents exist without fetching content by setting excludeContent to true
- See which IDs were left out and why through omitted, with the reason existence or permission
- Label requests in logs with the tag parameter

## Use cases

### AI agent read-after-write check

An agent that edits Sanity content needs to confirm its change before taking the next step, and the query index can lag behind. Through Jentic the agent searches for 'get a Sanity document by ID', loads the getDocuments operation, and requests the document IDs it wrote while the Sanity token is injected at call time. It gets the most recent write, not a cached or indexed copy.

Example prompt: GET `/data/doc/production/post-123`,drafts.post-123 and compare the title field on both documents

### Release version review

Before a content release goes live, editors want to see every pending version of a document. With includeAllVersions, a request for a published ID returns the published document, its draft, and each release version, on API version v2025-02-19 or later, even when the published document does not exist yet.

Example prompt: GET `/data/doc/production/product-7` with includeAllVersions true and list each returned _id

### Existence and permission checks

Sync jobs often need to know which IDs exist before writing references to them. Setting excludeContent to true returns documents as null and fills only omitted, marking each missing ID with existence and each unreadable one with permission, so a job can skip or flag them without downloading content.

Example prompt: GET `/data/doc/production/author-1`,author-2,author-3 with excludeContent true and report the IDs listed in omitted with their reasons

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/doc/{dataset}/{documentId}` | Get one or more documents by ID |

## Key resources

- **Documents** — Sanity documents with _id, _type, and all non-null fields
- **Omitted IDs** — IDs not returned, each with the reason existence or permission

## 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:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-doc/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 Doc API by hand means templating the projectId and apiVersion into the host, deciding when a bearer token is needed for drafts or private datasets, and avoiding unsupported query parameters that return 400. 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 in the URL path (`/data/doc/{dataset}/...`), so a rule can pin your agent to one dataset such as staging. The single operation is a read, so the bound is on where the agent may read, and the token's own read access decides which drafts and private documents come back.
- **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 'get a Sanity document by ID' or 'check whether a Sanity draft exists', and Jentic returns the getDocuments operation with its path and query parameters.

## Related APIs

- **Sanity HTTP API** — Query documents with GROQ and write mutations
- **Sanity Actions API** — Publish, unpublish, and release Sanity documents
- **Contentful** — Headless CMS with entries and assets
- **Storyblok** — Headless CMS with a visual editor

## FAQ

### What authentication does the Sanity Doc API use?

Per its OpenAPI spec, the Sanity Doc API accepts a bearer token in the Authorization header, and the token is optional. Requests to a public dataset without a token return only published documents. To read drafts, release versions, or private datasets, send a token with read access; through Jentic it is stored by your own instance and attached at call time.

### When should I use the Sanity Doc API instead of the Query API?

Use the Doc API when you need the most recent write of specific documents, since it bypasses caching and the query index delay. The spec notes it is less scalable than the Query API, so use GROQ queries for general content fetching.

### Can I use the perspective parameter with the Sanity Doc API?

No. The endpoint accepts only the includeAllVersions, excludeContent, and tag query parameters, and any other one, including perspective, returns a 400 error. Use includeAllVersions to get drafts and release versions instead.

### What are the rate limits for the Sanity Doc API?

The OpenAPI spec does not specify rate limits. Because every request goes to the backend rather than a cache, check the Sanity documentation at https://www.sanity.io/docs for current API limits before using it at volume.

### Is there a Sanity Doc API MCP server?

You don't need an MCP server to give your agent the Sanity Doc API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls getDocuments with the right parameters when it needs fresh content.

### How do I fetch a Sanity document by ID through Jentic?

Search Jentic for 'get a Sanity document by ID', load the getDocuments operation, and execute GET `/data/doc/{dataset}/{documentId}` with one or more comma-separated IDs. 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 Doc API?

Yes. A rule allowing GET only under `/data/doc/staging`/ lets the agent read any staging document while production reads stay out of reach. The API is read-only, so it cannot change content either way. Every call it makes is logged.
