Collections

Collections are folders for organizing bookmarks. They support nesting via parent-child relationships.

List Collections

GET /collections

Scope: collections:read

Returns a flat list of all collections. Use the parentId field to build a tree client-side.

{
  "data": [
    {
      "id": "col_abc",
      "name": "Development",
      "icon": "code",
      "color": "blue",
      "parentId": null,
      "depth": 0,
      "order": 0,
      "bookmarkCount": 24,
      "notes": "",
      "branding": null,
      "shareSlug": null,
      "isShared": false,
      "createdAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "col_def",
      "name": "Frontend",
      "icon": "layout",
      "color": "green",
      "parentId": "col_abc",
      "depth": 1,
      "order": 0,
      "bookmarkCount": 15,
      "notes": "Frontend resources",
      "branding": null,
      "shareSlug": "frontend-resources",
      "isShared": true,
      "createdAt": "2026-01-12T09:00:00Z"
    }
  ]
}

Get Collection

GET /collections/:id

Scope: collections:read

Create Collection

POST /collections

Scope: collections:write

Body:

{
  "name": "My Collection",
  "icon": "folder",
  "color": "blue",
  "parentId": "col_abc"
}

Update Collection

PATCH /collections/:id

Scope: collections:write

Body:

{
  "name": "Renamed Collection",
  "icon": "star",
  "color": "yellow",
  "notes": "Collection notes"
}

Delete Collection (Soft)

DELETE /collections/:id

Scope: collections:write

Moves the collection to trash. Child collections and bookmarks are cascaded.

One request can move at most 1,000 rows: the collection, its child collections, and every bookmark in them. Bookmarks already in the trash still count until they are permanently deleted. A larger collection is rejected with 422 COLLECTION_TOO_LARGE and nothing is changed. Trash its child collections first, or move its bookmarks to another collection (see bulk operations), or trash them and delete them permanently (DELETE /bookmarks/:id/permanent), then retry.

Restore Collection

POST /collections/:id/restore

Scope: collections:write

The same 1,000-row limit applies. A larger restore is rejected with 422 COLLECTION_TOO_LARGE and nothing is changed. Restore some of its bookmarks first with POST /bookmarks/:id/restore: while the collection is in the trash they come back unsorted and stop counting toward it. Then retry, and move them back with POST /bookmarks/bulk/move. Do not empty the trash (DELETE /bookmarks/trash): that permanently deletes the bookmarks you want back.

List Trashed Collections

GET /collections/trashed

Scope: collections:read

List Bookmarks in Collection

GET /collections/:id/bookmarks

Scope: bookmarks:read

Returns bookmarks assigned to this collection with cursor-based pagination.

Query Parameters:

Response:

{
  "data": {
    "bookmarks": [ ... ],
    "continueCursor": "eyJ..."
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

continueCursor is null when there are no more results.

Get Share Status

GET /collections/:id/share

Scope: collections:read

{
  "data": {
    "shared": true,
    "publicUrl": "/shared/my-collection-slug"
  }
}