Content Management API

Timeline releases

Timeline is a feature that allows you to create, schedule and preview multiple upcoming versions of the same digital experience.

The Timeline feature is available on specific plans. For more information, reach out to your Sales representative.

Currently supported actions:

  • Create release
  • Update release
  • Delete release
  • Fetch release
  • Query relases
  • Publish release
  • Validate release

Limitations

A release cannot contain more than 200 entities in total.

Create release

Create 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.

You must set sys.schemaVersion to Release.v2, otherwise a Launch release will be created which is incompatible with Timeline.

Permissions

Any user can create a new release.

Errors

  • 400 Error is returned in case:
    • ThelinkType 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

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:

FilterDescription
sys.schemaVersionWhen 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.linkTypeFilter 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
pageNextIf present, will return the next page of releases. This value needs to be provided from a previous release query result.
orderOrders the query results. The available options include sys.updatedAt, -sys.updatedAt, -title, title, sys.createdAt and -sys.createdAt
limitLimit 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

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

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 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

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

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

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

Use this method to archive a release. Archiving a release will prevent publishing, unpublishing or scheduling in the target release.

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

Use this method to query release actions that belong to one or more releases.

Filters

The following filters are available for this endpoint:

FilterDescription
limitLimit the number of release actions in the response
orderReturns results ordered by the value specified. Supports sys.updatedAt, sys.createdAt, -sys.updatedAt, sys.createdAt
actionReturns 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)
uniqueByReturns 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

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