Live updates (WebSocket)

Subscribe to a preview session to receive the hydrated experience whenever it changes, without polling.

GET wss://preview.xdn.contentful.com/spaces/{spaceId}/environments/{environmentId}/preview_sessions/{sessionId}/subscribe?access_token={previewToken}

For EU data residency, use wss://preview.xdn.eu.contentful.com.

This route upgrades the request to a WebSocket connection, so it isn’t part of the REST reference.

Authentication

Send a Content Preview API access token. Browsers can’t set headers on a WebSocket handshake, so pass the token as the access_token query parameter. Other clients can send Authorization: Bearer <token> instead. If you send both, they must be identical.

Tokens in a query string can appear in logs. Use a token that only grants preview access.

Messages

Every message is a JSON object with a type and a data field.

After connecting, the server sends the current preview or an error. Later updates contain the latest preview state. Rapid edits may be combined into one update, so a next message does not acknowledge an individual edit.

If the preview token becomes invalid or loses access, the server sends an error and closes the connection with 1008 and the reason authorization-lost.

<!— prettier-ignore —>

{"type":"ping","data":{}}

Send the exact compact JSON text above, for example with JSON.stringify({ type: "ping", data: {} }).

A next message larger than 7,000,000 UTF-8 bytes, including its JSON envelope, is replaced by an error message with the ID PayloadTooLarge.

Connection errors

The server refuses the upgrade with an HTTP status instead of opening the socket.

Closing codes