Project labels overview

A project label tags a project, not a work item. Project labels form one catalog per workspace. Use them to group projects by team, product line, or any other scheme. A project can carry several labels. To tag work items, use labels, which belong to a project.

The v2 API manages the catalog: list, read, create, rename, recolor, reorder, and delete. It has no endpoint or project field that attaches a label to a project.

Project labels aren't tied to a plan feature, and they don't depend on workspace governance. Anyone in the workspace, guests included, can read them. Only workspace owners and admins can create, update, or delete them.

Learn more about project labels

The project label object

Attributes

• id string (uuid)

  Unique identifier for the project label.

• name string

  Display name. Unique in the workspace, compared case-insensitively, so Roadmap and roadmap can't both exist. Maximum 255 characters.

• description string

  Free-form note about what the label is for.

• color string

  Hex color used wherever the label is rendered, for example #e5484d. Can be empty.

• sort_order number

  Ordering weight. Lower values sort first. Plane gives each new label the next slot, so the default list order is creation order until you reorder.

• created_at string (date-time)

  When the label was created.

• updated_at string (date-time)

  When the label was last updated.

• created_by_id string (uuid) or null

  The user who created the label.

• updated_by_id string (uuid) or null

  The user who last updated the label.

Response200

{
  "id": "d8a4f2c6-1e7b-4093-9c5a-6b2e0f8d3a71",
  "name": "Roadmap",
  "description": "Projects committed on this year's roadmap",
  "color": "#3e63dd",
  "sort_order": 65535,
  "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-labels/	List project labels
GET	/api/v2/workspaces/{slug}/project-labels/{pk}/	Get a project label
POST	/api/v2/workspaces/{slug}/project-labels/	Create a project label
PATCH	/api/v2/workspaces/{slug}/project-labels/{pk}/	Update a project label
DELETE	/api/v2/workspaces/{slug}/project-labels/{pk}/	Delete a project label

Name conflicts

A name already in use returns 409 conflict, regardless of letter case. The problem body carries the id of the label that holds the name, so an importer can map to the existing label instead of failing:

{
  "type": "conflict",
  "code": "conflict",
  "detail": "A project label with this name already exists in this workspace.",
  "id": "d8a4f2c6-1e7b-4093-9c5a-6b2e0f8d3a71"
}

Response shaping

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

Changed from v1

• A duplicate name always returns 409 conflict with the clashing label's id. v1 returned a 400 or a 409 depending on where the clash was caught.
• Reads return created_by_id and updated_by_id instead of created_by and updated_by, and no longer return workspace.
• The OAuth scopes are workspaces.project_labels:read and workspaces.project_labels:write, separate from the work item label scopes.

See Migrating from v1 for the full list.