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": { ... },
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123"
  }
}

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

Field	Type	Required	Description
`name`	string	Yes	Folder name
`icon`	string	No	Lucide icon name or emoji
`color`	string	No	Color identifier
`rules`	object	Yes	Object with `match` (`"all"` or `"any"`) and `conditions[]` array
`rules.match`	string	Yes	`"all"` (every condition must match) or `"any"` (at least one)
`rules.conditions`	array	Yes	Array of `{ field, operator, value }` objects (max 10 conditions)

Allowed fields and operators:

Field	Allowed Operators	Value
`tag`	`equals`, `contains`	Tag name (exact match or substring)
`domain`	`equals`, `contains`	Domain name (auto-normalized: lowercase, strips scheme/www/path)
`type`	`equals`	`link`, `article`, `image`, `video`, `document`
`isFavorite`	`equals`	`"true"` or `"false"`
`createdAfter`	`equals`	Milliseconds since epoch, as a string (e.g., `"1704067200000"`)
`createdBefore`	`equals`	Milliseconds since epoch, as a string (e.g., `"1704067200000"`)
`clickCount`	`gte`, `lte`	Numeric value as a string (e.g., `"5"`)

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:

Parameter	Type	Description
`cursor`	string	Pagination cursor from previous response

Always follow a non-null continueCursor, even when bookmarks is empty or truncated is false. Tag folders page their selective tag index, and one page can contain only trashed or deleted bookmarks while later pages still contain matches. Exact-tag cursors are opaque and become invalid when the folder rules change; restart without a cursor if the API returns SMART_FOLDER_CURSOR_INVALID. Domain, type, favorite, and fallback cursors are not strategy-bound and may remain accepted after rule changes.

Response:

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

Limits:

Exact-tag rules scan 200 tag memberships per request; other rules scan up to 5,000 bookmarks per evaluation
Returns up to 500 matching bookmarks
Uses cursor-based pagination (200 docs per page)

Smart Folders

List Smart Folders

Get Smart Folder

Create Smart Folder

Update Smart Folder

Delete Smart Folder

Evaluate Smart Folder

On this page