Plane DocsSign in

Workspace workflow states overview ​

A workspace workflow state is one entry in a catalog workflow's chain. It puts a catalog state in the workflow and holds the state's settings there. The same catalog state can be in many workflows, each with its own position, default flag, type, and creation setting. The state's name, color, and group belong to the catalog state itself, which you manage with workspace states.

Every route addresses a chain entry by its catalog state id, state_id, not by the entry's own id. That is the id you already hold from a workflow's states array, from a work item's state_id, or from the workspace states list.

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 states.

Learn more about workflows and approvals

The workspace workflow state object ​

Attributes ​

  • id string (uuid)

    Unique identifier of the chain entry. Transitions refer to it as workflow_state_id. Routes don't use it.

  • state_id string (uuid)

    The catalog state this entry puts in the chain. Every route addresses the entry by this id.

  • workflow_id string (uuid)

    The catalog workflow the entry belongs to.

  • type string

    How work items leave the state. With transition, work items move along the state's transitions directly. With approval, a move out needs a decision from the transition's approvers. Approval moves the work item to the transition's target, and rejection moves it to the transition's rejection state.

  • is_default boolean

    Whether new work items land in this state when no state is given. A workflow has at most one default.

  • allow_issue_creation boolean

    Whether new work items can be created directly in this state. Marking a state as default sets it to true.

  • sequence number

    Position weight in the chain. Lower values sort first.

  • updated_at string (date-time)

    When the entry was last updated.

Response200
json
{
  "id": "c48f1a6d-2e7b-4d95-8c03-6b1e9f2a7d54",
  "state_id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "workflow_id": "9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88",
  "type": "approval",
  "is_default": false,
  "allow_issue_creation": false,
  "sequence": 30000.0,
  "updated_at": "2026-01-14T09:31:07.215904Z"
}

Endpoints ​

MethodPathDescription
GET/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/List workspace workflow states
GET/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/{state_id}/Get a workspace workflow state
POST/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/Add states to a workspace workflow
PATCH/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/{state_id}/Update a workspace workflow state
DELETE/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/{state_id}/Remove a state from a workspace workflow
POST/api/v2/workspaces/{slug}/workflows/{workflow_id}/states/{state_id}/mark-default/Mark a workspace workflow state as default

Order and default ​

sequence changes only when you replace the chain with a states body on Update a workspace workflow. States attached with Add states to a workspace workflow get sequence 65535.

The default moves with Mark a workspace workflow state as default, with default_state_id in a chain replacement, or with new_default_state_id when you remove the default state.

Removing a state ​

Remove a state from a workspace workflow checks four things before it removes anything: the chain keeps at least one state, a removed default has a replacement, work items in the state have a target in state_mapping (409 workflow_state_orphans), and no transition references the state (409 workflow_state_dependencies).

Response shaping ​

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

Changed from v1 ​

See Migrating from v1 for the full list.