Labels API - Plane

Overview

Labels help you categorize and organize work items across your projects. You can create hierarchical labels with custom colors and use them to filter and group issues.

Endpoints

List labels

GET /api/v1/workspaces/{workspace_slug}/projects/{project_id}/labels/

Retrieve all labels for a project.

string

required

Workspace identifier

uuid

required

Project UUID

Response

uuid

Label unique identifier

string

Label name

string

Hex color code (e.g., “#FF5733”)

string

Optional label description

uuid

Parent label ID for hierarchical labels

number

Display order

Example

curl -X GET \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/labels/" \
  -H "X-Api-Key: your-api-key"

Create label

POST /api/v1/workspaces/{workspace_slug}/projects/{project_id}/labels/

Create a new label in the project.

string

required

Label name

string

Hex color code (default: random color)

string

Label description

uuid

Parent label ID to create a child label

number

Display order (default: 65535)

Example

curl -X POST \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/labels/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bug",
    "color": "#FF0000",
    "description": "Something is broken"
  }'

Update label

PATCH /api/v1/workspaces/{workspace_slug}/projects/{project_id}/labels/{label_id}/

Update an existing label.

uuid

required

Label UUID

string

Updated label name

string

Updated hex color code

string

Updated description

uuid

Updated parent label ID

Example

curl -X PATCH \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/labels/label-uuid/" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#00FF00"
  }'

Delete label

DELETE /api/v1/workspaces/{workspace_slug}/projects/{project_id}/labels/{label_id}/

Delete a label from the project.

Deleting a label removes it from all associated work items. This action cannot be undone.

Example

curl -X DELETE \
  "https://api.plane.so/api/v1/workspaces/acme/projects/abc-123/labels/label-uuid/" \
  -H "X-Api-Key: your-api-key"

Label hierarchies

Labels support parent-child relationships, allowing you to create hierarchical categorization:

{
  "name": "Frontend",
  "color": "#3B82F6",
  "parent": null
}

// Child label
{
  "name": "React",
  "color": "#61DAFB", 
  "parent": "uuid-of-frontend-label"
}

Using labels with work items

Labels can be added to work items via the Work Items API:

{
  "name": "Fix navigation bug",
  "labels": ["label-uuid-1", "label-uuid-2"]
}

Best practices

Color coding - Use consistent color schemes across related labels for better visual organization

Hierarchies - Group related labels under parent labels (e.g., Platform → Web, Mobile, API)

Naming - Use clear, concise label names that describe the category

Next steps

Work Items API

Apply labels to work items

Projects API

Manage project settings

​Overview

​Endpoints

​List labels

​Create label

​Update label

​Delete label

​Label hierarchies

​Using labels with work items

​Best practices

​Next steps

Work Items API

Projects API

Overview

Endpoints

List labels

Create label

Update label

Delete label

Label hierarchies

Using labels with work items

Best practices

Next steps