Workflows overview

Workflows constrain how work items move between states in a project.

Learn more about workflows

The workflow object

Attributes

• created_at string (date-time)

  When the workflow was created.

• updated_at string (date-time)

  When the workflow was last updated.

• created_by_id string (uuid)

  The user who created the workflow.

• updated_by_id string (uuid) or null

  The user who last updated the workflow. null until someone updates it.

• description string

  Free-form description.

• id string (uuid)

  Unique identifier.

• is_active boolean

  Whether the record is active.

• is_default boolean

  Make this the default for its parent. Setting it clears the flag on the previous default.

• name string

  Display name.

• work_item_type_ids array of string

  Ids of the associated work item types.

Response200

{
  "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "name": "Example name",
  "description": "What this is for.",
  "is_active": true,
  "is_default": false,
  "work_item_type_ids": [
    "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
    "5a9c2e47-1b6d-4f83-a2e0-8d4c7b1f3e95"
  ],
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/	List workflows
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/	Get a workflow
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/	Create a workflow
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/	Update a workflow
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{pk}/	Delete a workflow
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/activities/	List workflow activities
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/activities/{pk}/	Get a workflow activity
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflow-fallback-preview/	Preview a workflow fallback

A workflow's states, transitions, transition hooks, and activity feed have their own pages: Workflow states, Workflow transitions, Workflow hooks, and Workflow activities.

Governed workspaces

In a workspace with workspace governance turned on, workflows live in the workspace catalog and have no project. These project routes look workflows up by project, so they don't list catalog workflows. A catalog workflow id returns 404 here and on the nested states, transitions, hooks, and activities routes. Manage catalog workflows with Workspace workflows.

These project routes work only in a governed workspace and return 409 states_managed_at_project elsewhere:

• Preview a workflow fallback counts the work items a re-type or a workflow switch would move.
• Work item type workflows show and set which catalog workflow each work item type uses in the project.

Response shaping

Every workflow read accepts ?fields= for sparse responses. See Sparse fields. Errors follow the shared problem+json contract.