Tags API

Label short links with tags, then filter and export links by tag.

Tags are short labels such as a campaign, client or channel. A link can carry up to 10 tags, and one tag can sit on any number of links. Unlike folders, tags overlap, so one link can be both newsletter and q3.

Tag names are unique per workspace, ignoring case, and up to 30 characters. The number of tags per workspace depends on the plan: Free 5, Starter 15, Pro 50, Growth and above unlimited. Deleting a tag removes it from its links and never deletes a link.

GET/api/v1/tags

List the workspace's tags, A to Z, with the number of live links on each.

Scope: tags:read

Request

curl https://trimlink.co/api/v1/tags \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response
{
  "success": true,
  "tags": [
    {
      "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "name": "spring-launch",
      "linkCount": 12,
      "createdAt": "2026-11-19T10:00:00.000Z"
    }
  ]
}
POST/api/v1/tags

Create a tag.

Scope: tags:write

Parameters

NameTypeRequiredDescription
namestringYesTag name, 1 to 30 characters. Letters, numbers, spaces, hyphens, underscores and periods.

Request

curl -X POST https://trimlink.co/api/v1/tags \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "spring-launch"}'

Response

201Response
{
  "success": true,
  "tag": {
    "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "name": "spring-launch",
    "createdAt": "2026-11-19T10:00:00.000Z"
  }
}
PATCH/api/v1/tags/:id

Rename a tag. Every link carrying it shows the new name.

Scope: tags:write

Parameters

NameTypeRequiredDescription
namestringYesNew tag name.

Request

curl -X PATCH https://trimlink.co/api/v1/tags/7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "summer-launch"}'

Response

200Response
{
  "success": true,
  "tag": {
    "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "name": "summer-launch"
  }
}
DELETE/api/v1/tags/:id

Delete a tag. It is removed from every link, and the links stay.

Scope: tags:write

Request

curl -X DELETE https://trimlink.co/api/v1/tags/7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

204 No Content
POST/api/v1/links/:id/tags

Add one tag to a link. Adding a tag the link already has changes nothing.

Scope: tags:write

Parameters

NameTypeRequiredDescription
tagIdstringYesTag ID.

Request

curl -X POST https://trimlink.co/api/v1/links/9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c/tags \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tagId": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}'

Response

200Response
{
  "success": true,
  "tags": [
    { "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "spring-launch" }
  ]
}
DELETE/api/v1/links/:id/tags/:tagId

Remove one tag from a link. The tag itself is kept.

Scope: tags:write

Request

curl -X DELETE https://trimlink.co/api/v1/links/9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c/tags/7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

204 No Content

Tags on links

  • POST /api/v1/links accepts an optional tagIds array (scope links:write). The tags are checked before the link is created, and the response includes the link's tags.
  • PATCH /api/v1/links/:id returns the link's tags. Change tags with the endpoints above.
  • The CSV export has a Tags column with each link's tag names.

Errors

These endpoints use the standard error response format.

CodeWhen it happens
400Invalid or duplicate tag name, more than 10 tags on one link, or a tag ID from another workspace.
403The key is missing the tags:read or tags:write scope, or the plan tag limit is reached. Limit errors include tier, limit, current and limitKey ("tags").
404The tag or link does not exist in this workspace.