> 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. Workflows definitions allow you to configure a pre-defined process for entries. Each workflow definition describes the schema for its workflows by a sequence of workflow steps which the executed workflows undergo. ### Limitations A workflow definition can define up to 20 steps. Defining more than 20 steps will result in a validation error. The current maximum limit for workflow definitions is 20. If you lose access to the workflow API due to a price and package downgrade we will ensure that you can delete and complete existing workflows. An overview for our pricing and packaging can be found [here](https://www.contentful.com/pricing/). ### Workflow definition schema Besides the sequence of workflow steps, there are multiple properties to specify how workflows behave. | Field | Type | Required | Description | | --------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | name | String | true | Name of the workflow definition | | description | String | false | Explaining notes, e.g. a description of the use case | | appliesTo | Array\[Object] \* | false | Target entries for which workflows of this definition can be used. | | flowType | String | false | Can be `no_restriction` (default) or `strict_neighbor`. See the following paragraphs for more guidance. | | startOnEntityCreation | Boolean | false | Automatically start a workflow on targeted entries when they are created (default: false). See the following paragraphs for more guidance. | | steps | Array\[Object] | false | Ordered list of steps which a workflow undergoes. The shape of a step is described in a following chapter. | | sys | Sys \*\* | true | System resource properties | \* The items in the list `appliesTo` must match the following shape: `{ linkType: "Entry", type: "Link", validations: [{ linkContentType: ["contentTypeA", "contentTypeB"] }] }` It is recommended to have only one item in `appliesTo` as well as only one item in `validations`. If you want to address multiple content types, you can do so by mentioning multiple within the list at `linkContentType`. \*\* In addition to the [common sys properties](#/introduction/common-resource-attributes), a workflow definition has the following extra `sys` properties | Field | Type | Description | | ---------- | ------- | ------------------------------------------------------------------------------------------------------------- | | isLocked | Boolean | If the set up of permission rules was incomplete, the definition is marked as locked until it is saved again. | | lockReason | string | Provides context about why the last save request wasn't successful. | ##### The flow type of a workflow definition The property `flowType` controls to which step a user can move a workflow. It supports the follow two modes: * `no_restriction`: Apply no restrictions when moving a workflow to another step. * `strict_neighbor`: Enforce non-admin users to only move to the previous or the following step. The workflow can only be marked as 'complete' upon reaching the last step. #### Automatically start workflows The property `startOnEntityCreation` will automatically start a workflow for newly created targeted entries. Each time you create an entry of a content type configured for this workflow definition, the workflow will start automatically. However, this does not mean that workflows are started for entries that were already created before setting this property to `true`. #### Assign multiple workflows to the same content type(s) You can choose to configure multiple workflows for the same content type. This allows different teams working on the same content type to use dedicated workflows for their own review processes and governance. ### Workflow step schema A step within a workflow definition is described by the following properties. | Field | Type | Required | Description | | ----------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | id | String | true \* | Internally defined ID | | name | String | true | Name of the workflow step | | description | String | false | Explaining note | | annotations | Array\[String] | false | List of meta tags. To render a color in the Contentful UI, add a string with the shape `cf-color-1` (allowed digits: 1-6). | | permissions | Array\[Object] | false | Allow or deny actions for selected users when a workflow is in this step. | | actions | Array\[Object] | false | Automated actions that are triggered when a workflow reaches this step. | \* When leaving out the `id` in a POST/ PUT request for a workflow definition, you create a new step at that position in the list. When you define it (in a PUT request), you thereby update the existing step with that `id`. #### Workflow step permission schema In addition to the permission defined by a users role, a workflow step can restrict or grant permissions for selected users or teams. The permissions can only apply to a single active step in a workflow. The user restrictions in step permissions do not apply to organization or space admins. One permission must provide the following properties: | Field | Type | Required | Description | | -------------------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------- | | type | String | true | Can be `entity_permission` or `workflow_permission`. \* | | configuration.effect | String | true | Can be `allow` or `deny`. | | configuration.action | String | true | Can be `edit` or `publish`. Publishing is only available for entity permissions (see `type`). | | configuration.actors | String \| Array\[Link] | true | Can be `all` or a list of user/ team links. Defines who is targeted by this permission rule. | \* There are two supported types for targeted resources: * `workflow_permission`: Use this together with the action being `edit` to explicitly allow or deny who can move the workflow to another step. * `entity_permission`: Grant or restrict permission to edit or publish the entry on which the workflow is being executed. ### Workflow step action schema When a workflow reaches a step, it will automatically trigger the actions defined for this step. Those actions can be one of the following three: * Send an email to a set of users and teams. Additionally, you can also use any valid email address. The email notifies about the workflow being moved to this step. So far, the template is fixed and cannot be changed. There may be only one email action per step. * Create an [entry task](/references/content-management-api/entry-tasks) with a customisable message and assign it one user or team. Optionally, you can define a due date. Please note that you need to have the tasks app installed. You can define up to three task actions per step. * Send a custom message via Slack to a selected (public) channel about the workflow being moved to another step. Please note that you need to have the Slack app installed to use its app action. There may be only one Slack action per step. Depending on the type, an action is defined by the following properties: | Field | Type | Required | Description | | ------------------------ | ---------------------- | ------------------ | --------------------------------------------------------------------------------------- | | type | String | true | Can be `email`, `task` or `app` (for Slack). | | configuration.recipients | Array\[Link \| String] | if type is `email` | Recipients of the sent out email. | | configuration.assignee | Link | if type is `task` | Assignee (user or team) of the created task. | | configuration.body | String | if type is `task` | Text of the created task. | | configuration.dueDate | Number | false | Days to add to the current timestamp to calculate the due date. | | appId | String | if type is `app` | ID of the installed Slack app. | | appActionId | String | if type is `app` | ID of the installed Slack app action. | | configuration.body | Object | false | Optional payload for the Slack app action. May be defined when the `type` equals `app`. | ## Workflow definitions collection [Get all workflow definitions](/references/content-management-api/workflow-definitions/get-all-workflow-definitions) This endpoint returns a paginated list of workflow definitions for a given environment. #### Permissions Any user can read workflow definitions. [Create a workflow definition](/references/content-management-api/workflow-definitions/create-a-workflow-definition) Use this endpoint to create a workflow definition. #### Permissions Only organization or space admins can create a workflow definition. ## Workflow definition [Get a workflow definition](/references/content-management-api/workflow-definitions/get-a-workflow-definition) #### Permissions Any user can read a workflow definition. [Update a workflow definition](/references/content-management-api/workflow-definitions/update-a-workflow-definition) #### Permissions Only organization or space admins can update a workflow definition. [Delete a workflow definition](/references/content-management-api/workflow-definitions/delete-a-workflow-definition) #### Permissions Only organization or space admins can delete a workflow definition.