Workspace workflow transitions overview

A workspace workflow transition is a move that a catalog workflow allows from one chain state to another. In the Plane app, transitions are the flows you add to a state.

The source state's type decides what kind of transition it is:

• From a transition state, the transition moves the work item straight to transition_state_id.
• From an approval state, the move waits for a decision from the approvers in member_ids. Approval moves the work item to transition_state_id, and rejection moves it to rejection_state_id. required_approvals sets how many approvals the move needs.

Change a state's type with Update a workspace workflow state. Approval settings need the Workflow approvals plan feature.

These endpoints work only in a workspace with governance turned on. In an ungoverned workspace, they return 409 states_managed_at_project. Project workflows there have their own workflow transitions.

Learn more about workflows and approvals

The workspace workflow transition object

Attributes

• id string (uuid)

  Unique identifier for the transition. Hooks are addressed under it.

• workflow_state_id string (uuid)

  The chain entry the transition starts from. This is the entry's id, not its catalog state id. Match it against id in List workspace workflow states to find the state_id.

• transition_state_id string (uuid)

  The catalog state the move goes to. Nullable.

• rejection_state_id string (uuid)

  For a transition out of an approval state, the catalog state a rejected work item moves to. Nullable.

• required_approvals integer

  How many approvals the move needs. null means every approver must approve. Nullable.

• member_ids array of string

  User ids of the approvers.

• created_at string (date-time)

  When the transition was created.

• updated_at string (date-time)

  When the transition was last updated.

Requests and responses name the source differently

Request bodies name every state by catalog state id: state_id for the source, transition_state_id and rejection_state_id for the targets. Responses keep the targets as catalog state ids but report the source as workflow_state_id, the chain entry's id.

Response200

{
  "id": "4b6e1d93-2a7f-4c58-9e30-1d8b5f7a2c46",
  "workflow_state_id": "c48f1a6d-2e7b-4d95-8c03-6b1e9f2a7d54",
  "transition_state_id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
  "rejection_state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "required_approvals": 1,
  "member_ids": ["a3f92c71-6e4b-4d08-9b5a-1c7e3d9f2b84"],
  "created_at": "2026-01-15T11:04:52.660219Z",
  "updated_at": "2026-01-15T11:04:52.660219Z"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/workflows/{workflow_id}/state-transitions/	List workspace workflow transitions
GET	/api/v2/workspaces/{slug}/workflows/{workflow_id}/state-transitions/{pk}/	Get a workspace workflow transition
POST	/api/v2/workspaces/{slug}/workflows/{workflow_id}/state-transitions/	Create a workspace workflow transition
PATCH	/api/v2/workspaces/{slug}/workflows/{workflow_id}/state-transitions/{pk}/	Update a workspace workflow transition
DELETE	/api/v2/workspaces/{slug}/workflows/{workflow_id}/state-transitions/{pk}/	Delete a workspace workflow transition

Validation

• The source, the target, and the rejection state must all be in the workflow's chain. A source outside the chain returns 404. A target or rejection state outside it returns 400.
• Approvers must be active members of the workspace, or the request returns 400.
• A workflow holds one transition per source and target pair. A second one returns 409 conflict.
• Changing a state's type deletes every transition that starts from it, with their approvers.

Response shaping

Every endpoint that returns the workspace workflow transition object accepts ?fields= for sparse responses. See Sparse fields. Errors follow the shared problem+json contract.

Changed from v1

• List workspace workflow transitions is paginated. v1 returns every transition as one array.
• In an ungoverned workspace, every route returns 409 states_managed_at_project. v1 returns 400.

See Migrating from v1 for the full list.