> 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/_mcp/server.
[Timeline](https://www.contentful.com/help/timeline/) is a feature that allows you to create, schedule and preview multiple upcoming versions of the same digital experience.
> **Info**
>
> The Timeline feature is available on specific plans. For more information, [reach out](https://www.contentful.com/contact/sales/) to your Sales representative.
#### Currently supported actions:
* Create release
* Update release
* Delete release
* Fetch release
* Query releases
* Publish release
* Validate release
#### Limitations
A release cannot contain more than 200 entities in total.
## Create release
[Create release](/references/content-management-api/releases/create-a-release)
Use this endpoint to create a new Timeline release. When using this endpoint, an ID will be automatically generated for the created release and returned in the response.
> **Info**
>
> You must set `sys.schemaVersion` to `Release.v2`, otherwise a [Launch release](/references/content-management-api/releases) will be created which is incompatible with Timeline.
#### Permissions
Any user can create a new release.
#### Errors
* 400 Error is returned in case:
* The`linkType` property is missing
* The `linkType` property is not `Entry` or `Asset`
* The environment is not found
* 404 Error is returned in case:
* The current user doesn't have access to the space
* The current user doesn't have access to the provided entry
* The entity doesn't exist
* 422 Error is returned in case:
* The provided entity IDs are not unique
* The provided entity ID is undefined
* The provided `entityType` is not `Entry` or `Asset`
* The limit of entities in the release is exceeded
## Get all releases
[Get all releases](/references/content-management-api/releases/get-all-releases)
Use this endpoint to fetch multiple releases.
### Releases collection
The releases collection endpoint implements cursor-based pagination.
The pages object contains the `next` key which contains the relative URL to the next batch of items.
The URL contains the same set of filters and limit as initially requested.
This key is presented only if there are available elements to be fetched that weren't returned from the current request because of the requested limit.
The default page size is `100` and the maximum allowed limit is `1000`.
#### Filters
These are the following filters (query params) available for this endpoint:
| Filter | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sys.schemaVersion` | When set to `Release.v2` only Timeline releases will be returned |
| `sys.id[in]` | Filter releases to those matching the comma-separated list of ids (e.g. `id1,id2`) |
| `sys.id[nin]` | Filter releases **excluding** those matching the comma-separated list of ids (e.g. `id1,id2`) |
| `sys.createdBy.sys.id[in]` | Filter releases by the creator ID to those matching the comma-separated list of ids (e.g. `id1,id2`) |
| `sys.status[in]` | Filter releases to those matching the comma-separated list of available statuses (e.g. `active,archived`) |
| `sys.status[nin]` | Filter releases **excluding** those matching the comma-separated list of available statuses (e.g. `active,archived`) |
| `entities.sys.id[in]` | Filter releases to those containing a comma-separated list of **entity ids** (e.g. `id1,id2`). Requires `entities.sys.linkType` |
| `entities.sys.linkType` | Filter releases by provided entity types, required for the "entities.sys.id\[in]" filter. Can be one of `Asset` or `Entry` |
| `entities[exists]` | Filter (boolean) indicating whether to return empty releases or non-empty releases. E.g. using `true` will return releases that have at least 1 Entry/Asset within. |
| `title[match]` | Filter releases using full text search on the `title` field. Learn more about full text search in the [Delivery API documentation](/references/content-delivery-api/overview) |
| `pageNext` | If present, will return the next page of releases. This value needs to be provided from a previous release query result. |
| `order` | Orders the query results. The available options include `sys.updatedAt`, `-sys.updatedAt`, `-title`, `title`, `sys.createdAt` and `-sys.createdAt` |
| `limit` | Limit the number of releases returned in the response (max. is `1000`) |
#### Permissions
Any user with read access to an entry can query releases.
#### Errors
* 400 Error is returned in case:
* The environment is not found
* The `linkType` property is missing when using the `entities.sys.id[in]` filter
* The `linkType` property is not `Entry` or `Asset`
* 404 Error is returned in case:
* The current user doesn't have access to an included entry
* The current user doesn't have access to space
## Release
[Get a release](/references/content-management-api/releases/get-a-release)
Use this method to fetch a single release.
#### Permissions
Any user with read access to an entry can get a release.
#### Errors
* 404 Error is returned in case:
* The `sys.id` is not found
* Current user doesn't have access to space
[Update release](/references/content-management-api/releases/update-a-release)
Use this method to update the release by provided ID.
#### Permissions
Any user with write access to an entry can update a release.
#### Errors
* 400 Error is returned in case:
* The version header is not provided
* 404 Error is returned in case:
* The `sys.id` is not found
* Current user doesn't have access to space
* Current user doesn't have access to the provided entity
* Entity does not exist
* 422 Error is returned in case:
* The provided entity IDs are not unique
* The provided entity ID is undefined
* The provided `entityType` is not `Entry` or `Asset`
* The limit of entities in the release is exceeded
[Delete a release](/references/content-management-api/releases/delete-a-release)
Use this method to delete a release by provided ID.
#### Permissions
Only the user that created the release or the admin can delete a release.
#### Errors
* 404 Error is returned in case:
* The `sys.id` is not found
## Validate release
[Create validation release action](/references/content-management-api/releases/create-a-validation-release-action)
Use this method to create a release action that validates a release identified by the provided ID asynchronously.
#### Permissions
Any user with publish access to an entry can validate a release.
#### Limitations
Only 1 validation at a time is allowed for a single release. An error occurs if you try to initiate an additional validation for the release that already has one in progress.
#### Errors
* 404 Error is returned in case:
* The `sys.id` is not found
* The current user doesn't have access to releases
* 429 Error is returned in case:
* The current user doesn't have access to entries
* The validation action is not **publish** or **unpublish**
* The **publish** limit has been exceeded
* A release validation is already in progress
## Published release
[Publish release](/references/content-management-api/releases/publish-a-release)
Use this method to create a release action that applies all entities that belong to release by provided ID. Note that upon successful publish the release will automatically be archived.
#### Permissions
Any user with publish access to an entry can publish a release.
#### Errors
* 404 Error is returned in case:
* The `sys.id` is not found
* The current user doesn't have access to releases
* The version header is not provided
* 429 Error is returned in case:
* The **publish** limit has been exceeded
* An action is already created or in progress and that limit is exceeded
* Validation errors occur
## Archived release
[Archive release](/references/content-management-api/releases/archive-a-release)
Use this method to archive a release. Archiving a release prevents publishing, unpublishing or scheduling in the target release. When a Timeline release is archived, all its content is also archived.
\
Archiving a Timeline release cannot be undone. [Unarchiving a release](/references/content-management-api/releases/unarchive-a-release) is not yet supported for Timeline releases and returns a `400` error.\
#### Permissions
Users with access to the release can archive it.
#### Errors
* 400 Error is returned in case:
* The release is already archived
* 409 Error is returned in case:
* Incorrect release version passed in the `X-Contentful-Version` header
## Release actions
Release actions are entities that contain information about actions performed in a release. These actions include `validate`, `publish` and `unpublish`.
[Get all release actions](/references/content-management-api/releases/get-all-release-actions)
Use this method to query release actions that belong to one or more releases.
#### Filters
The following filters are available for this endpoint:
| Filter | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `limit` | Limit the number of release actions in the response |
| `order` | Returns results ordered by the value specified. Supports `sys.updatedAt`, `sys.createdAt`, `-sys.updatedAt`, `sys.createdAt` |
| `action` | Returns results that match the action value. Supported values are `validate`, `publish` and `unpublish` |
| `sys.id[in]` | Comma-separated list of *release action* IDs. Fetches only the release actions specified |
| `sys.release.sys.id[in]` | Comma-separated list of *release* IDs. Filter all release actions by the release ID |
| `sys.status[in]` | Comma-separated list of status. Filter all release actions **including** the status (`succeeded`, `inProgress` or `created`) |
| `sys.status[nin]` | Comma-separated list of status. Filter all release actions **excluding** the status (`succeeded`, `inProgress` or `created`) |
| `uniqueBy` | Returns unique release actions by the field specified. Only supports `sys.release.sys.id` |
#### Permissions
Any user with read access to an entry/release can query release actions.
#### Errors
* 400 (BadRequest) Error is returned when:
* `sys.status[in]` and `sys.status[nin]` are present at the same time in the request
## Release action
[Get a release action](/references/content-management-api/releases/get-a-release-action)
Use this method to get a single release action that belongs to a specific release.
#### Permissions
Any user with read access to an entry can query release actions.
#### Errors
* 404 Error is returned in case:
* The release is not found
* The release action is not found
## Monitoring release status via webhooks
You can use [webhooks](/references/content-management-api/webhooks) to get notified when a release publish succeeds or fails without polling the release actions API.
Subscribe to the **`ReleaseAction`** topic with the **`execute`** event. When a publish completes (successfully or not), Contentful sends a webhook with the release action payload. Use `sys.status` to determine the outcome:
| `sys.status` | Meaning |
| ------------ | -------------------------------------- |
| `succeeded` | The release was published successfully |
| `failed` | The release publish failed |
The `action` field tells you what operation was performed (`publish`, `unpublish`, `validate`).
**Example payload for a failed publish:**
```json
{
"sys": {
"type": "ReleaseAction",
"release": { "sys": { "type": "Link", "linkType": "Release", "id": "" } },
"status": "failed",
"completedAt": "2026-07-03T07:48:10.800Z",
"schemaVersion": "Release.v2"
},
"action": "publish",
"error": {
"sys": { "id": "ValidationFailed", "type": "Error" },
"details": {
"errors": [
{
"sys": {
"id": "",
"type": "Link",
"linkType": "Entry"
},
"error": {
"sys": { "id": "InvalidEntry", "type": "Error" },
"details": {
"errors": [
{
"name": "required",
"path": ["fields", "slug"],
"details": "The property \"slug\" is required here"
}
]
},
"message": "Validation error"
}
}
]
},
"message": "Validation error"
}
}
```
To filter only publish-related events, check that `action === "publish"` and inspect `sys.status` for `"succeeded"` or `"failed"`.