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. Update and delete look the transition up first, so an unknown id in their path returns 404 instead. 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

Access

Operation	Who can call it	Scope
List and get transitions	Workspace owners, admins, and members. Guests get 403 forbidden.	workspaces.workflows:read
Create, update, and delete	Workspace owners and admins.	workspaces.workflows:write

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.
• Create refuses a second transition for the same source and target pair with 409 conflict. Update doesn't check, so changing transition_state_id to a target the source already has leaves two transitions for the pair.
• 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, the routes return 409 states_managed_at_project. v1 returns 400. Update and delete return 404 first for an unknown id.

See Migrating from v1 for the full list.