Labels API

Create, manage, and assign labels to issues. Labels support categories for structured grouping.

List Labels

GET /api/v1/labels

Parameter	Type	Description
`category`	string	Filter by category. Use `_uncategorized` for labels without a category.

{
  "items": [
    {
      "id": 1,
      "name": "frontend",
      "color": "#4ade80",
      "category": "area",
      "sortOrder": 0
    }
  ]
}

GET /api/v1/labels/categories

Returns a list of distinct category names in use.

POST /api/v1/labels

{
  "name": "needs-review",
  "color": "#facc15",
  "category": "state",
  "sortOrder": 1
}

Field	Required	Description
`name`	Yes	Label name (1-50 chars, unique within category)
`color`	Yes	Hex color (e.g., `#ff4444`)
`category`	No	Category name (1-50 chars, alphanumeric + hyphens)
`sortOrder`	No	Display order within category (default: 0)

PATCH /api/v1/labels/{id}

Partial update — send only the fields to change.

DELETE /api/v1/labels/{id}

GET /api/v1/labels/issue/{issueId}

Returns labels attached to a specific issue, grouped by category.

POST /api/v1/labels/issue/{issueId}/{labelId}

Attaches a label to an issue.

DELETE /api/v1/labels/issue/{issueId}/{labelId}

Removes a label from an issue.

Action	Scope
List/view labels	`labels:read`
Create/update/delete labels	`labels:write`
Attach/detach labels to issues	`labels:write`