> 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. Enables users to create actions that will be performed on an entity at given time in the future. #### Currently supported entities and actions: * [Entry](/references/content-management-api/overview): publish and unpublish * [Asset](/references/content-management-api/overview): publish and unpublish * [Release](/references/content-management-api/overview): publish and unpublish Find out more regarding entry publish in [entry publish docs](/references/content-management-api/overview). #### Availability Scheduled action feature is globally available for all customers. #### Notifications If an entry fails to publish at the scheduled time due to validation errors, an email will be sent to the user that created the Scheduled Action informing that it failed. #### Limitations The current limit of scheduled actions in `scheduled` status is 500. Once it's reached, no additional scheduled actions can be created. In addition there is a limit of 200 scheduled actions that can be executed in a single minute. The scheduled date for a scheduled action when creating or updating must be between the current time and up to 5 years in the future. There is a limit of 200 entities when publishing an entity with references, e.g. a Compose page. The scheduled action will fail if the number of entities exceeds that limit. #### Scheduled action schema The scheduled action has the following properties: | Field | Type | Required | Description | | --------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- | | entity | Link | true | A reference to the entity object that the action is created for (Entry, Asset, Release). | | environment | Link | true | A reference to the environment object that the action is created for. | | scheduledFor | Object | true | The body of the scheduled action. | | scheduledFor.datetime | String | true | The `datetime` the scheduled action is scheduled for in ISO8601 format. | | scheduledFor.timezone | String | false | The `timezone` of the scheduled action. It should be a valid IANA timezone identifier. | | action | String | true | Action name for action to be scheduled | | sys | Object | true | System resource properties | | error | Object | false | Present when the `sys.status` is `failed`. Contains more details on what caused the action to fail. | | payload | Object | false | Object providing additional information about how the scheduled action will be executed | #### Scheduled action status Every scheduled action has a `sys.status` field. It contains one of the following values: | Status | Description | | --------- | ---------------------------------------------------------------- | | canceled | The action was canceled by the user and will never be processed. | | failed | The action failed to process successfully. | | scheduled | The initial status of the scheduled action. | | succeeded | The action has been processed successfully. | Once the scheduled action is created the status is set to `scheduled`. In case the scheduled action is canceled before the execution, the status is set to `canceled`. Once the scheduled action was executed the status is set to `succeeded` in case of successful execution and to `failed` if any error happened during execution process. #### Scheduled action payload Payload is used to provide additional information about how the scheduled action will be executed. It supports the following properties: | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | withReferences | Filters applied to references of the entity. **Note**: The entity needs to belong to a content type with annotations. **Note**: Currently only `'sys.contentType.metadata.annotations.ContentType[nin]': ['Contentful:AggregateRoot']` filter is supported and is required. | ## Scheduled actions collection For more information about scheduled actions in the web app, see our [Help Center article](https://www.contentful.com/help/scheduled-publishing/). [Get all scheduled actions of an entry](/references/content-management-api/scheduled-actions/get-all-scheduled-actions-of-an-entry) Use this endpoint to get all the scheduled actions of an entry. ### Collection filters Scheduled actions collection supports the following filters: | Params | Required | Description | | ----------------------------------------------------- | -------- | ----------------------------------------------------------- | | `?environment.sys.id="" ` | true | Filter by the external environment ID. | | `?entity.sys.id=1` | false | Filter by the list of entity ids | | `?sys.status[in]= ` | false | Filter by the list of the scheduled actions' statuses | | `?sys.status=` | false | Filter by single scheduled actions' status | | `?scheduledFor.datetime="ISO-time" ` | false | Filter by exact match of the scheduledFor.datetime property | | `?scheduledFor.datetime[lt\|lte\|gt\|gte]="ISO-time"` | false | Filter by comparison the scheduledFor.datetime property | ### Collection ordering Scheduled actions collection supports the following ordering options: | Params | Description | | ----------------------------- | ----------------------------------------------------------------------------- | | ?order=-scheduledFor.datetime | Descending order for scheduled actions; ascending if the parameter is absent. | ### Collection pagination The scheduled actions 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 pages object also contains the `prev` key for every request after the initial request. It contains the relative URL to the batch of items requested in the previous request. The default page size if `100` and the maximum allowed limit is `1000`. ### Permissions Any user can read all the scheduled actions in the entry. ## Get a Scheduled Action [Get a scheduled action](/references/content-management-api/scheduled-actions/get-a-scheduled-action) Use this method to fetch a single Scheduled Action. #### Permissions Any user with read access to the supported entities can fetch a given Scheduled Action. #### Errors * 404 Error is returned in case: * The `sys.id` is not found * Current user doesn't have access to space * User doesn't have permissions to read the entity (Release, Entry or Asset) in the Scheduled Action ## Create a scheduled action [Create a scheduled action](/references/content-management-api/scheduled-actions/create-a-scheduled-action) Use this endpoint to create a new scheduled action. When using this endpoint, an ID will be automatically generated for the created scheduled action and returned in the response. There's a limit of 200 scheduled actions in pending status per environment. An attempt to create more than 200 pending scheduled actions will result in an error. ### Create a scheduled action for a compose page Use this payload format when you want to create a scheduled action for an entry that belong to a [content type with annotations](/references/content-management-api/content-types#content-type). For example a Compose page. ``` { "entity": { "sys": { "type": "Link", "linkType": "Entry", "id": "5KsDBWseXY6QegucYAoacS" } }, "environment": { "sys": { "type": "Link", "linkType": "Environment", "id": "staging" } }, "scheduledFor": { "datetime": "2022-01-01T12:00:00.000Z", "timezone": "Europe/Berlin" }, "action": "publish", "payload": { "withReferences": { "sys.contentType.metadata.annotations.ContentType[nin]": [ "Contentful:AggregateRoot" ] } } } ``` #### Permissions Any user with the ability to perform the specified scheduled action to the referenced content. #### Errors * 400 Error is returned in case: * Environment is not found * Exceeds pending actions limit * The `payload.withReferences` is included for an entity without annotations * 422 Invalid request payload input return in following cases: * The body contains invalid payload * The `scheduledFor.datetime` is in the past or is not in the correct ISO format * The `scheduledFor.timezone` is not a valid IANA timezone identifier * The `action` is unsupported * The `payload.withReferences` is provided but it's not in a valid format. Only for `publish` action ## Update a scheduled action [Update a scheduled action](/references/content-management-api/scheduled-actions/update-a-scheduled-action) Use this method to update a scheduled action's time (at `scheduledFor.datetime`) or timezone (at `scheduledFor.timezone`). Changes to fields outside of `scheduledFor` are currently not supported and will result in an HTTP 400 Bad Request. #### Permissions Any user with the ability to perform the specified scheduled action to the referenced content. #### Errors * 400 Error is returned in case: * The version header is not provided * Property outside of `scheduledFor.datetime` and `scheduledFor.timezone` is changed * Scheduled action is not in status `scheduled` * An action is already scheduled for the same date and time * `entity.sys.id` is invalid * Environment is not found * Exceeds pending actions limit * The `payload.withReferences` is included for an entity without annotations * 409 Error is returned in case: * Version number is not a number * The version in the `X-Contentful-Version` header doesn't match the current scheduled action version * 422 Invalid request payload input return in following cases: * The body contains an invalid payload * The `scheduledFor.datetime` is missing * The `scheduledFor.datetime` is in the past or is not a valid ISO 8601 time * The `scheduledFor.datetime` is greater than 5 years (60 months) ahead of the current time * The `scheduledFor.timezone` is not a valid IANA timezone identifier * The `payload.withReferences` is provided but it's not in a valid format. Only for `publish` action ## Cancel a scheduled action [Cancel a scheduled action](/references/content-management-api/scheduled-actions/cancel-a-scheduled-action) Use this method to mark a scheduled action as canceled. #### Permissions Any user with publish access to an entry can set a scheduled action to canceled state. #### Errors * 400 Error is returned in case: * The `sys.status` is not in a `scheduled` state