Project states overview

A project state is a lifecycle stage that a project sits in, such as Planning, Execution, or Monitoring. It is not a work item state. Work items move through states, which you can also read and manage at the workspace level through workspace states.

Project states form one catalog per workspace. A project points at its project state through state_id on the project object. Every workspace starts with six project states, one per group, with Draft as the default. A project created without a state_id starts in the default project state.

Learn more about project states

Requirements

Every project state endpoint checks both of these. If either one is off, the endpoint returns the same error.

Requirement	Failure
Project states included in the workspace's plan	402 payment_required
Project states turned on in the workspace's settings	402 payment_required

Workspace owners, admins, and members can read and write project states. Guests can read them.

The project state object

Attributes

• id string (uuid)

  Unique identifier for the project state. This is the value you send as a project's state_id.

• name string

  Display name, unique in the workspace. Maximum 50 characters.

• description string

  Free-form description of what the stage means.

• color string

  Hex color used wherever the project state is rendered, for example #F59E0B.

• group string

  The lifecycle group. One of draft, planning, execution, monitoring, completed, or cancelled. These are not the work item state groups.

• sequence number

  Ordering weight. Lower values sort first.

• is_default boolean

  Whether this is the workspace's default project state. Exactly one project state is the default. Change it with Mark a project state as default.

• external_id, external_source string or null

  Correlation fields for sync and import.

• created_at string (date-time)

  When the project state was created.

• updated_at string (date-time)

  When the project state was last updated.

• created_by_id string (uuid) or null

  The user who created the project state.

• updated_by_id string (uuid) or null

  The user who last updated the project state.

Response200

{
  "id": "e2b95c07-8a3f-4d61-b7e4-0c6a1f9d3e28",
  "name": "Execution",
  "description": "",
  "color": "#F59E0B",
  "group": "execution",
  "sequence": 35000,
  "is_default": false,
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/project-states/	List project states
GET	/api/v2/workspaces/{slug}/project-states/{pk}/	Get a project state
POST	/api/v2/workspaces/{slug}/project-states/	Create a project state
PATCH	/api/v2/workspaces/{slug}/project-states/{pk}/	Update a project state
DELETE	/api/v2/workspaces/{slug}/project-states/{pk}/	Delete a project state
POST	/api/v2/workspaces/{slug}/project-states/{pk}/mark-default/	Mark a project state as default

Project states don't depend on workspace governance. The routes behave the same in a governed and an ungoverned workspace.

Response shaping

Every project state read accepts ?fields= for sparse responses. See Sparse fields. Errors follow the shared problem+json contract.

Changed from v1

• When project states are turned off in the workspace's settings, v2 returns 402 payment_required. v1 returned a 400.
• v1's POST …/project-states/{pk}/default/ is POST …/project-states/{pk}/mark-default/.
• Reads return is_default instead of default, and no longer return workspace_id.

See Migrating from v1 for the full list.