Tags

Tags help you categorize and organize tickets. You can use tags to filter tickets, set up automatic routing to teams, and track common issue types. On this page, we will look at how to create, retrieve, update, and delete tags.

The tag model

The tag model contains all the information about a ticket tag, including its name, color, icon, and optional team routing configuration.

Properties

Name
id
Type
string
Description
Unique identifier for the tag (UUID).
Name
name
Type
string
Description
The tag name (max 100 characters).
Name
color
Type
string
Description
Display color for the tag badge. Common values: zinc, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.
Name
icon
Type
string
Description
Optional Heroicon name for the tag (e.g., BugAntIcon, SparklesIcon).
Name
description
Type
string
Description
Optional description of what this tag represents.
Name
route_to_team
Type
object
Description
Team to automatically route tickets to when this tag is applied (nullable).
Name
ticket_count
Type
integer
Description
Number of tickets currently using this tag.
Name
created_at
Type
timestamp
Description
Timestamp of when the tag was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the tag was last updated.

GET/api/v1/tags

List all tags

Returns a list of all tags in your organization.

Required scope: tags:read

Query parameters

Name
search
Type
string
Description
Filter tags by name (case-insensitive partial match).

Request

GET

/api/v1/tags

curl https://api.supportstation.io/api/v1/tags \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "tag-uuid",
      "name": "Bug",
      "color": "red",
      "icon": "BugAntIcon",
      "description": "Something is broken or not working as expected",
      "route_to_team": {
        "id": "team-uuid",
        "name": "Engineering"
      },
      "ticket_count": 42,
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z"
    },
    {
      "id": "tag-uuid-2",
      "name": "Feature Request",
      "color": "purple",
      "icon": "SparklesIcon",
      "description": "Request for new functionality",
      "route_to_team": null,
      "ticket_count": 28,
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

GET/api/v1/tags/:id

Retrieve a tag

Returns a single tag by ID.

Required scope: tags:read

Request

GET

/api/v1/tags/:id

curl https://api.supportstation.io/api/v1/tags/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bug",
    "color": "red",
    "icon": "BugAntIcon",
    "description": "Something is broken or not working as expected",
    "route_to_team": {
      "id": "team-uuid",
      "name": "Engineering"
    },
    "ticket_count": 42,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

POST/api/v1/tags

Create a tag

Creates a new tag for your organization.

Required scope: tags:write

Required attributes

Name
name
Type
string
Description
The tag name (max 100 characters). Must be unique within your organization.

Optional attributes

Name
color
Type
string
Description
Display color for the tag badge (default: zinc).
Name
icon
Type
string
Description
Heroicon name for the tag (e.g., BugAntIcon).
Name
description
Type
string
Description
Description of what this tag represents (max 500 characters).
Name
route_to_team_id
Type
string
Description
Team UUID to automatically route tickets to when this tag is applied.

Request

POST

/api/v1/tags

curl -X POST https://api.supportstation.io/api/v1/tags \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Urgent",
    "color": "red",
    "icon": "ExclamationTriangleIcon",
    "description": "High priority issues requiring immediate attention"
  }'

Response

{
  "data": {
    "id": "new-tag-uuid",
    "name": "Urgent",
    "color": "red",
    "icon": "ExclamationTriangleIcon",
    "description": "High priority issues requiring immediate attention",
    "route_to_team": null,
    "ticket_count": 0,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

PATCH/api/v1/tags/:id

Update a tag

Updates an existing tag.

Required scope: tags:write

Optional attributes

Name
name
Type
string
Description
New tag name (max 100 characters).
Name
color
Type
string
Description
New display color.
Name
icon
Type
string
Description
New Heroicon name.
Name
description
Type
string
Description
New description (max 500 characters), or null to clear.
Name
route_to_team_id
Type
string | null
Description
Team UUID for automatic routing, or null to disable routing.

Request

PATCH

/api/v1/tags/:id

curl -X PATCH https://api.supportstation.io/api/v1/tags/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "orange",
    "route_to_team_id": "team-uuid"
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bug",
    "color": "orange",
    "icon": "BugAntIcon",
    "description": "Something is broken or not working as expected",
    "route_to_team": {
      "id": "team-uuid",
      "name": "Engineering"
    },
    "ticket_count": 42,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
  }
}

DELETE/api/v1/tags/:id

Delete a tag

Deletes a tag. This will remove the tag from all tickets that have it applied.

Required scope: tags:write

Request

DELETE

/api/v1/tags/:id

curl -X DELETE https://api.supportstation.io/api/v1/tags/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "deleted": true
  }
}