Tags endpoints
Create, list, rename, recolour and delete Muro Links tags through the API.
Tags group your short links. These endpoints manage the tags themselves. To attach tags to a link, send tag_ids or tag_names on the links endpoints. All paths are relative to https://app.muroanalytics.com/api/v1.
| Method | Path | What it does |
|---|---|---|
POST | /tags | Create a tag |
GET | /tags | List tags |
PATCH | /tags/{id} | Rename or recolour a tag |
DELETE | /tags/{id} | Delete a tag |
GET | /tags/{id}/stats | Tag click analytics, see Stats endpoints |
The tag object
{
"id": "tag_6a1d0c2b-4e8f-4b3a-9c7d-1e2f3a4b5c6d",
"name": "launch",
"color": "indigo",
"link_count": 3
}| Field | Type | Description |
|---|---|---|
id | string | The tag's ID, starting with tag_. |
name | string | The tag's name. Unique in your account, ignoring case. |
color | string | One of indigo, violet, cyan, fuchsia, lime, slate. |
link_count | number | How many live links carry the tag. |
Links embed a shorter form, { id, name, color }, without link_count.
Create a tag
POST /tags
Body
| Field | Type | Required | Rules |
|---|---|---|---|
name | string | Yes | Trimmed, 1–50 characters, no control characters or line breaks. Unique in your account, ignoring case. |
color | string | No | One of indigo, violet, cyan, fuchsia, lime, slate. If omitted, Muro assigns one in rotation. |
Example
curl -X POST https://app.muroanalytics.com/api/v1/tags \
-H "Authorization: Bearer muro_lnk_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "newsletter", "color": "cyan" }'Response
201 Created:
{
"id": "tag_0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
"name": "newsletter",
"color": "cyan",
"link_count": 0
}Errors
| Status | Code | When |
|---|---|---|
400 | INVALID_JSON | The body isn't valid JSON. |
403 | PLAN_LIMIT_REACHED | You're at your plan's tag limit (25 on Starter, 200 on Team and trial). |
409 | TAG_NAME_TAKEN | You already have a tag with that name, ignoring case. |
422 | VALIDATION_ERROR | The name is missing, too long or has control characters, or the colour isn't one of the six. |
List tags
GET /tags
Returns all your tags, newest first. This list isn't paginated.
curl https://app.muroanalytics.com/api/v1/tags \
-H "Authorization: Bearer muro_lnk_xxxxxxxxxxxx"200 OK:
{
"tags": [
{ "id": "tag_0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "name": "newsletter", "color": "cyan", "link_count": 0 },
{ "id": "tag_6a1d0c2b-4e8f-4b3a-9c7d-1e2f3a4b5c6d", "name": "launch", "color": "indigo", "link_count": 3 }
],
"tag_limit": 200
}tag_limit is your plan's tag limit, or null if unlimited.
Rename or recolour a tag
PATCH /tags/{id}
Send name, color, or both. The change shows on every link that carries the tag.
curl -X PATCH https://app.muroanalytics.com/api/v1/tags/tag_6a1d0c2b-4e8f-4b3a-9c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer muro_lnk_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "launch-2026", "color": "violet" }'200 OK with the updated tag object:
{
"id": "tag_6a1d0c2b-4e8f-4b3a-9c7d-1e2f3a4b5c6d",
"name": "launch-2026",
"color": "violet",
"link_count": 3
}Errors: 404 TAG_NOT_FOUND if the tag isn't in your account, 409 TAG_NAME_TAKEN if the new name is in use, and 422 VALIDATION_ERROR for an invalid name or colour, or a body with neither field.
Delete a tag
DELETE /tags/{id}
curl -X DELETE https://app.muroanalytics.com/api/v1/tags/tag_6a1d0c2b-4e8f-4b3a-9c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer muro_lnk_xxxxxxxxxxxx"Returns 204 No Content. The tag is removed from every link that carried it. The links themselves aren't changed. Deleting a tag can't be undone.
Errors: 404 TAG_NOT_FOUND.
Tags on links
On POST /links, PATCH /links/{id} and POST /links/upsert:
tag_idsattaches existing tags by ID. An ID that isn't yours returns404 TAG_NOT_FOUNDand nothing is saved.tag_namesattaches tags by name, matched ignoring case. Names with no match are created, with a colour assigned in rotation, and count toward your tag limit.- A link can carry at most 10 tags across both fields.
- When updating, sending either field replaces the link's full tag set. Send
[]to remove all tags, or omit both to leave them alone.
{ "title": "Launch tweet", "destination_url": "https://yourapp.com", "tag_names": ["launch", "twitter"] }To list only links with certain tags, use GET /links?tag_ids=…. See List links.