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.
/api/v1/tagsCreate a tag.
tags:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tag 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
{
"success": true,
"tag": {
"id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "spring-launch",
"createdAt": "2026-11-19T10:00:00.000Z"
}
}/api/v1/tags/:idRename a tag. Every link carrying it shows the new name.
tags:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | New 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
{
"success": true,
"tag": {
"id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "summer-launch"
}
}/api/v1/tags/:idDelete a tag. It is removed from every link, and the links stay.
tags:writeRequest
curl -X DELETE https://trimlink.co/api/v1/tags/7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
-H "Authorization: Bearer tk_live_your_api_key"Response
/api/v1/links/:id/tagsAdd one tag to a link. Adding a tag the link already has changes nothing.
tags:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
tagId | string | Yes | Tag 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
{
"success": true,
"tags": [
{ "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "spring-launch" }
]
}/api/v1/links/:id/tags/:tagIdRemove one tag from a link. The tag itself is kept.
tags:writeRequest
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
Tags on links
POST /api/v1/linksaccepts an optionaltagIdsarray (scopelinks:write). The tags are checked before the link is created, and the response includes the link'stags.PATCH /api/v1/links/:idreturns the link'stags. 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.
| Code | When it happens |
|---|---|
400 | Invalid or duplicate tag name, more than 10 tags on one link, or a tag ID from another workspace. |
403 | The 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"). |
404 | The tag or link does not exist in this workspace. |