Tags
tags:read to list and read tags, and tags:write to create, change and delete them.Tags label links within a workspace. A tag in no team is available to
the whole workspace; a tag can also be limited to one or more teams. Identify a tag by its
public_id. To put tags on a link, send their public IDs as tag_public_ids when you
create or update the link.
These endpoints return their objects directly, without a data wrapper.
Endpoints
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/workspaces/{workspace_public_id}/tags | tags:read |
POST | /api/v1/workspaces/{workspace_public_id}/tags | tags:write |
GET | /api/v1/tags/{tag_public_id} | tags:read |
PUT | /api/v1/tags/{tag_public_id} | tags:write |
DELETE | /api/v1/tags/{tag_public_id} | tags:write |
Every workspace member can list and read tags. Workspace owners and administrators see every tag; other members see workspace-wide tags and the tags of teams they belong to. Owners, administrators and collaborators can create, change and delete tags.
List tags
Returns the workspace’s tags, sorted by name.
| Query parameter | Notes |
|---|---|
team_public_ids | Team public IDs, comma-separated or as a JSON array. Returns workspace-wide tags and the tags assigned to every listed team. |
team | none returns only workspace-wide tags. Ignored when team_public_ids is present. |
report_scope | 1 treats the teams as a report’s scope: workspace-wide tags plus tags in any listed team. |
curl https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/tags \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"tags": [
{
"id": 42,
"public_id": "3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26",
"user_id": 7,
"workspace_id": 12,
"workspace_wide": true,
"name": "Spring sale",
"color": "#3b82f6",
"created_at": "2026-04-03T12:00:00Z",
"updated_at": "2026-04-03T12:00:00Z",
"url_count": 18
}
]
}| Field | Notes |
|---|---|
url_count | The links with this tag that you can see. Left out when 0. |
team_public_ids, team_names | The tag’s teams. Left out for workspace-wide tags. |
tags is null when there are no tags to show.
Create a tag
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1 to 20 characters. Unique, ignoring case, among the workspace-wide tags, or among the tags of the same team. |
color | string | Yes | A color such as #3b82f6. |
team_public_ids | array of strings | No | Teams to limit the tag to. Leave it out for a workspace-wide tag. |
curl -X POST https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/tags \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Spring sale", "color": "#3b82f6"}'The response is 201:
{
"id": 42,
"public_id": "3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26",
"name": "Spring sale",
"color": "#3b82f6",
"workspace_wide": true,
"team_public_ids": [],
"team_names": [],
"created_at": "2026-04-03T12:00:00Z"
}Errors:
| Status | code | When |
|---|---|---|
400 | invalid_request_format | The body isn’t valid JSON. |
400 | invalid_tag_name | The name is empty or longer than 20 characters (details.field is name). |
400 | color_required | color is missing. |
403 | workspace_permission_denied | You’re a read-only member. |
409 | tag_exists | A tag with this name already exists. |
An unknown team returns 400 with only an error message, such as team not found or
team does not belong to workspace.
Get a tag
curl https://app.shortn.link/api/v1/tags/3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26 \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"id": 42,
"public_id": "3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26",
"name": "Spring sale",
"color": "#3b82f6",
"url_count": 18,
"workspace_wide": true,
"team_public_ids": [],
"team_names": [],
"created_at": "2026-04-03T12:00:00Z"
}A tag you can’t see returns 404.
Update a tag
PUT changes what you send and keeps the rest. A request either:
- changes
nameand/orcolor; or - replaces the tag’s teams with
team_public_ids.
You can’t do both in one request.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | 1 to 20 characters. |
color | string | No | |
team_public_ids | array of strings | No | The tag’s complete list of teams. Send [] to make it workspace-wide. |
curl -X PUT https://app.shortn.link/api/v1/tags/3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26 \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Spring sale 2027", "color": "#16a34a"}'The response is the updated tag, as in Get a tag.
Errors:
400:invalid_tag_name;Update the tag access boundary separately from name or color changes, when you sent teams together with a name or color.
404: the tag doesn’t exist, or you can’t change it.409:Tag with this name already exists in one or more selected teams;workspace_archived, when the tag’s workspace is archived;- a team change that would leave the tag on links it no longer reaches.
Delete a tag
Deleting a tag removes it from every link that had it.
curl -X DELETE https://app.shortn.link/api/v1/tags/3f9c2a10-6b1d-4e8f-a2c7-5d0e9b4f1a26 \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"message": "Tag deleted successfully",
"links_updated": 18
}links_updated is the number of links the tag was removed from. A tag in an archived
workspace returns 409 workspace_archived.
Errors
Validation errors use the API’s usual shape, with a code:
{
"code": "invalid_tag_name",
"error": "Tag name must be between 1 and 20 characters",
"details": { "field": "name" }
}Some errors carry only error, without a code, for example {"error": "Tag not found"}.
These checks run before the tag endpoints:
- The workspace in the path:
400invalid_workspace_id;404workspace_not_found, which an archived workspace also returns.
- A key restricted to one workspace: a tag in another workspace returns
403api_key_workspace_mismatch.
Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.