Tags

Tags can be applied to bookmarks for flexible organization. Tags support hierarchy using / separators (e.g., dev/frontend).

List Tags

GET /tags

Scope: tags:read

{
  "data": [
    {
      "id": "tag_abc",
      "name": "development",
      "color": "blue",
      "parentId": null,
      "count": 42,
      "createdAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "tag_def",
      "name": "dev/frontend",
      "color": null,
      "parentId": "tag_abc",
      "count": 15,
      "createdAt": "2026-01-12T09:00:00Z"
    }
  ]
}

Create Tag

POST /tags

Scope: tags:write

Body:

{
  "name": "new-tag",
  "color": "green"
}

Rename Tag

PATCH /tags/:id

Scope: tags:write

Body:

{
  "newName": "renamed-tag"
}

Renaming updates the tag across all bookmarks that use it.

Delete Tag

DELETE /tags/:id

Scope: tags:write

Removes the tag and all bookmark-tag associations. The bookmarks themselves are not affected.

Merge Tags

POST /tags/merge

Scope: tags:write

Merges one tag into another. All bookmarks with the source tag will be re-tagged with the target tag. The source tag is deleted.

Note: Only leaf tags (tags without children) can be merged as the source.

Body:

{
  "sourceTagId": "tag_abc",
  "targetTagId": "tag_def"
}

List Bookmarks by Tag ID

GET /tags/by-id/:id/bookmarks

Scope: bookmarks:read

Returns all bookmarks that have the specified tag. This is an alternative to GET /tags/:name/bookmarks that uses the tag's ID instead of its name. This is useful for hierarchical tags that contain / characters in their names, which would conflict with URL path segments.

Query Parameters:

Response:

{
  "data": {
    "bookmarks": [ ... ],
    "tag": {
      "id": "tag_abc",
      "name": "development",
      "color": "blue",
      "parentId": null,
      "count": 42,
      "createdAt": "2026-01-10T08:00:00Z"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

The tag field is null if the tag ID does not match any existing tag.