States API

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.

string

required

Workspace identifier

uuid

required

Project UUID

Response

uuid

State unique identifier

string

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

string

Hex color code for UI display

string

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

number

Display order within the group

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.

string

required

State name

string

required

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

string

Hex color code (default: group-specific color)

number

Display order within the group

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.

uuid

required

State UUID

string

Updated state name

string

Updated hex color code

number

Updated display order

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.

Overview

Endpoints

Overview

State groups

Endpoints

List states

Create state

Update state

Delete state

Default states

State groups and workflow

Using states with work items

Best practices

Next steps

Work Items API

Projects API

​Overview

​State groups

​Endpoints

​List states

​Create state

​Update state

​Delete state

​Default states

​State groups and workflow

​Using states with work items

​Best practices

​Next steps

Work Items API

Projects API

Overview

State groups

Endpoints

List states

Create state

Update state

Delete state

Default states

State groups and workflow

Using states with work items

Best practices

Next steps