Create a state

POST/api/v2/workspaces/{slug}/projects/{project_id}/states/

Add a workflow state to a project. The new state is appended to the project's workflow and becomes immediately selectable on work items.

State names must be unique within a project — reusing one returns 409 conflict.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs — in https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring (uuid)

The project to add the state to.

Body Parameters

name:requiredstring

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

color:requiredstring

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

group:optionalstring

The workflow group the state belongs to. Determines how the state is treated by boards, charts, and cycle progress.

• backlog — Not yet scheduled
• unstarted — Scheduled but not begun
• started — Actively in progress
• completed — Finished successfully
• cancelled — Closed without completion
• triage — Awaiting intake review

Defaults to backlog when omitted.

description:optionalstring

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

sequence:optionalnumber

Ordering weight within the project. Lower values sort first. Assigned automatically when omitted.

is_default:optionalboolean

Make this the project's default state — where work items land when no state_id is supplied. Setting it clears the flag on the previous default.

external_id:optionalstring

Your system's identifier for this state, for sync and import correlation. Maximum 255 characters.

external_source:optionalstring

The system external_id came from, for example github or jira. Maximum 255 characters.

Scopes

projects.states:write

Errors

Status	Code	Cause
400	validation_error	Missing name/color, or a group outside the enum.
403	forbidden	Your role or token scope can't create states.
404	resource_not_found	No such workspace or project, or it's outside your tenant.
409	conflict	A state with this name already exists in the project.

Create a state

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/states/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "In Review",
  "color": "#3f76ff",
  "group": "started",
  "description": "Awaiting code review"
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/states/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "In Review",
        "color": "#3f76ff",
        "group": "started",
        "description": "Awaiting code review",
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/states/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "In Review",
      color: "#3f76ff",
      group: "started",
      description: "Awaiting code review",
    }),
  }
);
const data = await response.json();

Response201

{
  "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "name": "In Review",
  "description": "Awaiting code review",
  "color": "#3f76ff",
  "group": "started",
  "sequence": 45000,
  "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"
}

Response409

{
  "type": "https://api.plane.so/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "A state with this name already exists in this project."
}