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

# Sanity Query API

The Sanity Query API runs GROQ queries against a dataset in Sanity Content Lake and returns the result along with the time taken and sync tags for cache invalidation. Queries can be sent as GET with the query in the URL or as POST for long queries and large parameter values, with GROQ parameters passed alongside. A perspective setting chooses whether the query sees published content, drafts, raw documents, or a custom stack of release IDs, and options add a query execution plan, content source maps for visual editing, and request tags for log filtering. The same endpoint is served from Sanity's API CDN for edge-cached results on the published and raw perspectives.

## For AI agents

Run GROQ queries against a Sanity dataset to fetch content as published, as drafts, or as a release would look, with optional parameters, execution plans, and source maps.

## Scope

Does not create, edit, or delete documents, and does not stream changes. Use for reading Sanity content with GROQ queries only.

## Capabilities

- Run a GROQ query such as all documents of a given _type and get the result with timing in ms
- Pass GROQ parameters like $language as JSON in the params object of a POST query
- Preview content as drafts or as a stack of release IDs with the perspective parameter
- Return the query execution plan with explain, or only the plan without running the query
- Add content source maps with resultSourceMap so results can be traced back to fields for visual editing
- Get syncTags with each result to pair with live invalidation events, and set cacheMode noStale on CDN reads

## Use cases

### AI agent answering from CMS content

An agent answering customer questions should read the site's real content, not guess. Through Jentic it searches for 'query Sanity content with GROQ', loads the query operation, and sends a GROQ query with parameters for a dataset, with the Sanity token injected at call time when drafts or a private dataset are involved. The result comes back as JSON the agent can quote directly.

Example prompt: POST `/data/query/production` with query "*[_type == 'movie' && language == $language]" and params language 'es', then list the title of each result

### Previewing drafts and releases

Editors and review agents need to see content before it is published. Setting perspective to drafts runs the query as if every draft were published, and a comma-separated list of release IDs shows how content will look once those releases go live. These perspectives go to the API host, since the CDN serves only published and raw.

Example prompt: GET `/data/query/production` with query "*[_id == 'homepage'][0]" and perspective 'drafts', and compare it with the same query using perspective 'published'

### Debugging slow or wrong queries

When a page loads slowly or shows the wrong items, the query is the first suspect. Setting explain returns the execution plan in an explain field, and explain set to only returns the plan without running the query. Because GROQ evaluates to a value even when nothing matches, an empty array or null result points to a filter problem rather than a missing endpoint.

Example prompt: GET `/data/query/production` with query "*[_type == 'post'][0...20]" and explain 'only', then summarise the plan

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/query/{dataset}` | Run a GROQ query with GET |
| POST | `/data/query/{dataset}` | Run a long GROQ query with POST |

## Key resources

- **Query results** — GROQ result with ms timing, optional query echo, and syncTags
- **Perspectives** — published, drafts, raw, or a release stack

## 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:** 42 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 90 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 18 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-query/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 Query API by hand means templating the projectId and apiVersion into the host, choosing between the API and CDN hosts by perspective, switching to POST for long queries, and JSON-encoding GROQ parameters. 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 name in the URL path (`/data/query/{dataset}`), so a rule can pin your agent to one dataset. Both operations only read, and the token's own permissions decide what the agent can see.
- **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 'query Sanity content with GROQ' or 'preview Sanity drafts', and Jentic returns the query operation with its input schema, including perspective and explain.

## Related APIs

- **Sanity Doc API** — Fetch documents by ID with the most recent write
- **Sanity Actions API** — Publish and edit the documents your queries return
- **Contentful** — Headless CMS with entries, assets, and publishing
- **Storyblok** — Headless CMS with a visual editor

## FAQ

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

Per its OpenAPI spec, the Sanity Query API accepts a bearer token in the Authorization header, and queries can also be made without one. Through Jentic the token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### Should I use GET or POST for Sanity queries?

Use GET for most queries and POST for long queries or large parameter values; the spec advises POST for queries longer than 11 KB. The POST body only accepts query, params, and returnQuery, so options such as perspective, explain, and tag still go in the URL, and unknown body fields return 400.

### Why does my Sanity query return an empty result instead of 404?

GROQ always evaluates to a value, so a query for a missing document returns an empty array, null, or 0 rather than a 404. For example, a filter on an _id that does not exist returns [], and adding [0] returns null.

### Can I use the Sanity CDN for queries?

Yes. The same query path is served from the API CDN host for edge-cached results, but the CDN only accepts the published and raw perspectives; drafts or release perspectives return 400 there. Set cacheMode to noStale to stop stale-while-revalidate on CDN responses.

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

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API and CDN limits for your plan.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Query API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the GROQ query operation with its parameters when it needs content.

### How do I run a GROQ query through Jentic?

Search Jentic for 'query Sanity content with GROQ', load the query operation, and execute GET `/data/query/{dataset}` with your GROQ string in the query parameter, or POST `/data/query/{dataset}` with query and params in the body for longer queries. 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 Query API?

Yes. Write a rule that allows GET `/data/query/public-site` only, and the agent can query that dataset but cannot query any other dataset in the project, including private ones. Both operations are reads, and every call it makes is logged.
