Live Content API reference
Reference documentation for the Live HTTP endpoint.
The Live Content API is the underlying API that powers components like <SanityLive> and other Live by default functionality.
It lets you subscribe to a stream of sync tags as they become invalid, which you can then match up with the tags returned by the Query API, or in queries made with the Sanity client.
Authentication
To authenticate a request, send the Authorization: Bearer YOUR_TOKEN header, replacing YOUR_TOKEN with an API token. Whether a request needs a token depends on the data it streams:
- Authentication is not required for public data.
- Requests that use the
includeAllDocumentsoption require a valid API token. Use a token with the lowest access role you can, such as Viewer.
Base API server URL
Sanity API base URL. The API CDN (apicdn.sanity.io) does not serve this endpoint.
https://{projectId}.api.sanity.io/{apiVersion}Variables
- projectIdstringdefault:
"projectId"Project ID
- apiVersionstringdefault:
"v2025-02-19"API version. The minimum is v2021-03-25.
Endpoints
Stream sync tag invalidation events
/data/live/events/{dataset}Streams sync tags on published documents as they become invalid. This is a live API adhering to the Server-Sent Events standard.
The same stream is also available at https://api.sanity.io/{apiVersion}/projects/{projectId}/datasets/{dataset}/live/events.
Path parameters
The dataset to stream events from. The dataset name is not validated. A dataset that doesn't exist returns a
welcomeevent and then no further events.
Query parameters
Set to
trueto include version, draft, and system document changes. Only the exact valuetrueenables this. Requests made with this parameter require a valid API token. Use a token with the lowest access role you can, such as Viewer.Equivalent to
includeAllDocuments. This is the parameter@sanity/clientsends when you callclient.live.events({includeDrafts: true}). The API also acceptsincludeAllVersions=truewith the same effect.- waitForstring
Set to
functionto delay events until a configured Sync Tag Invalidate Function has processed them. Ignored whenincludeAllDocumentsorincludeDraftsistrue. - lastEventIdstring
Query parameter alternative to the
last-event-idheader, used when the header is not set. Some EventSource polyfills use it because a custom header triggers a CORS preflight request.
Header parameters
- last-event-idstring
An optional start event ID ("position"). If provided, it must be a previously returned event ID. The stream will continue with the next event following this position. If not given, the stream starts at the end. Only new tags are returned. If the ID is not usable, the stream sends a
restartevent and starts at the end. A malformed ID gets therestartevent as its first message. A valid ID that is older than the stream's retention gets awelcomeevent first, followed byrestart.
Responses
Successfully started streaming operation.
The examples show events as an EventSource client parses them. On the wire, tag messages have no event: line and arrive as the default message type, and welcome and restart events carry data: {}.
Tags are batched over a window of about one second, with up to 1,000 tags in a single message.
When no other events are sent, the server sends an empty comment line (: ) as a keep-alive about every 30 seconds.
A goaway event is sent in place of welcome when the connection is refused, and the server then closes the connection. Its data.reason is either connection limit reached or server shutting down. A stream that is already open closes without an event when the server shuts down.
text/event-stream{
"id": "MXxhYVlRejdGZUpPMA",
"event": "welcome"
}{
"id": "MXxhYVlRejdGZUpPMA",
"event": "restart"
}{
"id": "MXxhYVlRejdGZUpPMA",
"event": "message",
"data": {
"tags": [
"tag1",
"tag2"
]
}
}{
"event": "error",
"data": {
"status": 500,
"message": "Stream ended unexpectedly"
}
}{
"id": "MXxhYVlRejdGZUpPMA",
"event": "goaway",
"data": {
"reason": "connection limit reached"
}
}The API version is earlier than v2021-03-25.
application/json{
"message": "This API is not available for this version"
}The request sent an invalid API token, or set includeAllDocuments or includeDrafts to true without an API token.
An invalid token is rejected on every request, including requests for published content only.
application/json{
"message": "Unauthorized"
}{
"message": "Session not found",
"error": "Unauthorized",
"errorCode": "SIO-401-ANF",
"statusCode": 401
}The request came from a browser origin that isn't in the project's CORS origins.
application/json{
"error": "Forbidden",
"message": "CORS Origin not allowed",
"statusCode": 403
}The request was sent to the API CDN (apicdn.sanity.io) instead of the API.
application/json{
"message": "Streaming sync tag invalidation events only supported via API, not APICDN"
}The Accept header doesn't allow text/event-stream. Requests without an Accept header are accepted.
application/json{
"message": "Unsupported content type"
}The server failed to start the stream.
application/json{
"message": "Internal error"
}