Workflow transitions overview

Workflow transitions define the allowed moves between workflow states, and who may approve them.

The workflow transition object

Attributes

• created_at string (date-time)

  When the workflow transition was created.

• updated_at string (date-time)

  When the workflow transition was last updated.

• created_by_id string (uuid)

  The user who created the workflow transition.

• updated_by_id string (uuid) or null

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

• id string (uuid)

  Unique identifier for the transition.

• member_ids array of string

  ids of the members who may approve the transition.

• rejection_state_id string (uuid)

  The state a work item moves to when the transition is rejected.

• required_approvals integer

  How many approvals a transition needs before it may run.

• transition_state_id string (uuid)

  The state the transition moves a work item to.

• workflow_state_id string (uuid)

  The workflow state the transition starts from.

Response200

{
  "id": "5c8d2e71-4a9f-4b36-8e05-d17f3a6b9c42",
  "workflow_state_id": "8a5f3c1e-6d27-4b94-a0c8-2e7f1b9d4a63",
  "transition_state_id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
  "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "required_approvals": 1,
  "member_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
  "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}/state-transitions/	List workflow transitions
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/	Get a workflow transition
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/	Create a workflow transition
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/	Update a workflow transition
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{pk}/	Delete a workflow transition
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/	List workflow hooks
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/{pk}/	Get a workflow hook
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/	Create a workflow hook
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/{pk}/	Update a workflow hook
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/{pk}/	Delete a workflow hook
GET	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/{pk}/executions/	List workflow hook executions
POST	/api/v2/workspaces/{slug}/projects/{project_id}/workflows/{workflow_id}/state-transitions/{transition_id}/hooks/{pk}/regenerate-webhook-secret/	Regenerate a workflow hook secret

A hook runs a script or sends a webhook before or after a transition. See Workflow hooks.

Governed workspaces

In a workspace with workspace governance turned on, workflows and their transitions 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 transitions with Workspace workflow transitions. Manage their hooks with Workspace workflow hooks. See Workspace workflows for the catalog.

Response shaping

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