Skip to main content

​
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.
​
workspace_slug
string
required
Workspace identifier
​
project_id
uuid
required
Project UUID
Response
​
id
uuid
Label unique identifier
​
name
string
Label name
​
color
string
Hex color code (e.g., “#FF5733”)
​
description
string
Optional label description
​
parent
uuid
Parent label ID for hierarchical labels
​
sort_order
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.
​
name
string
required
Label name
​
color
string
Hex color code (default: random color)
​
description
string
Label description
​
parent
uuid
Parent label ID to create a child label
​
sort_order
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.
​
label_id
uuid
required
Label UUID
​
name
string
Updated label name
​
color
string
Updated hex color code
​
description
string
Updated description
​
parent
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

Build docs developers (and LLMs) love

Get started for freeTalk to us