Introduction

The Preview Session API previews unsaved edits to experiences, experience templates, experience fragments, and components. An editor sends updates to a session. A preview client reads the resulting experience, with content references resolved, or receives updates over a WebSocket. This resolved result is called a hydrated experience.

To connect your website to a preview session, see Set up live preview.

Basic API information

The API is split across two hosts:

All routes share the prefix /spaces/{spaceId}/environments/{environmentId}/preview_sessions.

Routes

Authentication

Management routes require a Content Management API token, sent as Authorization: Bearer <token>.

Use the same Content Management API token to create, read, update, and delete a session, and to update its entities. An entity update or deletion with another token returns 403, even if that token has permission to update preview sessions. A successful deletion returns 204 No Content with no response body.

GET /experience requires a Content Preview API access token, sent as Authorization: Bearer <token> or as the access_token query parameter. When both are present, the first access_token query parameter is used. A Content Delivery API token can’t be used.

How a session works

1. The editor client creates a session with POST /preview_sessions on the management host and receives a session ID.
2. The editor client sends each edit to /entities, using sys.id to identify the entity and sys.type to select its type. The session keeps the latest state.
3. A preview client reads the current hydrated experience with GET /preview_sessions/{sessionId}/experience, or subscribes to /subscribe to receive the latest preview state. Rapid edits may be combined into one update.
4. The session expires after 30 days without a management change.