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

# Sanity Live HTTP Endpoint

The Sanity Live API streams sync tag invalidation events for a Sanity dataset, the signal underneath the Live Content API. Over a server-sent events connection it sends batches of sync tags on published documents as they become invalid, so a site or app knows which cached content to refetch without polling. Tokened requests can also include draft, version, and system document changes, and a stream can wait until a configured Sync Tag Invalidate Function has processed events. A client can restart from a previously returned event ID, and the stream signals restart, goaway, and error conditions as events.

## For AI agents

Stream Sanity sync tag invalidation events for a dataset so cached content can be refetched the moment a published or draft document changes.

## Scope

Does not return document content, run queries, or purge CDN caches. Use for streaming Sanity sync tag invalidation events only.

## Capabilities

- Stream sync tags on published documents as they become invalid for one dataset
- Include draft, version, and system document changes with includeAllDocuments set to true and a token
- Restart a stream from a previously returned event ID with the last-event-id header or lastEventId parameter
- Delay events until a Sync Tag Invalidate Function has processed them with waitFor set to function
- Detect refused or ending streams through goaway, restart, and error events

## Use cases

### AI agent keeping a content cache fresh

An agent that answers questions from a cached copy of Sanity content should refetch only what changed. Through Jentic it searches for 'stream Sanity live content events', loads the live events operation, and opens the stream for a dataset. Each message carries a batch of sync tags that have become invalid, and the agent refetches the content cached under those tags.

Example prompt: Open GET `/data/live/events/production` and, for each message event, refetch every cached query tagged with one of the returned tags

### Live draft preview

Editors previewing unpublished changes want the preview to update as they type. Requesting the stream with includeAllDocuments set to true adds draft, version, and system document changes; the spec requires a valid token for this and recommends the lowest access role you can, such as Viewer.

Example prompt: Open GET `/data/live/events/production` with includeAllDocuments true using a Viewer token, and trigger a preview refresh on each tags message

### Reliable reconnects for static site rebuilds

A build service listening for invalidations must not lose events across reconnects. Storing each event id and sending it back as last-event-id continues the stream from that position; if the ID is unusable the stream sends a restart event, which tells the service to do a full refresh. A goaway event with the reason connection limit reached means the connection was refused.

Example prompt: Reconnect to GET `/data/live/events/production` with the last-event-id header set to the last stored id, and run a full cache refresh if a restart event arrives

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/live/events/{dataset}` | Stream sync tag invalidation events |

## Key resources

- **Sync tag messages** — Batches of invalidated sync tags for the dataset
- **Stream control events** — welcome, restart, goaway, and error 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: 81 / 100
  - Developer Experience & Jentic Compatibility: 76 / 100
  - AI-Readiness & Agent Experience: 21 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 0 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-live/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 Live API by hand means templating the projectId and apiVersion into the host, avoiding the API CDN host it does not serve, holding a server-sent events stream open, and adding a bearer token only when drafts are needed. 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/live/events/{dataset}`), so a rule can pin your agent to one dataset's stream. The operation only reads invalidation events, and a Viewer-role token keeps the draft stream to read access.
- **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 'stream Sanity live content events' or 'watch for stale Sanity content', and Jentic returns the live events operation with its query and header parameters.

## Related APIs

- **Sanity HTTP API** — Refetch content with GROQ after its sync tags are invalidated
- **Sanity CDN Cache Purge API** — Purge cached responses on Sanity's CDN
- **Contentful** — Headless CMS with entries, assets, and publishing

## FAQ

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

Per its OpenAPI spec, the Sanity Live API accepts a bearer token in the Authorization header. Published-content streams can run without a token, but includeAllDocuments or includeDrafts set to true requires one, and an invalid token is rejected with 401 even for published content only. Through Jentic the token is stored by your own instance and attached at call time.

### Why does the Sanity Live API return 404?

The spec says the API CDN at apicdn.sanity.io does not serve this endpoint, and a request sent there returns 404. Use the regular API host for your project. A 400 means the API version is earlier than v2021-03-25, the minimum for this endpoint.

### How are Sanity sync tags delivered on the live stream?

Tags arrive as default message events with a tags array, batched over a window of about one second. When nothing else is sent, the server sends an empty comment line as a keep-alive about every 30 seconds.

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

The OpenAPI spec does not specify rate limits. It does describe a goaway event with the reason connection limit reached when a connection is refused; 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 Live API. Jentic connects it directly from the API Directory: import it, store your Sanity token once if you need drafts, and your agent opens the live events stream when it needs to watch for invalidations.

### How do I stream Sanity live content events through Jentic?

Search Jentic for 'stream Sanity live content events', load the live events operation, and execute GET `/data/live/events/{dataset}`, adding includeAllDocuments when you need drafts. 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 Live API?

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