Smart Folders

Smart folders are virtual folders that automatically contain bookmarks matching a set of rules. They don't physically move bookmarks -- they evaluate rules on demand.

List Smart Folders

GET /smart-folders

Scope: bookmarks:read

{
  "data": [
    {
      "id": "sf_abc",
      "name": "Unread Articles",
      "icon": "book-open",
      "color": "orange",
      "rules": { ... }
    }
  ]
}

Get Smart Folder

GET /smart-folders/:id

Scope: bookmarks:read

Returns the smart folder with its rule definitions.

Create Smart Folder

POST /smart-folders

Scope: bookmarks:write

Body:

{
  "name": "Recent GitHub Stars",
  "icon": "star",
  "color": "yellow",
  "rules": {
    "match": "all",
    "conditions": [
      { "field": "domain", "operator": "equals", "value": "github.com" },
      { "field": "isFavorite", "operator": "equals", "value": "true" }
    ]
  }
}

Update Smart Folder

PATCH /smart-folders/:id

Scope: bookmarks:write

Delete Smart Folder

DELETE /smart-folders/:id

Scope: bookmarks:write

Deletes the folder definition. No bookmarks are affected.

Evaluate Smart Folder

GET /smart-folders/:id/bookmarks

Scope: bookmarks:read

Evaluates the folder's rules and returns matching bookmarks. This is a heavy endpoint with a rate limit of 1 request per minute.

Query Parameters:

Response:

{
  "data": {
    "bookmarks": [ ... ],
    "continueCursor": "eyJ...",
    "truncated": false
  }
}

Limits:

• Scans up to 5,000 documents per evaluation
• Returns up to 500 matching bookmarks
• Uses cursor-based pagination (200 docs per page)