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

# Groups API Reference — Bkmark Bookmark Collections

> Create and manage bookmark groups, including nested hierarchies. Supports custom colors, icons, and safe deletion with bookmark reassignment.

Groups let you organize bookmarks into named collections — think folders or boards. Groups can be nested by setting a `parentId`, so you can build a hierarchy like `Engineering → Frontend → React`. A bookmark can belong to multiple groups at once. All endpoints require a Bearer token in the `Authorization` header.

<Note>
  Groups are distinct from tags. Tags are flat labels applied directly to bookmarks; groups are containers that you can nest and assign icons and colors to for richer organization.
</Note>

***

## GET /api/v1/groups

List all groups for the authenticated user. The response includes each group's metadata and bookmark count.

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

```json theme={null}
{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Engineering",
      "description": "Tech articles, docs, and code references",
      "color": "#3B82F6",
      "icon": "code-bracket",
      "parentId": null,
      "count": 87,
      "createdAt": "2024-08-01T09:00:00.000Z",
      "updatedAt": "2025-03-20T14:30:00.000Z"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "name": "Frontend",
      "description": "UI, CSS, and browser APIs",
      "color": "#8B5CF6",
      "icon": "paint-brush",
      "parentId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "count": 41,
      "createdAt": "2024-08-02T10:00:00.000Z",
      "updatedAt": "2025-03-18T09:15:00.000Z"
    }
  ]
}
```

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

  <Expandable title="Group object fields">
    <ResponseField name="id" type="string">UUID of the group.</ResponseField>
    <ResponseField name="name" type="string">Display name of the group.</ResponseField>
    <ResponseField name="description" type="string | null">Optional description.</ResponseField>
    <ResponseField name="color" type="string | null">Hex color string (e.g. `#3B82F6`), or `null`.</ResponseField>
    <ResponseField name="icon" type="string | null">Icon identifier string, or `null`.</ResponseField>
    <ResponseField name="parentId" type="string | null">UUID of the parent group for nested hierarchies, or `null` for top-level groups.</ResponseField>
    <ResponseField name="count" type="number">Number of bookmarks directly in this group.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

***

## POST /api/v1/groups

Create a new group. Only `name` is required. Use `parentId` to nest the group inside an existing one.

<ParamField body="name" type="string" required>
  Display name for the group.
</ParamField>

<ParamField body="description" type="string">
  A short description of what this group contains.
</ParamField>

<ParamField body="color" type="string">
  A hex color string (e.g. `#3B82F6`) to visually distinguish the group in the UI.
</ParamField>

<ParamField body="icon" type="string">
  An icon identifier string for the group (e.g. `briefcase`, `code-bracket`, `star`).
</ParamField>

<ParamField body="parentId" type="string">
  UUID of an existing group to nest this group under. Omit for a top-level group.
</ParamField>

```bash theme={null}
curl -X POST "https://api.bkmark.it/api/v1/groups" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "React",
    "description": "React ecosystem: docs, patterns, and tooling",
    "color": "#06B6D4",
    "icon": "cube",
    "parentId": "d4e5f6a7-b8c9-0123-defa-234567890123"
  }'
```

Returns `201 Created` with the new group object.

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "name": "React",
  "description": "React ecosystem: docs, patterns, and tooling",
  "color": "#06B6D4",
  "icon": "cube",
  "parentId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "count": 0,
  "createdAt": "2025-04-01T11:00:00.000Z",
  "updatedAt": "2025-04-01T11:00:00.000Z"
}
```

***

## GET /api/v1/groups/:id

Retrieve a single group by its UUID.

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

```bash theme={null}
curl "https://api.bkmark.it/api/v1/groups/e5f6a7b8-c9d0-1234-efab-345678901234" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "name": "React",
  "description": "React ecosystem: docs, patterns, and tooling",
  "color": "#06B6D4",
  "icon": "cube",
  "parentId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "count": 0,
  "createdAt": "2025-04-01T11:00:00.000Z",
  "updatedAt": "2025-04-01T11:00:00.000Z"
}
```

***

## PATCH /api/v1/groups/:id

Update a group's name, description, color, icon, or parent. All body fields are optional — send only what you want to change.

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

<ParamField body="name" type="string">
  New display name for the group.
</ParamField>

<ParamField body="description" type="string">
  Updated description. Send `null` to clear it.
</ParamField>

<ParamField body="color" type="string">
  Updated hex color string. Send `null` to remove the color.
</ParamField>

<ParamField body="icon" type="string">
  Updated icon identifier. Send `null` to remove the icon.
</ParamField>

<ParamField body="parentId" type="string">
  UUID of a new parent group to reparent this group. Send `null` to promote it to a top-level group.
</ParamField>

```bash theme={null}
curl -X PATCH "https://api.bkmark.it/api/v1/groups/e5f6a7b8-c9d0-1234-efab-345678901234" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "React & Next.js",
    "color": "#0EA5E9",
    "description": "React ecosystem plus Next.js patterns and deployments"
  }'
```

Returns `200 OK` with the updated group object.

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "name": "React & Next.js",
  "description": "React ecosystem plus Next.js patterns and deployments",
  "color": "#0EA5E9",
  "icon": "cube",
  "parentId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "count": 0,
  "createdAt": "2025-04-01T11:00:00.000Z",
  "updatedAt": "2025-04-01T11:45:22.000Z"
}
```

***

## DELETE /api/v1/groups/:id

Delete a group. By default, bookmarks inside the group are **not deleted** — they remain in your library without a group assignment. Use `?moveBookmarksTo=<uuid>` to reassign them to another group atomically before the delete completes.

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

<ParamField query="moveBookmarksTo" type="string">
  UUID of a destination group. All bookmarks in the deleted group are moved here before deletion. The destination group must exist and belong to the authenticated user.
</ParamField>

<Tip>
  Use `?moveBookmarksTo` when you're consolidating groups to avoid leaving bookmarks orphaned. It's a single atomic operation — either the move and delete both succeed, or neither does.
</Tip>

```bash theme={null}
# Delete group and leave bookmarks ungrouped
curl -X DELETE "https://api.bkmark.it/api/v1/groups/e5f6a7b8-c9d0-1234-efab-345678901234" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Delete group and move its bookmarks to another group
curl -X DELETE "https://api.bkmark.it/api/v1/groups/e5f6a7b8-c9d0-1234-efab-345678901234?moveBookmarksTo=d4e5f6a7-b8c9-0123-defa-234567890123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

Returns `204 No Content` on success.