States API

Manage workflow states for work items

Overview

States represent the workflow stages for work items in your project (e.g., Backlog, In Progress, Done). Each state belongs to a state group and can be customized with colors and ordering.

State groups

States are organized into predefined groups:

• Backlog - Work items not yet started
• Unstarted - Planned but not in progress
• Started - Active work items
• Completed - Finished work items
• Cancelled - Abandoned work items

The Triage group is reserved for intake issues and cannot be created via the API.

Endpoints

List states

GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/states/

Retrieve all states for a project.

workspace_slug · string · required

Workspace identifier

project_id · uuid · required

Project UUID

Response

id · uuid

State unique identifier

name · string

State name (e.g., “In Progress”)

color · string

Hex color code for UI display

group · string

State group: backlog, unstarted, started, completed, cancelled

sequence · number

Display order within the group

default · boolean

Whether this is the default state for new work items

Example

curl -X GET \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/states/" \
  -H "X-Api-Key: your-api-key"

Response

[
  {
    "id": "state-uuid-1",
    "name": "Backlog",
    "color": "#6B7280",
    "group": "backlog",
    "sequence": 1,
    "default": false
  },
  {
    "id": "state-uuid-2",
    "name": "Todo",
    "color": "#3B82F6",
    "group": "unstarted",
    "sequence": 1,
    "default": true
  }
]

Create state

POST /api/v1/workspaces/{workspace_slug}/projects/{project_id}/states/

Create a new state in the project.

name · string · required

State name

group · string · required

State group: backlog, unstarted, started, completed, cancelled

color · string

Hex color code (default: group-specific color)

sequence · number

Display order within the group

default · boolean

Set as default state for new work items (sets all other states to non-default)

Cannot create states in the “triage” group. Use the intake API for triage functionality.

Example

curl -X POST \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/states/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In Review",
    "group": "started",
    "color": "#F59E0B",
    "sequence": 2
  }'

Update state

PATCH /api/v1/workspaces/{workspace_slug}/projects/{project_id}/states/{state_id}/

Update an existing state.

state_id · uuid · required

State UUID

name · string

Updated state name

color · string

Updated hex color code

sequence · number

Updated display order

default · boolean

Set as default state (automatically unsets other defaults)

Example

curl -X PATCH \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/states/state-uuid/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review",
    "color": "#8B5CF6"
  }'

Delete state

DELETE /api/v1/workspaces/{workspace_slug}/projects/{project_id}/states/{state_id}/

Delete a state from the project.

Work items in this state will need to be moved to another state. Ensure you have at least one state per group.

Example

curl -X DELETE \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/states/state-uuid/" \
  -H "X-Api-Key: your-api-key"

Default states

Each project must have one default state. When you create a new work item without specifying a state, it will be assigned to the default state.

{
  "name": "Todo",
  "group": "unstarted",
  "default": true
}

Setting a state as default automatically sets default: false on all other states in the project.

State groups and workflow

States are organized into groups that represent different phases of your workflow:

Group	Purpose	Example States
backlog	Work not yet planned	Backlog, Someday
unstarted	Planned but not active	Todo, Ready
started	Active work	In Progress, In Review
completed	Finished work	Done, Shipped
cancelled	Abandoned work	Cancelled, Duplicate

Using states with work items

Set the state when creating or updating work items:

{
  "name": "Fix navigation bug",
  "state": "state-uuid-for-in-progress"
}

Best practices

Keep it simple - Start with 3-5 states per group. Add more as your workflow evolves.

Color coding - Use consistent colors for state groups (e.g., blue for unstarted, yellow for started, green for completed).

Clear names - Use action-oriented names that describe the work stage clearly.

Next steps

Work Items API

Manage work item states

Projects API

Configure project settings