Workflow transitions overview

Workflow transitions define the legal 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.

• member_ids array of string

  Ids of the associated members.

• rejection_state_id string (uuid)

  The related rejection state.

• required_approvals integer

  How many approvals a transition needs before it may run.

• transition_state_id string (uuid)

  The related transition state.

• workflow_state_id string (uuid)

  The related workflow state.

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.