Skip to content
bkmark.it
Docs menu

API reference

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

Copy a bookmark from the current library into another one (e.g. a team).

Key or token with bookmarks:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
libraryIdrequireduuid
includeMyHighlightsbooleanDefault false.
matchCollectionsbooleanDefault false.

Example

curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/share-to-library' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"libraryId":"0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e"}'
Response fields (4)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
duplicaterequiredboolean
highlightsCopiedrequiredinteger-9007199254740991–9007199254740991.

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

Body fields
NameTypeDescription
kindenumOne of link, note. Default "link".
urlstringUp to 4,096 characters.
titlestringUp to 500 characters.
descriptionstringUp to 100,000 characters.
tagsstring[]Up to 50 items.
collectionIdsuuid[]Up to 50 items.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target. Default "api".
sourceDetailstringUp to 200 characters.
textstringUp 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)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean
duplicaterequiredboolean

get /v1/bookmarks

List bookmarks with filters and a cursor (deleted=true lists the trash).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadenumOne of true, false.
archivedenumOne of true, false.
ribbonedenumOne of true, false.
brokenenumOne of true, false.
deletedenumOne of true, false.
savedAftertimestamp
savedBeforetimestamp
sortenumOne of newest, oldest. Default "newest".
cursorstringUp to 300 characters.
limitintegerDefault 50. 1–100.

Example

curl 'https://api.bkmark.it/v1/bookmarks' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (2)
Response fields
NameTypeDescription
datarequiredobject[]
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean
nextCursorrequiredstring or null

post /v1/bookmarks/bulk

Apply one action to up to 500 bookmarks.

Key or token with bookmarks:write Returns 200

Body

Body fields
NameTypeDescription
actionrequiredenumOne of archive, unarchive, read, unread, ribbon, unribbon, delete, restore, purge, tag, untag, add_to_collection, remove_from_collection.
idsrequireduuid[]Up to 500 items.
tagsstring[]Up to 20 items.
collectionIduuid

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)
Response fields
NameTypeDescription
updatedrequiredinteger-9007199254740991–9007199254740991.

get /v1/bookmarks/{id}

One bookmark (trashed ones included).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (26)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean

patch /v1/bookmarks/{id}

Edit a bookmark; a changed url is fetched again.

Key or token with bookmarks:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
urlstringUp to 4,096 characters.
titlestring or nullUp to 500 characters.
descriptionstring or nullUp to 100,000 characters.
readboolean
archivedboolean
ribbonedboolean
tagsstring[]Up to 50 items.
collectionIdsuuid[]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)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean

delete /v1/bookmarks/{id}

Move to the trash, or delete for good with ?permanent=true.

Key or token with bookmarks:write Returns 200

Parameters

Parameters
NameTypeDescription
permanentenumOne of true, false.
idrequireduuidIn 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)
Response fields
NameTypeDescription
messagerequiredstring

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

Parameters
NameTypeDescription
idrequireduuidIn 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)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean

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)
Response fields
NameTypeDescription
updatedrequiredinteger-9007199254740991–9007199254740991.

post /v1/bookmarks/{id}/refetch

Fetch the page and its saved copy again.

Key or token with bookmarks:write Returns 202

Parameters

Parameters
NameTypeDescription
idrequireduuidIn 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)
Response fields
NameTypeDescription
messagerequiredstring

post /v1/bookmarks/{id}/check

Check whether the link still works.

Key or token with bookmarks:write Returns 202

Parameters

Parameters
NameTypeDescription
idrequireduuidIn 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)
Response fields
NameTypeDescription
messagerequiredstring

get /v1/bookmarks/{id}/saved-copy

The readable copy kept when the page was saved.

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn 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)
Response fields
NameTypeDescription
bookmarkIdrequireduuid
htmlrequiredstring
textrequiredstring
wordCountrequiredinteger-9007199254740991–9007199254740991.
bylinerequiredstring or null
publishedAtrequiredstring or null
fetchedAtrequiredstring
expiresAtrequiredstring or null

post /v1/bookmarks/{id}/tags

Add tags (created if new).

Key or token with tags:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
namesrequiredstring[]Up to 50 items.

Example

curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/tags' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"names":["Hybrid search with pgvector"]}'
Response fields (26)
Response fields
NameTypeDescription
idrequireduuid
libraryIdrequireduuid
kindrequiredenumOne of link, note.
urlrequiredstring or null
canonicalUrlrequiredstring or null
titlerequiredstring or null
descriptionrequiredstring or null
summaryrequiredstring or null
siteNamerequiredstring or null
faviconUrlrequiredstring or null
imageUrlrequiredstring or null
sourcerequiredenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
sourceDetailrequiredstring or null
sourceAuthorrequiredstring or null
fetchStatusrequiredenumOne of pending, ok, failed, gone.
readAtrequiredstring or null
archivedAtrequiredstring or null
ribbonedAtrequiredstring or null
deletedAtrequiredstring or null
lastCheckedAtrequiredstring or null
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring
tagsrequiredstring[]
collectionIdsrequireduuid[]
hasSavedCopyrequiredboolean

delete /v1/bookmarks/{id}/tags/{tagId}

Remove a tag from a bookmark.

Key or token with tags:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.
tagIdrequireduuidIn the path.

Example

curl -X DELETE 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/tags/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (1)
Response fields
NameTypeDescription
messagerequiredstring

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)
Response fields
NameTypeDescription
inboxrequiredinteger-9007199254740991–9007199254740991.
libraryrequiredinteger-9007199254740991–9007199254740991.
readingrequiredinteger-9007199254740991–9007199254740991.
ribbonedrequiredinteger-9007199254740991–9007199254740991.
brokenrequiredinteger-9007199254740991–9007199254740991.
trashrequiredinteger-9007199254740991–9007199254740991.

get /v1/bookmarks/{id}/suggestions

AI tag and collection suggestions, and the summary.

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/suggestions' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (4)
Response fields
NameTypeDescription
tagsrequiredobject[]
namerequiredstring1–50 characters.
confidencerequirednumber0–1.
collectionsrequiredobject[]
idrequireduuid
namerequiredstring
confidencerequirednumber0–1.
summaryrequiredstring or null
statusrequiredenumOne 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

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
acceptTagsstring[]Default []. Up to 20 items.
dismissTagsstring[]Default []. Up to 20 items.
acceptCollectionsuuid[]Default []. Up to 20 items.
dismissCollectionsuuid[]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)
Response fields
NameTypeDescription
tagsrequiredobject[]
namerequiredstring1–50 characters.
confidencerequirednumber0–1.
collectionsrequiredobject[]
idrequireduuid
namerequiredstring
confidencerequirednumber0–1.
summaryrequiredstring or null
statusrequiredenumOne 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

Parameters
NameTypeDescription
idrequireduuidIn 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)
Response fields
NameTypeDescription
messagerequiredstring