Tags

Tags on tickets, customers and articles. List them with usage counts, merge one into another, or remove one everywhere. There is no create call: add a tag by updating a record’s tags.

The Tag object

tag string

Tag name

entity string

Where the tag is used: tickets, customers or articles

count integer

Number of records of that entity with the tag

Endpoints

GET List Tags POST Merge Tags DELETE Remove Tag

GET /api/v1/teams/{teamId}/tags

List Tags

List tags with usage counts, one row per tag and entity type, most used first. Without entity, the key needs view permission on all three.

Query Parameters

entity string

Only tickets, customers or articles

search string

Case-insensitive name filter

Code Examples

bash

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/tags?entity=tickets" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Tag list

json

{
  "success": true,
  "data": [
    {
      "tag": "billing",
      "entity": "tickets",
      "count": 23
    },
    {
      "tag": "vip",
      "entity": "customers",
      "count": 15
    }
  ]
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

POST /api/v1/teams/{teamId}/tags

Merge Tags

Replace fromTag with toTag on every record that carries it. Without entity, the key needs manage permission on all three entity types.

Request Body

action string required

Always 'merge'

fromTag string required

Tag to replace

toTag string required

Tag that replaces it

entity string

Only tickets, customers or articles

Code Examples

bash

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/tags" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action":"merge","fromTag":"bug","toTag":"defect"}'

Responses

200 Tags merged

json

{
  "success": true,
  "data": {
    "merged": 12,
    "fromTag": "bug",
    "toTag": "defect"
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

DELETE /api/v1/teams/{teamId}/tags

Remove Tag

Remove a tag from every record that carries it. The tag name goes in the JSON body.

Request Body

tag string required

Tag to remove

entity string

Only tickets, customers or articles

Code Examples

bash

curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/tags" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tag":"legacy"}'

Responses

200 Tag removed

json

{
  "success": true,
  "data": {
    "deleted": true,
    "tag": "legacy",
    "removedFrom": 4
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}