Tags API Reference — Organize Bookmarks with Bkmark

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"
    }
  ]
}

array

Array of tag objects.

Show Tag object fields

string

UUID of the tag.

string

The tag’s display name.

string | null

Color slug from the available palette, or null for the default style.

number

Number of bookmarks that currently have this tag applied.

string

ISO 8601 creation timestamp.

POST /api/v1/tags

Create a new tag. Tag names must be unique within your account. Optionally assign a color from the supported palette.

string

required

The tag name. Must be unique for the authenticated user.

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.

string

required

The UUID of the tag to update.

string

New name for the tag. Must be unique within the account. All bookmarks using this tag will immediately reflect the new name.

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.

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.

Overview

Endpoints

OAuth2

Tags API Reference — Organize Bookmarks with Bkmark

GET /api/v1/tags

POST /api/v1/tags

PATCH /api/v1/tags/:id

DELETE /api/v1/tags/:id

​GET /api/v1/tags

​POST /api/v1/tags

​PATCH /api/v1/tags/:id

​DELETE /api/v1/tags/:id

GET /api/v1/tags

POST /api/v1/tags

PATCH /api/v1/tags/:id

DELETE /api/v1/tags/:id