Skip to main content
Tags give you a fast, flexible way to label and cross-reference bookmarks across any group. You can create tags on the fly when saving bookmarks, or manage them explicitly through the Tags API. Every tag tracks how many bookmarks carry it, so you can see which labels are actually in use. All endpoints require a Bearer token in the Authorization header.
When you create a bookmark and supply tagNames, any names that don’t already exist are created automatically. You don’t need to pre-create tags unless you want to assign a specific color upfront.

​
GET /api/v1/tags

List all tags for the authenticated user, ordered by name. Each tag includes a count field showing how many bookmarks currently carry it. 
curl "https://api.bkmark.it/api/v1/tags" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "typescript",
      "color": "blue",
      "count": 34,
      "createdAt": "2024-09-10T08:00:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "reading",
      "color": "amber",
      "count": 121,
      "createdAt": "2024-09-10T08:01:15.000Z"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "ai",
      "color": "violet",
      "count": 58,
      "createdAt": "2024-12-01T11:30:00.000Z"
    }
  ]
}
​
data
array
Array of tag objects.

​
POST /api/v1/tags

Create a new tag. Tag names must be unique within your account. Optionally assign a color from the supported palette.
​
name
string
required
The tag name. Must be unique for the authenticated user.
​
color
string
Color to assign. Must be one of: red, orange, amber, yellow, lime, green, teal, cyan, blue, indigo, violet, pink. Omit or pass null for the default unstyled appearance.
The available color slugs map to the Tailwind CSS color palette. Clients rendering tags should treat any unrecognized color value as the default style to remain forward-compatible.
curl -X POST "https://api.bkmark.it/api/v1/tags" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "machine-learning",
    "color": "violet"
  }'
Returns 201 Created with the new tag object. 
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "name": "machine-learning",
  "color": "violet",
  "count": 0,
  "createdAt": "2025-04-01T10:15:42.000Z"
}

​
PATCH /api/v1/tags/:id

Update an existing tag’s name or color. Both fields are optional — send only what you want to change.
​
id
string
required
The UUID of the tag to update.
​
name
string
New name for the tag. Must be unique within the account. All bookmarks using this tag will immediately reflect the new name.
​
color
string
New color. Must be one of the supported color slugs (see POST /api/v1/tags), or null to remove the color.
curl -X PATCH "https://api.bkmark.it/api/v1/tags/d4e5f6a7-b8c9-0123-defa-234567890123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ml",
    "color": "indigo"
  }'
Returns 200 OK with the updated tag object. 
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "name": "ml",
  "color": "indigo",
  "count": 0,
  "createdAt": "2025-04-01T10:15:42.000Z"
}

​
DELETE /api/v1/tags/:id

Delete a tag. Bkmark removes the tag from every bookmark that carries it before deleting the record. Bookmarks themselves are not deleted.
​
id
string
required
The UUID of the tag to delete.
Deleting a tag removes it from all associated bookmarks immediately. This cannot be undone. If you have hundreds of bookmarks using the tag, consider renaming it instead.
curl -X DELETE "https://api.bkmark.it/api/v1/tags/d4e5f6a7-b8c9-0123-defa-234567890123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Returns 204 No Content on success.