Skip to content
bkmark.it
Docs menu

API reference

Saved searches

A query and filters, kept up to date as you save more.

get /v1/saved-searches

Saved searches in display order.

Key or token with bookmarks:read Returns 200

Example

curl 'https://api.bkmark.it/v1/saved-searches' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (1)
Response fields
NameTypeDescription
datarequiredobject[]
idrequireduuid
namerequiredstring
queryrequiredstring
filtersrequiredobject
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadboolean
archivedboolean
ribbonedboolean
brokenboolean
positionrequiredinteger-9007199254740991–9007199254740991.
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring

post /v1/saved-searches

Save a search.

Key or token with bookmarks:write Returns 201

Body

Body fields
NameTypeDescription
namerequiredstring1–100 characters.
querystringDefault "". Up to 500 characters.
filtersobjectDefault {}.
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadboolean
archivedboolean
ribbonedboolean
brokenboolean
positioninteger0–9007199254740991.

Example

curl -X POST 'https://api.bkmark.it/v1/saved-searches' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Hybrid search with pgvector"}'
Response fields (8)
Response fields
NameTypeDescription
idrequireduuid
namerequiredstring
queryrequiredstring
filtersrequiredobject
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadboolean
archivedboolean
ribbonedboolean
brokenboolean
positionrequiredinteger-9007199254740991–9007199254740991.
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring

patch /v1/saved-searches/{id}

Edit a saved search.

Key or token with bookmarks:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
namestring1–100 characters.
querystringUp to 500 characters.
filtersobject
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadboolean
archivedboolean
ribbonedboolean
brokenboolean
positioninteger0–9007199254740991.

Example

curl -X PATCH 'https://api.bkmark.it/v1/saved-searches/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Hybrid search with pgvector","query":"text"}'
Response fields (8)
Response fields
NameTypeDescription
idrequireduuid
namerequiredstring
queryrequiredstring
filtersrequiredobject
collectionuuid
tagstring1–50 characters.
kindenumOne of link, note.
sourceenumOne of web, extension, slack, email, zapier, api, import, shortcut, share_target.
unreadboolean
archivedboolean
ribbonedboolean
brokenboolean
positionrequiredinteger-9007199254740991–9007199254740991.
createdByrequireduuid or null
createdAtrequiredstring
updatedAtrequiredstring

delete /v1/saved-searches/{id}

Delete a saved search.

Key or token with bookmarks:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

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

get /v1/saved-searches/{id}/results

Run a saved search in its library (no query text = its filters, newest first).

Key or token with bookmarks:read Returns 200

Parameters

Parameters
NameTypeDescription
cursorstringUp to 300 characters.
limitintegerDefault 20. 1–50.
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/saved-searches/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/results' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (4)
Response fields
NameTypeDescription
resultsrequiredobject[]
bookmarkrequiredobject
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
libraryIdrequireduuid
scorerequirednumber
matchedInrequiredenumOne of title, url, description, saved_copy, highlight, note, meaning.
passagerequiredobject or null
textrequiredstring
marksrequiredinteger[][]
nextCursorrequiredstring or null
moderequiredenumOne of hybrid, keyword.
tookMsrequirednumber