Workflow states overview

Workflow states are the states attached to a project workflow.

The workflow state object

Attributes

• allow_issue_creation boolean

  Whether work items can be created in this state.

• created_at string (date-time)

  When the workflow state was created.

• updated_at string (date-time)

  When the workflow state was last updated.

• created_by_id string (uuid)

  The user who created the workflow state.

• updated_by_id string (uuid) or null

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

• id string (uuid)

  Unique identifier.

• is_default boolean

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

• state_id string (uuid)

  The related state.

• type string

  How the state behaves in the workflow. One of transition or approval.

• workflow_id string (uuid)

  The related workflow.

Response200

{
  "id": "8a5f3c1e-6d27-4b94-a0c8-2e7f1b9d4a63",
  "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "workflow_id": "9e3f6a2c-7b14-4d8e-a5c1-2f60b8d4e719",
  "type": "transition",
  "allow_issue_creation": true,
  "is_default": false,
  "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/{workflow_id}/states/	List workflow states
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/	Get a workflow state
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/	Create a workflow state
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/	Update a workflow state
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/states/{pk}/	Delete a workflow state

Transitions between these states, and the hooks on them, are under Workflow transitions.

Governed workspaces

In a workspace with workspace governance turned on, workflows and their states live in the workspace catalog and have no project. These project routes look the workflow up by project, so a catalog workflow id returns 404. Manage catalog workflow states with Workspace workflow states. See Workspace workflows for the catalog.

Response shaping

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