Create a workflow definition

POST

https://api.contentful.com/spaces/:space_id/environments/:environment_id/workflow_definitions

POST

/spaces/:space_id/environments/:environment_id/workflow_definitions

$ curl -X POST https://api.contentful.com/spaces/yadj1kx9rmg0/environments/staging/workflow_definitions \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/vnd.contentful.management.v1+json" \
>      -d '{
>   "name": "name",
>   "description": "description",
>   "appliesTo": [
>     {
>       "type": "Link",
>       "linkType": "Entry",
>       "validations": [
>         {
>           "linkContentType": [
>             "content_type_a",
>             "content_type_b",
>             "content_type_c"
>           ]
>         }
>       ]
>     }
>   ],
>   "flowType": "strict_neighbor",
>   "startOnEntityCreation": true,
>   "steps": [
>     {
>       "name": "To Do",
>       "description": "Move to the next step when starting work",
>       "permissions": [
>         {
>           "type": "entity_permission",
>           "configuration": {
>             "actors": "all",
>             "effect": "deny",
>             "action": "publish"
>           }
>         },
>         {
>           "type": "workflow_permission",
>           "configuration": {
>             "actors": [
>               {
>                 "sys": {
>                   "type": "Link",
>                   "linkType": "User",
>                   "id": "someUserId"
>                 }
>               }
>             ],
>             "effect": "allow",
>             "action": "edit"
>           }
>         }
>       ],
>       "annotations": [
>         "cf-color-1",
>         "some-custom-annotation"
>       ],
>       "actions": [
>         {
>           "type": "email",
>           "configuration": {
>             "recipients": [
>               "custom@example.com",
>               {
>                 "sys": {
>                   "type": "Link",
>                   "linkType": "Team",
>                   "id": "someTeamId"
>                 }
>               }
>             ]
>           }
>         },
>         {
>           "type": "task",
>           "configuration": {
>             "assignee": {
>               "sys": {
>                 "type": "Link",
>                 "linkType": "Team",
>                 "id": "someTeamId"
>               }
>             },
>             "body": "Please take care of this until Friday.",
>             "dueDate": "3"
>           }
>         },
>         {
>           "type": "app",
>           "appId": "theSlackAppId",
>           "appActionId": "theSlackAppActionId",
>           "configuration": {
>             "body": {
>               "workspaceId": "someConnectedSlackWorkspaceId",
>               "channelId": "someSlackChannelId",
>               "message": "myCustomSlackMessage"
>             }
>           }
>         }
>       ]
>     },
>     {
>       "name": "To Do",
>       "description": "Move to the next step when starting work",
>       "permissions": [
>         {
>           "type": "entity_permission",
>           "configuration": {
>             "actors": "all",
>             "effect": "deny",
>             "action": "publish"
>           }
>         },
>         {
>           "type": "workflow_permission",
>           "configuration": {
>             "actors": [
>               {
>                 "sys": {
>                   "type": "Link",
>                   "linkType": "User",
>                   "id": "someUserId"
>                 }
>               }
>             ],
>             "effect": "allow",
>             "action": "edit"
>           }
>         }
>       ],
>       "annotations": [
>         "cf-color-1",
>         "some-custom-annotation"
>       ],
>       "actions": [
>         {
>           "type": "email",
>           "configuration": {
>             "recipients": [
>               "custom@example.com",
>               {
>                 "sys": {
>                   "type": "Link",
>                   "linkType": "Team",
>                   "id": "someTeamId"
>                 }
>               }
>             ]
>           }
>         },
>         {
>           "type": "task",
>           "configuration": {
>             "assignee": {
>               "sys": {
>                 "type": "Link",
>                 "linkType": "Team",
>                 "id": "someTeamId"
>               }
>             },
>             "body": "Please take care of this until Friday.",
>             "dueDate": "3"
>           }
>         },
>         {
>           "type": "app",
>           "appId": "theSlackAppId",
>           "appActionId": "theSlackAppActionId",
>           "configuration": {
>             "body": {
>               "workspaceId": "someConnectedSlackWorkspaceId",
>               "channelId": "someSlackChannelId",
>               "message": "myCustomSlackMessage"
>             }
>           }
>         }
>       ]
>     }
>   ]
> }'

201Create a standard workflow definition

