Skip to Content
API ReferenceLabels

Labels API

Labels organize tasks with a workspace-managed name and color. Create labels once, then attach their names when creating or updating tasks.

Task writes reject unknown label names by default. To create a label as part of a task write instead, send "createMissing": true with labels — see creating labels on the fly. Labels born that way get color gray; everything else on this page applies to them unchanged.

Label Object

{
  "id": "label_abc123",
  "name": "Release",
  "color": "blue",
  "createdAt": "2025-01-10T12:00:00.000Z",
  "updatedAt": "2025-01-10T12:00:00.000Z"
}

Field Reference

FieldTypeDescription
idstringUnique identifier
namestringLabel name, 1–40 characters after trimming; unique within a workspace without regard to case
colorstringOne of: gray, blue, teal, green, yellow, orange, red, pink, purple, brown
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-updated timestamp

List Labels

GET /api/v1/labels

Returns labels in the current workspace, sorted by name.

Response

{
  "data": [
    {
      "id": "label_abc123",
      "name": "Release",
      "color": "blue",
      "createdAt": "2025-01-10T12:00:00.000Z",
      "updatedAt": "2025-01-10T12:00:00.000Z"
    }
  ]
}

Create Label

POST /api/v1/labels

Request Body

FieldTypeRequiredDescription
namestringYes1–40 characters after trimming; unique within the workspace without regard to case
colorstringYesOne of the supported label colors

Example

curl -X POST https://api.cohort.bot/api/v1/labels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release",
    "color": "blue"
  }'

Returns the created label with a 201 status.

Name Conflict

Label names are case-insensitively unique within a workspace. Creating release when Release already exists returns 409 with the LABEL_NAME_EXISTS conflict error.

Update Label

PATCH /api/v1/labels/:id

Updates the supplied fields and returns the updated label.

Request Body

FieldTypeDescription
namestringReplacement name; 1–40 characters after trimming and case-insensitively unique within the workspace
colorstringReplacement color from the supported label colors

Example

curl -X PATCH https://api.cohort.bot/api/v1/labels/label_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Urgent",
    "color": "red"
  }'

As with creation, a duplicate name returns 409 with the LABEL_NAME_EXISTS conflict error.

Delete Label

DELETE /api/v1/labels/:id

Permanently deletes the label and removes it from every task in the workspace. The response is 204 with no body.

Example

curl -X DELETE https://api.cohort.bot/api/v1/labels/label_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
TasksProjects