Groups API Reference — Bkmark Bookmark Collections

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.

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.

GET /api/v1/groups

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

curl "https://api.bkmark.it/api/v1/groups" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

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

array

Array of group objects.

Show Group object fields

string

UUID of the group.

string

Display name of the group.

string | null

Optional description.

string | null

Hex color string (e.g. #3B82F6), or null.

string | null

Icon identifier string, or null.

string | null

UUID of the parent group for nested hierarchies, or null for top-level groups.

number

Number of bookmarks directly in this group.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

POST /api/v1/groups

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

string

required

Display name for the group.

string

A short description of what this group contains.

string

A hex color string (e.g. #3B82F6) to visually distinguish the group in the UI.

string

An icon identifier string for the group (e.g. briefcase, code-bracket, star).

string

UUID of an existing group to nest this group under. Omit for a top-level group.

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.

{
  "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.

string

required

The UUID of the group to retrieve.

curl "https://api.bkmark.it/api/v1/groups/e5f6a7b8-c9d0-1234-efab-345678901234" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "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.

string

required

The UUID of the group to update.

string

New display name for the group.

string

Updated description. Send null to clear it.

string

Updated hex color string. Send null to remove the color.

string

Updated icon identifier. Send null to remove the icon.

string

UUID of a new parent group to reparent this group. Send null to promote it to a top-level group.

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.

{
  "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.

string

required

The UUID of the group to delete.

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.

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.

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

Overview

Endpoints

OAuth2

Groups API Reference — Bkmark Bookmark Collections

GET /api/v1/groups

POST /api/v1/groups

GET /api/v1/groups/:id

PATCH /api/v1/groups/:id

DELETE /api/v1/groups/:id

​GET /api/v1/groups

​POST /api/v1/groups

​GET /api/v1/groups/:id

​PATCH /api/v1/groups/:id

​DELETE /api/v1/groups/:id

GET /api/v1/groups

POST /api/v1/groups

GET /api/v1/groups/:id

PATCH /api/v1/groups/:id

DELETE /api/v1/groups/:id