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

# Sanity Listen HTTP Endpoint

The Sanity Listen API streams an event every time a document matching a GROQ filter is modified in a Sanity dataset, over a server-sent events connection the backend holds open. Each mutation event names the document ID, transaction ID, transition such as update, the identity that made the change, and the previous and resulting revisions, and can optionally include the resulting document, the document before the change, the mutations applied, and Mendoza effects. Listeners can wait until changes are visible to queries, include release version documents, and resume after a reconnect from the last event ID so no changes are missed. Sanity recommends its Live Content API for most new projects; Listen remains the way to receive per-document mutation detail.

## For AI agents

Subscribe to a live stream of changes to Sanity documents that match a GROQ filter, with the document ID, revision, author identity, and optionally the full updated document.

## Scope

Does not write documents, run full GROQ projections, or send webhooks to your servers. Use for streaming real-time change events for Sanity documents only.

## Capabilities

- Stream mutation events for documents matching a GROQ filter such as all posts of a given type
- Include the full resulting document with includeResult or the prior version with includePreviousRevision
- Wait until changes are queryable by setting visibility to query instead of transaction
- Resume a dropped connection from the last event ID with enableResume so missed changes are replayed
- Receive events for release version documents with includeAllVersions on API version 2025-02-19 or later
- Get mutation effects in the Mendoza diff format with effectFormat set to mendoza

## Use cases

### AI agent reacting to content edits

An agent that reviews new copy for tone or broken links needs to know the moment an editor saves. Through Jentic it searches for 'listen for Sanity document changes', loads the listen operation, and opens a stream with a GROQ filter such as all post documents and includeResult set to true, with the Sanity token injected at call time so drafts are visible. Each mutation event hands it the document ID and the updated content to check.

Example prompt: Open GET `/data/listen/production` with query '*[_type == "post"]' and includeResult true, and for each mutation event read documentId and transition

### Keeping a search index in sync

Sites that mirror Sanity content into a search engine or cache need to update entries as soon as content changes. The listen stream sends one event per matching document change; with visibility set to query it waits until the change is visible to queries, and enableResume lets the sync worker reconnect after the roughly four-hour connection limit without missing changes.

Example prompt: Open GET `/data/listen/production` with query '*[_type == "product"]', visibility 'query', and enableResume true, storing each event id so a reconnect can pass it as lastEventId

### Change review with before and after

Editorial review tools want to show what actually changed, not just that something did. Setting includePreviousRevision and includeResult returns both versions of the document with each event, and includeMutations lists the mutations applied in the transaction, so a reviewer or agent can diff the two and flag risky edits.

Example prompt: Open GET `/data/listen/staging` with query '*[_type == "page"]', includePreviousRevision true, and includeResult true, and summarise the difference between the two documents for each event

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/listen/{dataset}` | Stream document mutation events |

## Key resources

- **Mutation events** — Per-document change events with IDs, revisions, identity, and optional documents
- **Stream control events** — welcome, welcomeback, reset, channelError, and disconnect events

## 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:** 0 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 83 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 15 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 0 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-listen/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 Listen API by hand means templating the projectId and apiVersion into the host, holding a server-sent events stream open, deciding when a bearer token is needed for drafts or private datasets, and handling errors that arrive as stream events. 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/listen/{dataset}`), so a rule can pin your agent to one dataset such as staging. The GROQ filter travels as a query parameter, and the token's own read access decides whether drafts and private documents appear in the stream.
- **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 'listen for Sanity document changes' or 'watch a dataset for edits', and Jentic returns the listen operation with its query parameters, including includeResult and enableResume.

## Related APIs

- **Sanity HTTP API** — Run GROQ queries and writes against the dataset you are listening to
- **Sanity Doc API** — Fetch the latest write of a changed document by ID
- **Contentful** — Headless CMS with entries, assets, and publishing

## FAQ

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

Per its OpenAPI spec, the Sanity Listen API accepts a bearer token in the Authorization header, and the token is optional for public datasets. It is required to receive events for drafts, versions, or documents in private datasets. A malformed Authorization header returns 400 and an invalid token 401 before the stream starts. Through Jentic the token is stored by your own instance and attached at call time.

### Should I use the Sanity Listen API or the Live Content API?

The spec says most new projects should use the Live Content API, which streams cache invalidation signals. Use Listen when you need per-document mutation detail, such as the document ID, the identity that made the change, or the resulting document.

### How do I avoid missing Sanity events when the connection drops?

The server closes the connection after about four hours, and on restarts, without sending a disconnect event. Set enableResume to true and send the last event ID in the Last-Event-ID header or lastEventId parameter; if the listener can resume you get a welcomeback event followed by the missed events, otherwise a reset or welcome event tells you to refetch.

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

The OpenAPI spec does not give numeric rate limits, but it notes that a dataset has a maximum number of concurrent listeners, reported as a Max listener limit exceeded error on the stream. Check the Sanity documentation at https://www.sanity.io/docs for current limits.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Listen API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent opens the listen stream with the right query parameters when it needs to watch for changes.

### How do I listen for Sanity document changes through Jentic?

Search Jentic for 'listen for Sanity document changes', load the listen operation, and execute GET `/data/listen/{dataset}` with a GROQ filter in the query parameter. Only the filter part of the query is used; projections and slicing are ignored. 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 Listen API?

Yes. Write a rule that allows the listen operation only at `/data/listen/staging`, and the agent can watch staging changes but cannot open a stream on production. The operation is read-only, and every call it makes is logged.
