States overview

A state is a step in a project's workflow. Every work item sits in exactly one state, and a state belongs to exactly one project — states are never shared across projects.

Each state is assigned to a group, which is what Plane uses to reason about progress. Boards, charts, and cycle burndowns read the group, not the state name, so a project can rename In Progress to Building without breaking any reporting.

Learn more about states

The state object

Attributes

• id string (uuid)

  Unique identifier for the state.

• name string

  Display name, unique within the project. Maximum 255 characters.

• description string

  Free-form description of what the state means in this workflow.

• color string

  Hex color used wherever the state is rendered, for example #3f76ff.

• group string

  The workflow group this state belongs to. One of backlog, unstarted, started, completed, cancelled, or triage.

• sequence number

  Ordering weight within the project. Lower values sort first.

• is_default boolean

  Whether new work items land in this state when no state_id is supplied. Exactly one state per project is the default.

• is_triage boolean

  Whether this is the project's triage state, used by intake. Read-only — a triage state is created and managed by Plane.

• external_id , external_source string

  Correlation fields for sync and import. Together they let you map a state to a record in another system and find it again later.

• created_at string (date-time)

  When the state was created.

• created_by_id string (uuid)

  The user who created the state.

Group drives behavior, name does not

Filtering work items by state_group=started is stable across projects even when each project names its in-progress state differently. Filtering by state_id is exact but project-specific.

Response200

{
  "id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "name": "In Progress",
  "description": "Actively being worked on",
  "color": "#3f76ff",
  "group": "started",
  "sequence": 25000,
  "is_default": false,
  "is_triage": false,
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/states/	List states
POST	/api/v2/workspaces/{slug}/projects/{project_id}/states/	Create a state
GET	/api/v2/workspaces/{slug}/projects/{project_id}/states/{pk}/	Get a state
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/states/{pk}/	Update a state
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/states/{pk}/	Delete a state

Deleting states

Two deletes are rejected with 409 conflict:

• The project's default state cannot be deleted. Mark another state as default first.
• A state that still holds work items cannot be deleted. Move those work items to another state first.

Changed from v1

• default is now is_default.
• Reads no longer return updated_at, updated_by, project, or workspace.
• group accepts triage in addition to the five v1 groups.

See Migrating from v1 for the full list.