1 {
2   "name": "name",
3   "description": "description",
4   "appliesTo": [
5     {
6       "type": "Link",
7       "linkType": "Entry",
8       "validations": [
9         {
10           "linkContentType": [
11             "content_type_a",
12             "content_type_b",
13             "content_type_c"
14           ]
15         }
16       ]
17     }
18   ],
19   "flowType": "strict_neighbor",
20   "startOnEntityCreation": true,
21   "steps": [
22     {
23       "id": "someStepId",
24       "name": "To Do",
25       "description": "Move to the next step when starting work",
26       "permissions": [
27         {
28           "type": "entity_permission",
29           "configuration": {
30             "actors": "all",
31             "effect": "deny",
32             "action": "publish"
33           }
34         },
35         {
36           "type": "workflow_permission",
37           "configuration": {
38             "actors": [
39               {
40                 "sys": {
41                   "type": "Link",
42                   "linkType": "User",
43                   "id": "someUserId"
44                 }
45               }
46             ],
47             "effect": "allow",
48             "action": "edit"
49           }
50         }
51       ],
52       "annotations": [
53         "cf-color-1",
54         "some-custom-annotation"
55       ],
56       "actions": [
57         {
58           "type": "email",
59           "configuration": {
60             "recipients": [
61               "custom@example.com",
62               {
63                 "sys": {
64                   "type": "Link",
65                   "linkType": "Team",
66                   "id": "someTeamId"
67                 }
68               }
69             ]
70           }
71         },
72         {
73           "type": "task",
74           "configuration": {
75             "assignee": {
76               "sys": {
77                 "type": "Link",
78                 "linkType": "Team",
79                 "id": "someTeamId"
80               }
81             },
82             "body": "Please take care of this until Friday.",
83             "dueDate": "3"
84           }
85         },
86         {
87           "type": "app",
88           "appId": "theSlackAppId",
89           "appActionId": "theSlackAppActionId",
90           "configuration": {
91             "body": {
92               "workspaceId": "someConnectedSlackWorkspaceId",
93               "channelId": "someSlackChannelId",
94               "message": "myCustomSlackMessage"
95             }
96           }
97         }
98       ]
99     },
100     {
101       "name": "To Do",
102       "description": "Move to the next step when starting work",
103       "permissions": [
104         {
105           "type": "entity_permission",
106           "configuration": {
107             "actors": "all",
108             "effect": "deny",
109             "action": "publish"
110           }
111         },
112         {
113           "type": "workflow_permission",
114           "configuration": {
115             "actors": [
116               {
117                 "sys": {
118                   "type": "Link",
119                   "linkType": "User",
120                   "id": "someUserId"
121                 }
122               }
123             ],
124             "effect": "allow",
125             "action": "edit"
126           }
127         }
128       ],
129       "annotations": [
130         "cf-color-1",
131         "some-custom-annotation"
132       ],
133       "actions": [
134         {
135           "type": "email",
136           "configuration": {
137             "recipients": [
138               "custom@example.com",
139               {
140                 "sys": {
141                   "type": "Link",
142                   "linkType": "Team",
143                   "id": "someTeamId"
144                 }
145               }
146             ]
147           }
148         },
149         {
150           "type": "task",
151           "configuration": {
152             "assignee": {
153               "sys": {
154                 "type": "Link",
155                 "linkType": "Team",
156                 "id": "someTeamId"
157               }
158             },
159             "body": "Please take care of this until Friday.",
160             "dueDate": "3"
161           }
162         },
163         {
164           "type": "app",
165           "appId": "theSlackAppId",
166           "appActionId": "theSlackAppActionId",
167           "configuration": {
168             "body": {
169               "workspaceId": "someConnectedSlackWorkspaceId",
170               "channelId": "someSlackChannelId",
171               "message": "myCustomSlackMessage"
172             }
173           }
174         }
175       ]
176     }
177   ],
178   "sys": {
179     "id": "someWorkflowDefinitionId",
180     "type": "WorkflowDefinition",
181     "environment": {
182       "sys": {
183         "id": "staging",
184         "linkType": "Environment",
185         "type": "Link"
186       }
187     },
188     "space": {
189       "sys": {
190         "id": "yadj1kx9rmg0",
191         "linkType": "Space",
192         "type": "Link"
193       }
194     },
195     "isLocked": false,
196     "version": 1,
197     "updatedAt": "2025-06-13T04:06:37.000Z",
198     "updatedBy": {
199       "sys": {
200         "linkType": "User",
201         "id": "1xGZIRXr2WPnsLkKfREo0z",
202         "type": "Link"
203       }
204     },
205     "createdAt": "2025-06-13T04:06:37.000Z",
206     "createdBy": {
207       "sys": {
208         "linkType": "User",
209         "id": "someUserId",
210         "type": "Link"
211       }
212     }
213   }
214 }

Creates a new workflow definition. Only org or space admins can create workflow definitions.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

space_idstringRequired

ID of the space in form of a string

environment_idstringRequired

ID of the environment in form of a string

Request

This endpoint expects a map from strings to any.

Response headers

Content-Typestring

Content-Type

Response

Created - Resource created successfully