# Label

A label: a per-project tag work items are marked with, carrying the colour and the optional icon the backlog chips and the work item detail view show beside its name. Labels belong to one project and are attached to work items from the work-item side.

## Used by
- GET /api/v2/labels: List labels (LabelList)
- POST /api/v2/labels: Create a label (Label)
- GET /api/v2/labels/{label}: Read a label (Label)
- PATCH /api/v2/labels/{label}: Update a label (Label)

## Label fields
- id (integer, required): Unique identifier.
- project_id (integer, required): The project this label belongs to. Follow `GET /api/v2/projects/{project}` for its details; the project is not expandable from here.
- name (string ≤ 255, required): Label name as shown on the chip, e.g. `Blocked`.
- color (string ≤ 255, required): Six-digit hex colour, e.g. `#ef4444`. Stored verbatim: a row written before the colour picker enforced the format reads back as it is stored.
- icon (string or null ≤ 255, required): Icon name, e.g. `heroicon-o-tag`: not a URL and not markup. Null when the label has no icon.
- order (integer, required, server-assigned): Display position within the project. Assigned on create as the next position in that project's label order, changed only by dragging in plnnrly, and not writable.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- links (LabelLinks, required)
  - self (url, required): The canonical URI of this record.

## Variants

### LabelList

What a collection returns, and what `?view=summary` returns on a single record.

9 fields.
Identical to the detail object above.

### LabelSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

3 fields.
Omits: project_id, icon, order, created_at, updated_at, links

### LabelLinks

The `links` object on this resource.

Keys: self

## Example
```json
{
  "id": 1,
  "project_id": 1,
  "name": "Blocked",
  "color": "#ef4444",
  "icon": "heroicon-o-tag",
  "order": 1,
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1"
  }
}
```