Live Content API reference
The sync tag invalidation API underlying the Live Content API
The Live Content API is a more flexible and performant alternative to the Listen API. This page is reference documentation for interacting directly with the underlying API. For a general overview and usage guides, visit the Live Content API overview page.
This is a live API adhering to the Server Sent Events standard. It streams sync tags on published documents as they become invalid.
GET /v2021-03-25/data/live/events/<dataset>
The API does not require authentication. Since tags are opaque, we don’t consider these to pose any risk of information leakage.
Sync tags opaquely identify specific pieces of content that are returned in a query response.
Requests from the query API and clients include an array of syncTags in their response bodies. Store these tags and compare them with the tags returned from the Live Content API.
If the sync tag from a query matches a sync tag included in the Live Content event, that means the content in the document returned by that query has changed in some way. This is the indication that you should re-fetch the original query to retrieve the latest content.
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. A client can choose to pick any ID it has seen, but the intent is to allow a client to continue after disconnecting.
- If not given, the stream starts at the end. Only new tags are returned.
- If not usable (for example: invalid encoding, instances where we have truncated the underlying stream so it no longer refers to a valid position, or if the ID is not within a valid range), the first message emitted will be a
restartmessage, and the stream will start at the end. - We don’t guarantee the “lifetime” of a position. A client should always be prepared to receive a
restartmessage. A client should assume arestartmessage invalidates earlier positions.
includeAllVersionsboolean
Set to
trueto include version and draft changes. Requests made with this parameter must be authenticated with Viewer access rights. Defaults tofalse. In API versions prior to 2025-02-19, this wasincludeDrafts. Example:GET /v2025-02-19/data/live/events/<dataset>?includeAllVersions=true
- 200 OK: If a streaming operation is started successfully.
- 406 Unacceptable: If the
Acceptheader does not includetext/event-stream. - All errors are represented as other standard status code unless they occur after the stream have been started, in which case they are represented as
errorevents.
content-typewill betext/event-stream.
- The response body is a Server-Sent Events stream.
- The API may choose to disconnect at any time. It is the client’s responsibility to reconnect and continue from the last position.
Most message types contain an id field that is the “position” in the stream.
May be emitted at the beginning of stream in order for headers to be written.
id: MXxhYVlRejdGZUpPMA
event: welcome
If the client receives this message, it should purge their entire state. After a restart, the client should assume earlier positions are not valid.
id: MXxhYVlRejdGZUpPMA
event: restart
id: MXxhYVlRejdGZUpPMA
event: message
data: {"tags": ["tag1","tag2"]}
event: error
data: {"status": 500, "message": "Internal Server Error"}
This is emitted when a connection is rejected or had to be closed. For example, if the connection limits are reached.
The id field is the position at which the connection was rejected or closed. The data field will specify why the connection rejected/closed.
id: MXxhYVlRejdGZUpPMA
event: goaway
data: {"reason":"connection limit reached"}To prevent some clients from dropping the connection, the API regularly sends an empty comment. You can safely ignore this if you're listening for specific messages or errors.
: