Labels API

Labels are project-scoped tags applied to issues. Each label has a name (unique within its project), a color, and an order used to sort the list. Labels surface on each issue as a label_ids array — fetch the labels list once per project and join client-side.

Permissions

Action	Required Permission	Scope
List / view	Labels: Read	In accessible projects
Create	Labels: Create	In accessible projects
Update	Labels: Update (All)	In accessible projects
Delete	Labels: Delete (All)	In accessible projects
Assign labels to an issue	Issues: Update (Own/All)	In accessible projects

Admins and project owners bypass all permission checks for project-scoped resources. By default, the system Member role has read-only access to labels — label CRUD is an admin-curated workflow.

Endpoints

Method	Endpoint	Description
GET	/api/projects/{projectId}/labels	List labels (ordered by order ascending)
POST	/api/projects/{projectId}/labels	Create a label
PUT	/api/projects/{projectId}/labels/{labelId}	Update a label
PATCH	/api/projects/{projectId}/labels/{labelId}	Update a label partially
DELETE	/api/projects/{projectId}/labels/{labelId}	Delete a label
PUT	/api/projects/{projectId}/issues/{issueId}/labels	Replace the set of labels assigned to an issue

List Labels

GET /api/projects/{projectId}/labels

Returns every label in the project ordered by order ascending. Eight default labels (Bug, Enhancement, Feature, Question, Documentation, Won't fix, Duplicate, Blocked) are seeded on project creation.

Request

curl https://{tenant}.kendo.dev/api/projects/1/labels \
  -H "Authorization: Bearer your-token"

Response 200

[
  {
    "id": 1,
    "name": "Bug",
    "color": 3,
    "project_id": 1,
    "order": 1,
    "created_at": "2026-05-26T10:00:00+00:00",
    "updated_at": "2026-05-26T10:00:00+00:00"
  },
  {
    "id": 2,
    "name": "Enhancement",
    "color": 1,
    "project_id": 1,
    "order": 2,
    "created_at": "2026-05-26T10:00:00+00:00",
    "updated_at": "2026-05-26T10:00:00+00:00"
  }
]

Create Label

POST /api/projects/{projectId}/labels

Request Fields

Field	Type	Required	Description
name	string	Yes	Label name, max 255 characters, unique within the project
color	integer	Yes	See Color enum below
order	integer	Yes	Position in the label list, min 0

Request

curl -X POST https://{tenant}.kendo.dev/api/projects/1/labels \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "good first issue",
    "color": 1,
    "order": 9
  }'

Response 201

{
  "id": 9,
  "name": "good first issue",
  "color": 1,
  "project_id": 1,
  "order": 9,
  "created_at": "2026-05-27T14:00:00+00:00",
  "updated_at": "2026-05-27T14:00:00+00:00"
}

Error Responses

Status	Cause
403	The caller lacks Labels: Create permission on the project
422	A label with the same name already exists in this project, color is not a valid enum value, or a required field is missing

Update Label

PUT /api/projects/{projectId}/labels/{labelId}

Partial update: send PATCH instead of PUT to change a subset of fields — name alone keeps the current color, color alone keeps the current name. Every other validation rule is unchanged. A PATCH that sends none of the writable fields is rejected with 422.

Updates the label's name and color. The order and project_id fields are not editable via this endpoint — labels can be renamed and recolored, but they don't change project, and ordering is not currently exposed for updates.

Request Fields

Field	Type	Required	Description
name	string	Yes	Label name, max 255 characters, unique within the project (renaming to the current value is allowed)
color	integer	Yes	See Color enum below

Request

curl -X PUT https://{tenant}.kendo.dev/api/projects/1/labels/9 \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "good first issue",
    "color": 2
  }'

Response 200

{
  "id": 9,
  "name": "good first issue",
  "color": 2,
  "project_id": 1,
  "order": 9,
  "created_at": "2026-05-27T14:00:00+00:00",
  "updated_at": "2026-05-27T14:05:00+00:00"
}

Error Responses

Status	Cause
403	The caller lacks Labels: Update permission on the project
404	The label belongs to a different project (route binding scopes the label to {projectId})
422	The new name collides with a different label in the same project, or color is not a valid enum value

Delete Label

DELETE /api/projects/{projectId}/labels/{labelId}

Returns 204 No Content. The label row is removed and the issue_label pivot is silently detached from every issue that carried this label — issues are unaffected otherwise.

curl -X DELETE https://{tenant}.kendo.dev/api/projects/1/labels/9 \
  -H "Authorization: Bearer your-token"

Error Responses

Status	Cause
403	The caller lacks Labels: Delete permission on the project
404	The label belongs to a different project

Assign Labels to an Issue

PUT /api/projects/{projectId}/issues/{issueId}/labels

Replaces the full set of labels assigned to an issue. The request body is a label_ids array — every label currently attached that's not in the new set is detached, every ID in the new set that isn't currently attached is attached. Pass an empty array to detach every label from the issue.

Authorization gates on Issues: Update, not Labels: Update — the row state being mutated is the issue's M2M membership, not the label itself.

Request Fields

Field	Type	Required	Description
label_ids	integer[]	Yes (key must be present)	Set of label IDs to assign. Empty array detaches every label. IDs must be unique and must reference labels in the same project.

Request

curl -X PUT https://{tenant}.kendo.dev/api/projects/1/issues/42/labels \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"label_ids": [1, 3, 5]}'

Response 204

HTTP/1.1 204 No Content

To verify the new set, fetch the issue and read label_ids:

curl https://{tenant}.kendo.dev/api/projects/1/issues/42 \
  -H "Authorization: Bearer your-token"

Error Responses

Status	Cause
403	The caller lacks Issues: Update permission on the project
422	The label_ids key is missing from the body, the array contains a duplicate ID, or any ID references a label outside this project

Enums

Color

Value	Label
0	Grey
1	Green
2	Blue
3	Red
4	Purple
5	Yellow
6	Orange
7	Teal

See Also

• Issues API — Each issue exposes label_ids: number[] populated from the issue_label pivot
• Projects API — Project that owns the labels