• Cheat sheets
  • Documentation
  • API reference
  • Product updates
  • Sign in
Kontent.ai Learn
  • Try Kontent.ai
  • Plan
  • Set up
  • Model
  • Develop
  • Create
Management API v2
API Reference
    • About Management API
    • Postman collection
    • SDKs
    • Authentication
    • API keys
    • API limitations
    • Guidelines on handling changes
      • Introduction
      • Workflow object
        Schema
      • Add a workflow
        POST
      • Retrieve workflows
        GET
      • D
        Retrieve workflow steps
        GET
      • Update a workflow
        PUT
      • Delete a workflow
        DELETE

Workflows

Every project environment comes with a single workflow marked as Default. In subscriptions with multiple workflows, your environments might contain several workflows with different workflow steps.The workflows themselves consist of a number of steps, with two predefined steps, Published and Archived. Workflow steps indicate a specific stage in the content production process. For example, Draft -> Review -> Legal approval -> Published. Every variant of a content item (such as English, Spanish, French) can be moved to a specific workflow step. The combination of workflow and its workflow step might affect who can edit the variant and who can move the variant to another workflow step. Check how to set up a workflow for your content.

Workflow object

id
string · read-only · uuid
The workflow's internal ID. The ID of the default workflow is always 00000000-0000-0000-0000-000000000000.
name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Show child attributes
steps[]
required · array
The workflow steps in this workflow.
Show child attributes
published_step
required · object
The workflow's predefined Published workflow step.
Show child attributes
scheduled_step
object · read-only
The workflow's predefined Scheduled workflow step.
Show child attributes
archived_step
required · object
The workflow's predefined Archived workflow step.
Show child attributes
JSON
{
  "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
  "name": "My workflow",
  "codename": "my_workflow",
  "scopes": [
    {
      "content_types": [
        {
          "id": "1cdb6e21-3330-4f0f-88cd-171098950e4f"
        },
        {
          "id": "2ea20d43-5293-43a4-8bd2-9674a92b20ec"
        }
      ],
      "collections": [
        {
          "id": "b15b6050-80d8-406d-bf21-3012e4ad0ac5"
        },
        {
          "id": "af665269-5b03-409d-b6e4-81a8b34e97fc"
        }
      ]
    }
  ],
  "steps": {
    "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
    "name": "Draft",
    "codename": "draft",
    "color": "red",
    "transitions_to": [
      {
        "step": {
          "id": "c199950d-99f0-4983-b711-6c4c91624b22"
        }
      },
      {
        "step": {
          "id": "7a535a69-ad34-47f8-806a-def1fdf4d391"
        }
      }
    ],
    "role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  },
  "published_step": {
    "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    "name": "Published",
    "codename": "published",
    "unpublish_role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ],
    "create_new_version_role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  },
  "scheduled_step": {
    "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    "name": "Scheduled",
    "codename": "scheduled"
  },
  "archived_step": {
    "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    "name": "Archived",
    "codename": "archived",
    "role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  }
}

Add a workflow

Create a new workflow.
POST
https://manage.kontent.ai/v2/projects/{environment_id}/workflows

Request

Path parameters

environment_id
required · string
Identifies your environment.

Body schema

Application/json

Specify the new workflow.

name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Show child attributes
steps[]
required · array
The workflow steps in this workflow.
Show child attributes
published_step
required · object
The workflow's predefined Published workflow step.
Show child attributes
archived_step
required · object
The workflow's predefined Archived workflow step.
Show child attributes

Request samples

Payload
TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .addWorkflow()
  .withData({
    name: 'My workflow',
    scopes: [
      {
        content_types: [
          {
            id: '1aeb9220-f167-4f8e-a7db-1bfec365fa80',
          },
        ],
        collections: [
          {
            id: 'b15b6050-80d8-406d-bf21-3012e4ad0ac5',
          },
        ],
      },
    ],
    steps: [
      {
        name: 'First step',
        codename: 'first_step',
        color: 'sky-blue',
        transitions_to: [
          {
            step: {
              codename: 'second_step',
            },
          },
        ],
        role_ids: [],
      },
      {
        name: 'Second step',
        codename: 'second_step',
        color: 'rose',
        transitions_to: [
          {
            step: {
              codename: 'published',
            },
          },
        ],
        role_ids: ['e796887c-38a1-4ab2-a999-c40861bb7a4b'],
      },
    ],
    published_step: {
      unpublish_role_ids: ['e796887c-38a1-4ab2-a999-c40861bb7a4b'],
      create_new_version_role_ids: [],
    },
    archived_step: {
      role_ids: [],
    },
  })
  .toPromise();

Response

Status (201)
The created workflow.
id
string · read-only · uuid
The workflow's internal ID. The ID of the default workflow is always 00000000-0000-0000-0000-000000000000.
name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Show child attributes
steps[]
required · array
The workflow steps in this workflow.
Show child attributes
published_step
required · object
The workflow's predefined Published workflow step.
Show child attributes
scheduled_step
object · read-only
The workflow's predefined Scheduled workflow step.
Show child attributes
archived_step
required · object
The workflow's predefined Archived workflow step.
Show child attributes

Example responses

201
400
{
  "id": "705c3bd8-29c6-466c-b42b-6c6c3887786e",
  "name": "My workflow",
  "codename": "my_workflow",
  "scopes": [
    {
      "content_types": [
        {
          "id": "1aeb9220-f167-4f8e-a7db-1bfec365fa80"
        }
      ],
      "collections": [
        {
          "id": "b15b6050-80d8-406d-bf21-3012e4ad0ac5"
        }
      ]
    }
  ],
  "steps": [
    {
      "id": "2044477d-36aa-4ad5-91de-eaa2927ab173",
      "name": "First step",
      "codename": "first_step",
      "color": "sky-blue",
      "transitions_to": [
        {
          "step": {
            "id": "c236dedd-a216-47fa-b0c0-0ea33877f357"
          }
        }
      ],
      "role_ids": []
    },
    {
      "id": "c236dedd-a216-47fa-b0c0-0ea33877f357",
      "name": "Second step",
      "codename": "second_step",
      "color": "rose",
      "transitions_to": [
        {
          "step": {
            "id": "c199950d-99f0-4983-b711-6c4c91624b22"
          }
        }
      ],
      "role_ids": [
        "e796887c-38a1-4ab2-a999-c40861bb7a4b"
      ]
    }
  ],
  "published_step": {
    "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    "name": "Published",
    "codename": "published",
    "unpublish_role_ids": [
      "e796887c-38a1-4ab2-a999-c40861bb7a4b"
    ],
    "create_new_version_role_ids": []
  },
  "archived_step": {
    "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    "name": "Archived",
    "codename": "archived",
    "role_ids": []
  }
}

Retrieve workflows

Retrieve a list of workflows with information about the workflow steps they define.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/workflows

Request

Path parameters

environment_id
required · string
Identifies your environment.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client.listWorkflows().toPromise();

Response

Status (200)
Workflows in the specified environment.
array

Hide child attributes
id
string · read-only · uuid
The workflow's internal ID. The ID of the default workflow is always 00000000-0000-0000-0000-000000000000.
name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Hide child attributes
content_types[]
array
References to the content types limited to this workflow.
Hide child attributes
id
string · uuid
The referenced object's internal ID.
collections[]
array
References to the content types limited to this workflow.
Hide child attributes
id
string · uuid
The referenced object's internal ID.
steps[]
required · array
The workflow steps in this workflow.
Hide child attributes
id
string · read-only · uuid
The workflow step's internal ID.
name
required · string · 1-30 chars
The workflow step's display name.
codename
required · string · 1-40 chars
The workflow step's codename.
color
required · string
The workflow step's color in a human-readable format.
transitions_to[]
required · array · min. 1 items · unique items
References to the workflow steps that this step can transition to. Workflow steps can be referenced either by their codename or internal ID.
Hide child attributes
step
required · object
Reference to a specific object in the environment.
Hide child attributes
id
string · uuid
The referenced object's internal ID.
role_ids[]
required · array
The roles that can work with this step, represented by their internal IDs. If empty, all roles can work with this step.
published_step
required · object
The workflow's predefined Published workflow step.
Hide child attributes
id
string · uuid
The Published workflow step's internal ID.
name
string
The Published workflow step's display name.
codename
string
The Published workflow step's codename.
unpublish_role_ids[]
array · min. 1 items
The internal IDs of the roles that can unpublish and archive content items using this workflow. If empty, all roles can unpublish and archive content items.
create_new_version_role_ids[]
array · min. 1 items
The internal IDs of the roles that can create new versions of content items using this workflow. If empty, all roles can create new versions.
scheduled_step
object · read-only
The workflow's predefined Scheduled workflow step.
Hide child attributes
id
string · uuid
The Scheduled workflow step's internal ID.
name
string
The Scheduled workflow step's display name.
codename
string
The Scheduled workflow step's codename.
archived_step
required · object
The workflow's predefined Archived workflow step.
Hide child attributes
id
string · uuid
The Archived workflow step's internal ID.
name
string
The Archived workflow step's display name.
codename
string
The Archived workflow step's codename.
role_ids[]
array · min. 1 items
The internal IDs of the roles that can restore archived content items using this workflow. If empty, all roles can restore archived content items.

Example responses

200
{
  "": {
    "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
    "name": "My workflow",
    "codename": "my_workflow",
    "scopes": [
      {
        "content_types": [
          {
            "id": "1cdb6e21-3330-4f0f-88cd-171098950e4f"
          },
          {
            "id": "2ea20d43-5293-43a4-8bd2-9674a92b20ec"
          }
        ],
        "collections": [
          {
            "id": "b15b6050-80d8-406d-bf21-3012e4ad0ac5"
          },
          {
            "id": "af665269-5b03-409d-b6e4-81a8b34e97fc"
          }
        ]
      }
    ],
    "steps": {
      "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
      "name": "Draft",
      "codename": "draft",
      "color": "red",
      "transitions_to": [
        {
          "step": {
            "id": "c199950d-99f0-4983-b711-6c4c91624b22"
          }
        },
        {
          "step": {
            "id": "7a535a69-ad34-47f8-806a-def1fdf4d391"
          }
        }
      ],
      "role_ids": [
        "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    },
    "published_step": {
      "id": "c199950d-99f0-4983-b711-6c4c91624b22",
      "name": "Published",
      "codename": "published",
      "unpublish_role_ids": [
        "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ],
      "create_new_version_role_ids": [
        "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    },
    "scheduled_step": {
      "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
      "name": "Scheduled",
      "codename": "scheduled"
    },
    "archived_step": {
      "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
      "name": "Archived",
      "codename": "archived",
      "role_ids": [
        "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    }
  }
}

Retrieve workflow steps

Deprecated
Get the workflow steps from the default workflow in your environment.
Deprecation noticeIn April 2022, this endpoint was deprecated in favor of the Retrieve workflows endpoint, which supports multiple workflows.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/workflow

Request

Path parameters

environment_id
required · string
Identifies your environment.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client.listWorkflows().toPromise();
const steps = response.data.find(
  (workflow) => workflow.codeName === 'default',
).steps;

Response

Status (200)
A list of workflow steps in the specified environment.
array · unique items

Hide child attributes
id
required · string · uuid
The workflow step's internal ID.
name
required · string
The workflow step's display name.
codename
required · string
The workflow step's codename.
transitions_to[]
required · array · unique items
The workflow steps that this step can transition to, represented by their internal IDs.

Example responses

200
[
  {
    "id": "eee6db3b-545a-4785-8e86-e3772c8756f9",
    "name": "Draft",
    "codename": "draft",
    "transitions_to": [
      "c199950d-99f0-4983-b711-6c4c91624b22",
      "7a535a69-ad34-47f8-806a-def1fdf4d391"
    ]
  },
  {
    "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    "name": "Scheduled",
    "codename": "scheduled",
    "transitions_to": []
  },
  {
    "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    "name": "Published",
    "codename": "published",
    "transitions_to": []
  },
  {
    "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    "name": "Archived",
    "codename": "archived",
    "transitions_to": []
  }
]

Update a workflow

Update an existing workflow, manage its scope, workflow steps and their transitions, and role permissions. Always make sure that all steps eventually transition to the Published step.When removing a workflow step, make sure the step is not in use. You can't remove a used workflow step.
PUT
https://manage.kontent.ai/v2/projects/{environment_id}/workflows/{workflow_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
workflow_identifier
required · string
Identifies the workflow by its internal ID (e.g., 8bfdb62d-7aa1-473b-9d80-311ef93db108) or codename (e.g., codename/my-workflow).

Body schema

Application/json

Specify what you want to update in the workflow.

name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Show child attributes
steps[]
required · array
The workflow steps in this workflow.
Prefer codenames over IDs when referring to workflow stepsYou can reference existing workflow steps by their codename or ID. We recommend using codenames because it makes your code cleaner and easier to manage. Use ID only when you need to change the codename of a workflow step. If you want to reuse codenames of existing workflow steps in new workflow steps, you need to make two requests. First remove the workflow step with the desired codename. This make the codename available. Then add a new workflow step.
Show child attributes
published_step
required · object
The workflow's predefined Published workflow step.
Show child attributes
archived_step
required · object
The workflow's predefined Archived workflow step.
Show child attributes

Request samples

Payload
TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .updateWorkflow()
  .byWorkflowId('f9f28df0-9dec-4ee3-b087-c501e4b75347')
  //.byWorkflowCodename('my-workflow')
  .withData({
    name: 'My workflow',
    scopes: [
      {
        content_types: [
          {
            codename: 'article',
          },
        ],
        collections: [
          {
            id: 'b15b6050-80d8-406d-bf21-3012e4ad0ac5',
          },
        ],
      },
    ],
    steps: [
      {
        name: 'First step',
        codename: 'first_step',
        color: 'sky-blue',
        transitions_to: [
          {
            step: {
              id: '16221cc2-bd22-4414-a513-f3e555c0fc93',
            },
          },
          {
            step: {
              codename: 'archived',
            },
          },
        ],
        role_ids: ['e796887c-38a1-4ab2-a999-c40861bb7a4b'],
      },
      {
        name: 'Renamed Second step',
        codename: 'second_step_renamed',
        color: 'rose',
        id: '16221cc2-bd22-4414-a513-f3e555c0fc93',
        transitions_to: [
          {
            step: {
              codename: 'published',
            },
          },
        ],
        role_ids: [],
      },
    ],
    published_step: {
      unpublish_role_ids: [],
      create_new_version_role_ids: ['e796887c-38a1-4ab2-a999-c40861bb7a4b'],
    },
    archived_step: {
      role_ids: ['e796887c-38a1-4ab2-a999-c40861bb7a4b'],
    },
  })
  .toPromise();

Response

Status (200)
The updated workflow.
id
string · read-only · uuid
The workflow's internal ID. The ID of the default workflow is always 00000000-0000-0000-0000-000000000000.
name
required · string · 1-200 chars
The workflow's display name.
codename
string · 1-60 chars
The workflow's codename.
scopes[]
required · array
Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.
Show child attributes
steps[]
required · array
The workflow steps in this workflow.
Show child attributes
published_step
required · object
The workflow's predefined Published workflow step.
Show child attributes
scheduled_step
object · read-only
The workflow's predefined Scheduled workflow step.
Show child attributes
archived_step
required · object
The workflow's predefined Archived workflow step.
Show child attributes

Example responses

200
400
404
{
  "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
  "name": "My workflow",
  "codename": "my_workflow",
  "scopes": [
    {
      "content_types": [
        {
          "id": "1cdb6e21-3330-4f0f-88cd-171098950e4f"
        },
        {
          "id": "2ea20d43-5293-43a4-8bd2-9674a92b20ec"
        }
      ],
      "collections": [
        {
          "id": "b15b6050-80d8-406d-bf21-3012e4ad0ac5"
        },
        {
          "id": "af665269-5b03-409d-b6e4-81a8b34e97fc"
        }
      ]
    }
  ],
  "steps": {
    "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
    "name": "Draft",
    "codename": "draft",
    "color": "red",
    "transitions_to": [
      {
        "step": {
          "id": "c199950d-99f0-4983-b711-6c4c91624b22"
        }
      },
      {
        "step": {
          "id": "7a535a69-ad34-47f8-806a-def1fdf4d391"
        }
      }
    ],
    "role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  },
  "published_step": {
    "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    "name": "Published",
    "codename": "published",
    "unpublish_role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ],
    "create_new_version_role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  },
  "scheduled_step": {
    "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    "name": "Scheduled",
    "codename": "scheduled"
  },
  "archived_step": {
    "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    "name": "Archived",
    "codename": "archived",
    "role_ids": [
      "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
    ]
  }
}

Delete a workflow

Deletes an unused workflow.
DELETE
https://manage.kontent.ai/v2/projects/{environment_id}/workflows/{workflow_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
workflow_identifier
required · string
Identifies the workflow by its internal ID (e.g., 8bfdb62d-7aa1-473b-9d80-311ef93db108) or codename (e.g., codename/my-workflow).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .deleteWorkflow()
  .byWorkflowId('f9f28df0-9dec-4ee3-b087-c501e4b75347')
  //.byWorkflowCodename('my-workflow')
  .toPromise();

Response

Status (204)
The specified workflow was deleted.
Empty response

Example responses

400
404
{
  "request_id": "703be4d0773e5647",
  "error_code": 235,
  "message": "The default workflow '00000000-0000-0000-0000-000000000000' cannot be deleted."
}
Copyright © 2025 Kontent.ai. All rights reserved.
  • Web
  • Privacy policy
  • Cookies policy
  • Consent settings
  • Security
  • GDPR