Live Content API reference

The Live Content API is a more flexible and performant alternative to the Listen API.

This is a live API adhering to the Server Sent Events standard. It streams sync tags as they become invalid.

GET /vX/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.

• last-event-id: 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, i.e. only new tags will be returned.
  • If not usable (e.g. invalid encoding, or we have truncated the underlying stream so it no longer refers to a valid position, or it is not within a valid range), the first message emitted will be a restart message, 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 restart message. A client should assume a restart message invalidates earlier positions.

• 200 OK: If a streaming operation is started successfully.
• 406 Unacceptable: If the Accept header does not include text/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 error events.

• content-type will be text/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.

event: welcome

event: restart

In this message, the id field is the position.

id: MXxhYVlRejdGZUpPMA
data: {"tags": ["tag1","tag2"]}

event: error
data: {"status": 500, "message": "Internal Server Error"}

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.

: