Skip to content

Tags

Availability: Tags are available on every plan, including Free. API keys need 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

MethodPathScope
GET/api/v1/workspaces/{workspace_public_id}/tagstags:read
POST/api/v1/workspaces/{workspace_public_id}/tagstags: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 parameterNotes
team_public_idsTeam public IDs, comma-separated or as a JSON array. Returns workspace-wide tags and the tags assigned to every listed team.
teamnone returns only workspace-wide tags. Ignored when team_public_ids is present.
report_scope1 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
    }
  ]
}
FieldNotes
url_countThe links with this tag that you can see. Left out when 0.
team_public_ids, team_namesThe tag’s teams. Left out for workspace-wide tags.

tags is null when there are no tags to show.

Create a tag

FieldTypeRequiredNotes
namestringYes1 to 20 characters. Unique, ignoring case, among the workspace-wide tags, or among the tags of the same team.
colorstringYesA color such as #3b82f6.
team_public_idsarray of stringsNoTeams 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:

StatuscodeWhen
400invalid_request_formatThe body isn’t valid JSON.
400invalid_tag_nameThe name is empty or longer than 20 characters (details.field is name).
400color_requiredcolor is missing.
403workspace_permission_deniedYou’re a read-only member.
409tag_existsA 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 name and/or color; or
  • replaces the tag’s teams with team_public_ids.

You can’t do both in one request.

FieldTypeRequiredNotes
namestringNo1 to 20 characters.
colorstringNo
team_public_idsarray of stringsNoThe 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:
    • 400 invalid_workspace_id;
    • 404 workspace_not_found, which an archived workspace also returns.
  • A key restricted to one workspace: a tag in another workspace returns 403 api_key_workspace_mismatch.

Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.

Last updated on