Labels

Labels are tags you can attach to any number of tasks. These endpoints act on your own labels only: an id belonging to anyone else returns 404 Not Found.

List labels

Returns all your labels with how many tasks use them.

GET /api/labels

No query parameters are needed.

Response

A bare JSON array of labels:

[
  {
    "id": "d2a6f8c4-9b31-4e57-8c02-7a4d1e6b3f89",
    "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
    "name": "writing",
    "color": "#F59E0B",
    "createdAt": "2026-09-28T22:50:00.000Z",
    "updatedAt": "2026-09-28T22:50:00.000Z",
    "_count": { "tasks": 3 }
  }
]

Labels come back in name order. _count.tasks counts the tasks carrying the label.

Status codes

Code	When
200 OK	the list returned
401 Unauthorized	no valid session or API key

Create a label

Creates one label.

POST /api/labels

Send these fields in the JSON body:

Body parameters

Name	Type	Required	Description
name	string	Yes	Label name, 1–100 characters
color	string	No	#RRGGBB hex colour such as #F59E0B, or null for no colour

Names must be unique for each user, so creating a second label with the same name fails with 409 Conflict.

Response

The new label comes back with 201 Created:

{
  "id": "d2a6f8c4-9b31-4e57-8c02-7a4d1e6b3f89",
  "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
  "name": "writing",
  "color": "#F59E0B",
  "createdAt": "2026-09-28T22:50:00.000Z",
  "updatedAt": "2026-09-28T22:50:00.000Z"
}

Attach the label to tasks by sending its id in a task’s labelIds, as on the Tasks page.

Status codes

Code	When
201 Created	the label was created
400 Bad Request	the body failed validation (Validation failed), most often a color that isn’t #RRGGBB
401 Unauthorized	no valid session or API key

Update a label

Changes the name or colour of one label. Omit the field you want to keep.

PATCH /api/labels/{id}

Send only the fields to change in the JSON body:

Body parameters

Name	Type	Required	Description
name	string	No	Label name, 1–100 characters
color	string	No	#RRGGBB hex colour such as #F59E0B, or null to clear it

Renaming keeps every task attachment; only the label’s own name and colour change.

Response

The updated label comes back as one JSON object:

{
  "id": "d2a6f8c4-9b31-4e57-8c02-7a4d1e6b3f89",
  "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
  "name": "client-writing",
  "color": "#EF4444",
  "createdAt": "2026-09-28T22:50:00.000Z",
  "updatedAt": "2026-09-30T03:20:11.000Z"
}

Only the fields you send change; the rest keep their old values.

Status codes

Code	When
200 OK	the label was updated
400 Bad Request	the body failed validation (Validation failed), most often a color that isn’t #RRGGBB
401 Unauthorized	no valid session or API key
404 Not Found	no label with that id belongs to you (Label not found)

Delete a label

Deletes one label and detaches it from every task.

DELETE /api/labels/{id}

No body is needed.

Response

The endpoint confirms the change:

{
  "success": true
}

The label row is gone for good. Tasks that carried it keep existing and simply lose the tag.

Status codes

Code	When
200 OK	the label was deleted
401 Unauthorized	no valid session or API key
404 Not Found	no label with that id belongs to you (Label not found)

See also

• REST API: authentication, errors and pagination
• Labels: using labels in the app
• Tasks: attach labels with labelIds