Content Management API

Releases

Enables users to create releases that contains entries or assets and perform actions on them.

Currently supported actions:
  • Create release
  • Update release
  • Delete release
  • Fetch release
  • Query releases
  • Publish release
  • Unpublish release
  • Validate release

Availability

Releases feature is globally available for all customers. In the Contentful web app this feature is available for the customers that purchased Launch application.

Limitations

Release cannot contain more then 200 entities or assets in total.

Release schema

The release entity has following schema:

FieldTypeRequiredDescription
titleStringtrueThe releases title
entitiesObjecttrueThe object containing releases items
sysObjecttrueSystem resource properties

Releases

Create release

Use this endpoint to create a new release. When using this endpoint, an ID will be automatically generated for the created release and returned in the response.

Permissions

Any user can create new release.

Errors

  • 400 Error is returned in case:
    • property “linkType” is missing
    • property “linkType” is not “Entry” or “Asset”
    • environment is not found
  • 404 Error is returned in case:
    • current user doesn’t have access to space
    • current user doesn’t have access to provided entry
    • entity does not exist
  • 422 Error is returned in case:
    • provided entity ids are not unique
    • provided entity id is undefined
    • provided entityType is not Entry or Asset
    • exceed limit of entities in the release

Get all releases

Use this endpoint to fetch a 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.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:
    • Environment is not found
    • Property LinkType is missing when using “entities.sys.id[in]” filter
    • Property “linkType” is not “Entry” or “Asset”
  • 404 Error is returned in case:
    • Including an entry that user has no permissions to
    • 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:
    • provided entity ids are not unique
    • provided entity id is undefined
    • provided entityType is not Entry or Asset
    • exceed limit of entities in the release

Delete a release

Use this method to delete a release by provided ID.

Permissions

Only a user that created release or 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

There is only 1 validation at a time allowed for a single release. Initiating additional validation for the release that already has in progress would result in error.

Errors

  • 404 Error is returned in case:
    • The sys.id is not found
    • current user has no access to releases
  • 429 Error is returned in case:
    • current user has no access to entries
    • validation action is not publish or unpublish
    • exceeding the publish limit
    • release validation is already in progress

Published release

Publish release

Use this method to create a release action that publishes all entities that belong to release by provided ID.

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
    • current user has no access to releases
    • the version header is not provided.
  • 429 Error is returned in case:
    • exceeding the limit publish limit
    • exceeding the limit if in action is already created or in progress
    • fails with validation errors

Unpublish release

Use this method to create release action that unpublishes all entities that belong to release by provided ID.

Permissions

Any user with publish access to an entry can unpublish a release.

Errors

  • 404 Error is returned in case:
    • The sys.id is not found
    • current user has no access to releases
    • the version header is not provided.
  • 429 Error is returned in case:
    • exceeding the limit publish limit
    • exceeding the limit if in action is already created or in progress
    • fails with validation errors

Archived release

Archive release

Use this method to archive a release. Archiving a release will prevent publishes, unpublishes or schedules 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

Unarchive release

Use this method to unarchive an archived release. Unarchiving a release will enable 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 not 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 belongs to one or more releases.

Filters

There are following filters available on 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 single release action that belongs to specific release.

Permissions

Any user with read access to an entry can query release actions.

Errors

  • 404 Error is returned in case:
    • release not found
    • release action not found