> This page is for API Reference.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

## Overview

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](/developers/docs/experience-orchestration/experiences-sdk/live-preview).

## Basic API information

The API is split across two hosts:

| Purpose                               | Token                                                                                               | Host                                 | EU host                                 |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------- |
| Session management and entity updates | [Content Management API](/developers/docs/references/authentication#the-content-management-api) token               | `https://api.contentful.com`         | `https://api.eu.contentful.com`         |
| Current preview and live updates      | [Content Preview API](/developers/docs/references/authentication#the-content-delivery-and-preview-api) access token | `https://preview.xdn.contentful.com` | `https://preview.xdn.eu.contentful.com` |

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

## Routes

| Area               | Method and path                                                                                                      | Host       |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------- |
| Session management | `POST /preview_sessions`                                                                                             | Management |
| Session management | `GET /preview_sessions/{sessionId}`                                                                                  | Management |
| Session management | `PUT /preview_sessions/{sessionId}`                                                                                  | Management |
| Session management | `DELETE /preview_sessions/{sessionId}`                                                                               | Management |
| Entity updates     | `POST /preview_sessions/{sessionId}/experiences/{id}`                                                                | Management |
| Entity updates     | `POST /preview_sessions/{sessionId}/data_assemblies/{id}`                                                            | Management |
| Entity updates     | `POST /preview_sessions/{sessionId}/components/{id}`                                                                 | Management |
| Entity updates     | `POST /preview_sessions/{sessionId}/experience_templates/{id}`                                                       | Management |
| Entity updates     | `POST /preview_sessions/{sessionId}/experience_fragments/{id}`                                                       | Management |
| Current preview    | `GET /preview_sessions/{sessionId}/experience`                                                                       | Preview    |
| Live updates       | [`GET /preview_sessions/{sessionId}/subscribe`](/developers/docs/references/preview-session-api/live-updates-web-socket) (WebSocket) | Preview    |

## 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 the entity-specific route, with the entity ID in the path. The request body contains the complete entity configuration, not a partial patch, and does not need `sys`. The service overwrites any supplied `sys` with the route's entity ID and 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.