Bookmarks

List Bookmarks

GET /bookmarks

Scope: bookmarks:read

Query Parameters:

Parameter	Type	Description
`limit`	number	Max results to return (default: 50)
`collectionId`	string	Filter by collection ID
`domain`	string	Filter by domain (e.g., `github.com`)
`type`	string	Filter by type: `link`, `article`, `image`, `video`, `document`
`isFavorite`	boolean	Filter favorites only
`sortBy`	string	Sort order

Response:

{
  "data": [
    {
      "id": "abc123",
      "url": "https://example.com",
      "title": "Example Site",
      "description": "An example website",
      "note": "My personal notes",
      "type": "link",
      "isFavorite": false,
      "tags": ["dev", "reference"],
      "collectionId": "col_xyz",
      "domain": "example.com",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ]
}

Get Bookmark

GET /bookmarks/:id

Scope: bookmarks:read

Response: single bookmark object (same shape as list items)

Create Bookmark

POST /bookmarks

Scope: bookmarks:write

Body:

{
  "url": "https://example.com",
  "title": "Example Site",
  "description": "Optional description",
  "note": "Optional personal note",
  "tags": ["dev", "reference"],
  "collectionId": "col_xyz",
  "type": "link",
  "isFavorite": false
}

Field	Type	Required	Description
`url`	string	Yes	The URL to bookmark
`title`	string	No	Override the auto-detected title
`description`	string	No	Override the auto-detected description
`note`	string	No	Personal notes
`tags`	string[]	No	Tags to apply
`collectionId`	string	No	Collection to add to
`type`	string	No	Content type override
`isFavorite`	boolean	No	Mark as favorite (default: false)

If the URL already exists in your trash, it will be restored instead of creating a duplicate.

Update Bookmark

PATCH /bookmarks/:id

Scope: bookmarks:write

Body: any subset of bookmark fields (partial update)

{
  "title": "Updated Title",
  "note": "New notes"
}

Delete Bookmark (Soft)

DELETE /bookmarks/:id

Scope: bookmarks:write

Moves the bookmark to trash. It can be restored within 30 days.

Restore Bookmark

POST /bookmarks/:id/restore

Scope: bookmarks:write

Restores a trashed bookmark.

Permanently Delete Bookmark

DELETE /bookmarks/:id/permanent

Scope: destructive

Permanently deletes the bookmark and all associated data (tags, highlights, uploads). This cannot be undone.

Set Favorite

PUT /bookmarks/:id/favorite

Scope: bookmarks:write

Body:

{
  "isFavorite": true
}

Move Bookmark

POST /bookmarks/:id/move

Scope: bookmarks:write

Body:

{
  "collectionId": "col_xyz"
}

Pass null for collectionId to move to Unsorted.

Search Bookmarks

GET /bookmarks/search

Scope: bookmarks:read

Query Parameters:

Parameter	Type	Required	Description
`q`	string	Yes	Search query
`titleOnly`	boolean	No	Search titles only (default: false)

Response: array of matching bookmarks

List Domains

GET /bookmarks/domains

Scope: bookmarks:read

Returns all domains with bookmark counts.

{
  "data": [
    { "domain": "github.com", "count": 42 },
    { "domain": "stackoverflow.com", "count": 15 }
  ]
}

Get Stats

GET /bookmarks/stats

Scope: bookmarks:read

{
  "data": {
    "total": 1234,
    "favorites": 89,
    "unsorted": 45,
    "typeCounts": {
      "link": 800,
      "article": 300,
      "video": 100,
      "image": 30,
      "document": 4
    },
    "noTags": 200
  }
}

Bookmark Tags

GET /bookmarks/:id/tags

Scope: bookmarks:read

Add Tag to Bookmark

POST /bookmarks/:id/tags

Scope: tags:write

Body:

{
  "name": "important"
}

Remove Tag from Bookmark

DELETE /bookmarks/:id/tags/:tagId

Scope: tags:write

List Bookmarks by Tag Name

GET /tags/:name/bookmarks

Scope: bookmarks:read

Bookmarks

On this page