Labels API

Manage labels for organizing and categorizing tickets.

Endpoints

Method	Endpoint	Description
GET	/labels	List labels
POST	/labels	Create label
GET	/labels/:id	Get label
PATCH	/labels/:id	Update label
DELETE	/labels/:id	Delete label

List Labels

GET /api/v1/labels

Response

{
  "data": [
    {
      "id": "label-uuid-1",
      "name": "Billing",
      "color": "#EF4444",
      "description": "Billing and payment issues",
      "ticket_count": 42,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "label-uuid-2",
      "name": "Technical",
      "color": "#3B82F6",
      "description": "Technical support issues",
      "ticket_count": 156,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Label

POST /api/v1/labels

Request Body

{
  "name": "VIP",
  "color": "#8B5CF6",
  "description": "High-priority VIP customers"
}

Field	Type	Required	Description
name	string	Yes	Label name (unique)
color	string	Yes	Hex color code
description	string	No	Label description

Colors

Use hex color codes:

Color	Hex
Red	#EF4444
Orange	#F97316
Yellow	#EAB308
Green	#22C55E
Blue	#3B82F6
Purple	#8B5CF6
Gray	#6B7280

Response

{
  "data": {
    "id": "label-uuid",
    "name": "VIP",
    "color": "#8B5CF6",
    "description": "High-priority VIP customers",
    "ticket_count": 0,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Label

GET /api/v1/labels/:id

Returns label with usage statistics.

Update Label

PATCH /api/v1/labels/:id

{
  "name": "VIP Customer",
  "color": "#A855F7"
}

Changes apply to all tickets with this label.

Delete Label

DELETE /api/v1/labels/:id

Response

204 No Content

Removes the label from all tickets. Tickets themselves are not affected.

Applying Labels to Tickets

Add Labels

POST /api/v1/tickets/:ticket_id/labels

{
  "label_ids": ["label-uuid-1", "label-uuid-2"]
}

Adds labels to the ticket (existing labels are kept).

Remove Labels

DELETE /api/v1/tickets/:ticket_id/labels

{
  "label_ids": ["label-uuid-1"]
}

Removes specified labels from the ticket.

Set Labels

When updating a ticket, setting label_ids replaces all labels:

PATCH /api/v1/tickets/:id

{
  "label_ids": ["label-uuid-1", "label-uuid-3"]
}

Filtering Tickets by Label

GET /api/v1/tickets?label_ids=label-uuid-1,label-uuid-2

Returns tickets that have any of the specified labels.

Error Codes

Code	Description
LABEL_NOT_FOUND	Label doesn’t exist
LABEL_NAME_EXISTS	Label name already used
INVALID_COLOR	Color must be valid hex code