Bookmarks
Save links and notes, edit them, move them to the trash and back, and read their saved copies and AI suggestions.
- post /v1/bookmarks/{id}/share-to-library
- post /v1/bookmarks
- get /v1/bookmarks
- post /v1/bookmarks/bulk
- get /v1/bookmarks/{id}
- patch /v1/bookmarks/{id}
- delete /v1/bookmarks/{id}
- post /v1/bookmarks/{id}/restore
- delete /v1/trash
- post /v1/bookmarks/{id}/refetch
- post /v1/bookmarks/{id}/check
- get /v1/bookmarks/{id}/saved-copy
- post /v1/bookmarks/{id}/tags
- delete /v1/bookmarks/{id}/tags/{tagId}
- get /v1/counts
- get /v1/bookmarks/{id}/suggestions
- post /v1/bookmarks/{id}/suggestions
- post /v1/bookmarks/{id}/opened
post /v1/bookmarks
Save a link or note. A url already in the library returns it (200, duplicate: true) with tags and collections merged in.
Key or token with bookmarks:write Returns 200, 201
Body
| Name | Type | Description |
|---|---|---|
kind | enum | One of link, note. Default "link". |
url | string | Up to 4,096 characters. |
title | string | Up to 500 characters. |
description | string | Up to 100,000 characters. |
tags | string[] | Up to 50 items. |
collectionIds | uuid[] | Up to 50 items. |
source | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. Default "api". |
sourceDetail | string | Up to 200 characters. |
text | string | Up to 10,000 characters. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks' \
-H "Authorization: Bearer $BKMARK_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/article","title":"Hybrid search with pgvector"}' Response fields (27)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
kindrequired | enum | One of link, note. |
urlrequired | string or null | |
canonicalUrlrequired | string or null | |
titlerequired | string or null | |
descriptionrequired | string or null | |
summaryrequired | string or null | |
siteNamerequired | string or null | |
faviconUrlrequired | string or null | |
imageUrlrequired | string or null | |
sourcerequired | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
sourceDetailrequired | string or null | |
sourceAuthorrequired | string or null | |
fetchStatusrequired | enum | One of pending, ok, failed, gone. |
readAtrequired | string or null | |
archivedAtrequired | string or null | |
ribbonedAtrequired | string or null | |
deletedAtrequired | string or null | |
lastCheckedAtrequired | string or null | |
createdByrequired | uuid or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
tagsrequired | string[] | |
collectionIdsrequired | uuid[] | |
hasSavedCopyrequired | boolean | |
duplicaterequired | boolean |
get /v1/bookmarks
List bookmarks with filters and a cursor (deleted=true lists the trash).
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
collection | uuid | |
tag | string | 1–50 characters. |
kind | enum | One of link, note. |
source | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
unread | enum | One of true, false. |
archived | enum | One of true, false. |
ribboned | enum | One of true, false. |
broken | enum | One of true, false. |
deleted | enum | One of true, false. |
savedAfter | timestamp | |
savedBefore | timestamp | |
sort | enum | One of newest, oldest. Default "newest". |
cursor | string | Up to 300 characters. |
limit | integer | Default 50. 1–100. |
Example
curl 'https://api.bkmark.it/v1/bookmarks' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (2)
| Name | Type | Description |
|---|---|---|
datarequired | object[] | |
idrequired | uuid | |
libraryIdrequired | uuid | |
kindrequired | enum | One of link, note. |
urlrequired | string or null | |
canonicalUrlrequired | string or null | |
titlerequired | string or null | |
descriptionrequired | string or null | |
summaryrequired | string or null | |
siteNamerequired | string or null | |
faviconUrlrequired | string or null | |
imageUrlrequired | string or null | |
sourcerequired | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
sourceDetailrequired | string or null | |
sourceAuthorrequired | string or null | |
fetchStatusrequired | enum | One of pending, ok, failed, gone. |
readAtrequired | string or null | |
archivedAtrequired | string or null | |
ribbonedAtrequired | string or null | |
deletedAtrequired | string or null | |
lastCheckedAtrequired | string or null | |
createdByrequired | uuid or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
tagsrequired | string[] | |
collectionIdsrequired | uuid[] | |
hasSavedCopyrequired | boolean | |
nextCursorrequired | string or null |
post /v1/bookmarks/bulk
Apply one action to up to 500 bookmarks.
Key or token with bookmarks:write Returns 200
Body
| Name | Type | Description |
|---|---|---|
actionrequired | enum | One of archive, unarchive, read, unread, ribbon, unribbon, delete, restore, purge, tag, untag, add_to_collection, remove_from_collection. |
idsrequired | uuid[] | Up to 500 items. |
tags | string[] | Up to 20 items. |
collectionId | uuid |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/bulk' \
-H "Authorization: Bearer $BKMARK_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"action":"archive","ids":["0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e"]}' Response fields (1)
| Name | Type | Description |
|---|---|---|
updatedrequired | integer | -9007199254740991–9007199254740991. |
get /v1/bookmarks/{id}
One bookmark (trashed ones included).
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (26)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
kindrequired | enum | One of link, note. |
urlrequired | string or null | |
canonicalUrlrequired | string or null | |
titlerequired | string or null | |
descriptionrequired | string or null | |
summaryrequired | string or null | |
siteNamerequired | string or null | |
faviconUrlrequired | string or null | |
imageUrlrequired | string or null | |
sourcerequired | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
sourceDetailrequired | string or null | |
sourceAuthorrequired | string or null | |
fetchStatusrequired | enum | One of pending, ok, failed, gone. |
readAtrequired | string or null | |
archivedAtrequired | string or null | |
ribbonedAtrequired | string or null | |
deletedAtrequired | string or null | |
lastCheckedAtrequired | string or null | |
createdByrequired | uuid or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
tagsrequired | string[] | |
collectionIdsrequired | uuid[] | |
hasSavedCopyrequired | boolean |
patch /v1/bookmarks/{id}
Edit a bookmark; a changed url is fetched again.
Key or token with bookmarks:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
url | string | Up to 4,096 characters. |
title | string or null | Up to 500 characters. |
description | string or null | Up to 100,000 characters. |
read | boolean | |
archived | boolean | |
ribboned | boolean | |
tags | string[] | Up to 50 items. |
collectionIds | uuid[] | Up to 50 items. |
Example
curl -X PATCH 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
-H "Authorization: Bearer $BKMARK_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/article","title":"Hybrid search with pgvector"}' Response fields (26)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
kindrequired | enum | One of link, note. |
urlrequired | string or null | |
canonicalUrlrequired | string or null | |
titlerequired | string or null | |
descriptionrequired | string or null | |
summaryrequired | string or null | |
siteNamerequired | string or null | |
faviconUrlrequired | string or null | |
imageUrlrequired | string or null | |
sourcerequired | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
sourceDetailrequired | string or null | |
sourceAuthorrequired | string or null | |
fetchStatusrequired | enum | One of pending, ok, failed, gone. |
readAtrequired | string or null | |
archivedAtrequired | string or null | |
ribbonedAtrequired | string or null | |
deletedAtrequired | string or null | |
lastCheckedAtrequired | string or null | |
createdByrequired | uuid or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
tagsrequired | string[] | |
collectionIdsrequired | uuid[] | |
hasSavedCopyrequired | boolean |
delete /v1/bookmarks/{id}
Move to the trash, or delete for good with ?permanent=true.
Key or token with bookmarks:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
permanent | enum | One of true, false. |
idrequired | uuid | In the path. |
Example
curl -X DELETE 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
messagerequired | string |
post /v1/bookmarks/{id}/restore
Restore from the trash (409 if the page was saved again since).
Key or token with bookmarks:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/restore' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (26)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
libraryIdrequired | uuid | |
kindrequired | enum | One of link, note. |
urlrequired | string or null | |
canonicalUrlrequired | string or null | |
titlerequired | string or null | |
descriptionrequired | string or null | |
summaryrequired | string or null | |
siteNamerequired | string or null | |
faviconUrlrequired | string or null | |
imageUrlrequired | string or null | |
sourcerequired | enum | One of web, extension, slack, email, zapier, api, import, shortcut, share_target. |
sourceDetailrequired | string or null | |
sourceAuthorrequired | string or null | |
fetchStatusrequired | enum | One of pending, ok, failed, gone. |
readAtrequired | string or null | |
archivedAtrequired | string or null | |
ribbonedAtrequired | string or null | |
deletedAtrequired | string or null | |
lastCheckedAtrequired | string or null | |
createdByrequired | uuid or null | |
createdAtrequired | string | |
updatedAtrequired | string | |
tagsrequired | string[] | |
collectionIdsrequired | uuid[] | |
hasSavedCopyrequired | boolean |
delete /v1/trash
Empty the trash (trashed bookmarks are also purged after 30 days).
Key or token with bookmarks:write Returns 200
Example
curl -X DELETE 'https://api.bkmark.it/v1/trash' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
updatedrequired | integer | -9007199254740991–9007199254740991. |
post /v1/bookmarks/{id}/refetch
Fetch the page and its saved copy again.
Key or token with bookmarks:write Returns 202
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/refetch' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
messagerequired | string |
post /v1/bookmarks/{id}/check
Check whether the link still works.
Key or token with bookmarks:write Returns 202
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/check' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
messagerequired | string |
get /v1/bookmarks/{id}/saved-copy
The readable copy kept when the page was saved.
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/saved-copy' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (8)
| Name | Type | Description |
|---|---|---|
bookmarkIdrequired | uuid | |
htmlrequired | string | |
textrequired | string | |
wordCountrequired | integer | -9007199254740991–9007199254740991. |
bylinerequired | string or null | |
publishedAtrequired | string or null | |
fetchedAtrequired | string | |
expiresAtrequired | string or null |
get /v1/counts
Bookmark counts for the sidebar views.
Key or token with bookmarks:read Returns 200
Example
curl 'https://api.bkmark.it/v1/counts' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (6)
| Name | Type | Description |
|---|---|---|
inboxrequired | integer | -9007199254740991–9007199254740991. |
libraryrequired | integer | -9007199254740991–9007199254740991. |
readingrequired | integer | -9007199254740991–9007199254740991. |
ribbonedrequired | integer | -9007199254740991–9007199254740991. |
brokenrequired | integer | -9007199254740991–9007199254740991. |
trashrequired | integer | -9007199254740991–9007199254740991. |
get /v1/bookmarks/{id}/suggestions
AI tag and collection suggestions, and the summary.
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/suggestions' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (4)
| Name | Type | Description |
|---|---|---|
tagsrequired | object[] | |
namerequired | string | 1–50 characters. |
confidencerequired | number | 0–1. |
collectionsrequired | object[] | |
idrequired | uuid | |
namerequired | string | |
confidencerequired | number | 0–1. |
summaryrequired | string or null | |
statusrequired | enum | One of pending, ready, unavailable, quota_exceeded. |
post /v1/bookmarks/{id}/suggestions
Accept (apply) or dismiss suggestions; dismissed ones are not suggested again.
Key or token with bookmarks:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
acceptTags | string[] | Default []. Up to 20 items. |
dismissTags | string[] | Default []. Up to 20 items. |
acceptCollections | uuid[] | Default []. Up to 20 items. |
dismissCollections | uuid[] | Default []. Up to 20 items. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/suggestions' \
-H "Authorization: Bearer $BKMARK_TOKEN" \
-H 'Content-Type: application/json' \
-d '{}' Response fields (4)
| Name | Type | Description |
|---|---|---|
tagsrequired | object[] | |
namerequired | string | 1–50 characters. |
confidencerequired | number | 0–1. |
collectionsrequired | object[] | |
idrequired | uuid | |
namerequired | string | |
confidencerequired | number | 0–1. |
summaryrequired | string or null | |
statusrequired | enum | One of pending, ready, unavailable, quota_exceeded. |
post /v1/bookmarks/{id}/opened
Record that the bookmark was opened (reader or original); does not mark it read.
Key or token with bookmarks:read Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Example
curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/opened' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
messagerequired | string |