> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bkmark.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags API Reference — Organize Bookmarks with Bkmark

> Create, list, update, and delete tags for organizing bookmarks. Each tag supports a name and an optional color from a fixed palette.

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.

<Note>
  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.
</Note>

***

## 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.

```bash theme={null}
curl "https://api.bkmark.it/api/v1/tags" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="data" type="array">
  Array of tag objects.

  <Expandable title="Tag object fields">
    <ResponseField name="id" type="string">UUID of the tag.</ResponseField>
    <ResponseField name="name" type="string">The tag's display name.</ResponseField>
    <ResponseField name="color" type="string | null">Color slug from the available palette, or `null` for the default style.</ResponseField>
    <ResponseField name="count" type="number">Number of bookmarks that currently have this tag applied.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
  </Expandable>
</ResponseField>

***

## POST /api/v1/tags

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

<ParamField body="name" type="string" required>
  The tag name. Must be unique for the authenticated user.
</ParamField>

<ParamField body="color" type="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.
</ParamField>

<Tip>
  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.
</Tip>

```bash theme={null}
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.

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The UUID of the tag to update.
</ParamField>

<ParamField body="name" type="string">
  New name for the tag. Must be unique within the account. All bookmarks using this tag will immediately reflect the new name.
</ParamField>

<ParamField body="color" type="string">
  New color. Must be one of the supported color slugs (see [POST /api/v1/tags](#post-apiv1tags)), or `null` to remove the color.
</ParamField>

```bash theme={null}
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.

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The UUID of the tag to delete.
</ParamField>

<Warning>
  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.
</Warning>

```bash theme={null}
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.