Skip to main content
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"
    }
  ]
}
​
data
array
Array of group objects.

​
POST /api/v1/groups

Create a new group. Only name is required. Use parentId to nest the group inside an existing one.
​
name
string
required
Display name for the group.
​
description
string
A short description of what this group contains.
​
color
string
A hex color string (e.g. #3B82F6) to visually distinguish the group in the UI.
​
icon
string
An icon identifier string for the group (e.g. briefcase, code-bracket, star).
​
parentId
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.
​
id
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.
​
id
string
required
The UUID of the group to update.
​
name
string
New display name for the group.
​
description
string
Updated description. Send null to clear it.
​
color
string
Updated hex color string. Send null to remove the color.
​
icon
string
Updated icon identifier. Send null to remove the icon.
​
parentId
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.
​
id
string
required
The UUID of the group to delete.
​
moveBookmarksTo
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.