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 startedUnstarted - Planned but not in progressStarted - Active work itemsCompleted - Finished work itemsCancelled - 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.
Response State name (e.g., “In Progress”)
Hex color code for UI display
State group: backlog, unstarted, started, completed, cancelled
Display order within the group
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.
State group: backlog, unstarted, started, completed, cancelled
Hex color code (default: group-specific color)
Display order within the group
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.
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
