Skip to content
bkmark.it
Docs menu

API reference

Highlights and notes

Highlights anchor to the saved copy. Each person has a private note per bookmark; team bookmarks also have one shared note.

get /v1/bookmarks/{id}/highlights

Your highlights and the library-visible ones, in reading order.

Key or token with highlights:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/highlights' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (1)
Response fields
NameTypeDescription
datarequiredobject[]
idrequireduuid
bookmarkIdrequireduuid
authorIdrequireduuid or null
visibilityrequiredenumOne of private, library.
textrequiredstring
prefixrequiredstring
suffixrequiredstring
startOffsetrequiredinteger-9007199254740991–9007199254740991.
endOffsetrequiredinteger-9007199254740991–9007199254740991.
noterequiredstring or null
colorrequiredenumOne of yellow, green, blue, pink, purple.
createdAtrequiredstring
updatedAtrequiredstring

post /v1/bookmarks/{id}/highlights

Highlight a passage of the saved copy.

Key or token with highlights:write Returns 201

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
textrequiredstring1–5,000 characters.
prefixstringDefault "". Up to 64 characters.
suffixstringDefault "". Up to 64 characters.
startOffsetrequiredinteger0–9007199254740991.
endOffsetrequiredinteger1–9007199254740991.
notestring or nullUp to 10,000 characters.
colorenumOne of yellow, green, blue, pink, purple. Default "yellow".
visibilityenumOne of private, library. Default "private".

Example

curl -X POST 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/highlights' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"text","startOffset":1,"endOffset":1}'
Response fields (13)
Response fields
NameTypeDescription
idrequireduuid
bookmarkIdrequireduuid
authorIdrequireduuid or null
visibilityrequiredenumOne of private, library.
textrequiredstring
prefixrequiredstring
suffixrequiredstring
startOffsetrequiredinteger-9007199254740991–9007199254740991.
endOffsetrequiredinteger-9007199254740991–9007199254740991.
noterequiredstring or null
colorrequiredenumOne of yellow, green, blue, pink, purple.
createdAtrequiredstring
updatedAtrequiredstring

patch /v1/highlights/{id}

Edit your highlight’s note, colour or visibility.

Key or token with highlights:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
notestring or nullUp to 10,000 characters.
colorenumOne of yellow, green, blue, pink, purple.
visibilityenumOne of private, library.

Example

curl -X PATCH 'https://api.bkmark.it/v1/highlights/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"note":"text","color":"yellow"}'
Response fields (13)
Response fields
NameTypeDescription
idrequireduuid
bookmarkIdrequireduuid
authorIdrequireduuid or null
visibilityrequiredenumOne of private, library.
textrequiredstring
prefixrequiredstring
suffixrequiredstring
startOffsetrequiredinteger-9007199254740991–9007199254740991.
endOffsetrequiredinteger-9007199254740991–9007199254740991.
noterequiredstring or null
colorrequiredenumOne of yellow, green, blue, pink, purple.
createdAtrequiredstring
updatedAtrequiredstring

delete /v1/highlights/{id}

Delete your highlight.

Key or token with highlights:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

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

get /v1/bookmarks/{id}/notes/me

Your private note on a bookmark (empty body if none).

Key or token with highlights:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/notes/me' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (3)
Response fields
NameTypeDescription
bookmarkIdrequireduuid
bodyrequiredstring
updatedAtrequiredstring or null

put /v1/bookmarks/{id}/notes/me

Write your private note (an empty body deletes it).

Key or token with highlights:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
bodyrequiredstringUp to 100,000 characters.

Example

curl -X PUT 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/notes/me' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"body":"text"}'
Response fields (3)
Response fields
NameTypeDescription
bookmarkIdrequireduuid
bodyrequiredstring
updatedAtrequiredstring or null

get /v1/bookmarks/{id}/notes/shared

The team’s shared note on a bookmark (team libraries).

Key or token with highlights:read Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Example

curl 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/notes/shared' \
  -H "Authorization: Bearer $BKMARK_TOKEN"
Response fields (3)
Response fields
NameTypeDescription
bookmarkIdrequireduuid
bodyrequiredstring
updatedAtrequiredstring or null

put /v1/bookmarks/{id}/notes/shared

Write the team’s shared note (members and admins; an empty body deletes it).

Key or token with highlights:write Returns 200

Parameters

Parameters
NameTypeDescription
idrequireduuidIn the path.

Body

Body fields
NameTypeDescription
bodyrequiredstringUp to 100,000 characters.

Example

curl -X PUT 'https://api.bkmark.it/v1/bookmarks/0c9d3a52-6f1e-4b8a-9d2f-5e7a1b3c4d6e/notes/shared' \
  -H "Authorization: Bearer $BKMARK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"body":"text"}'
Response fields (3)
Response fields
NameTypeDescription
bookmarkIdrequireduuid
bodyrequiredstring
updatedAtrequiredstring or null