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
- post /v1/bookmarks/{id}/highlights
- patch /v1/highlights/{id}
- delete /v1/highlights/{id}
- get /v1/bookmarks/{id}/notes/me
- put /v1/bookmarks/{id}/notes/me
- get /v1/bookmarks/{id}/notes/shared
- put /v1/bookmarks/{id}/notes/shared
get /v1/bookmarks/{id}/highlights
Your highlights and the library-visible ones, in reading order.
Key or token with highlights: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/highlights' \
-H "Authorization: Bearer $BKMARK_TOKEN" Response fields (1)
| Name | Type | Description |
|---|---|---|
datarequired | object[] | |
idrequired | uuid | |
bookmarkIdrequired | uuid | |
authorIdrequired | uuid or null | |
visibilityrequired | enum | One of private, library. |
textrequired | string | |
prefixrequired | string | |
suffixrequired | string | |
startOffsetrequired | integer | -9007199254740991–9007199254740991. |
endOffsetrequired | integer | -9007199254740991–9007199254740991. |
noterequired | string or null | |
colorrequired | enum | One of yellow, green, blue, pink, purple. |
createdAtrequired | string | |
updatedAtrequired | string |
post /v1/bookmarks/{id}/highlights
Highlight a passage of the saved copy.
Key or token with highlights:write Returns 201
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
textrequired | string | 1–5,000 characters. |
prefix | string | Default "". Up to 64 characters. |
suffix | string | Default "". Up to 64 characters. |
startOffsetrequired | integer | 0–9007199254740991. |
endOffsetrequired | integer | 1–9007199254740991. |
note | string or null | Up to 10,000 characters. |
color | enum | One of yellow, green, blue, pink, purple. Default "yellow". |
visibility | enum | One 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)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
bookmarkIdrequired | uuid | |
authorIdrequired | uuid or null | |
visibilityrequired | enum | One of private, library. |
textrequired | string | |
prefixrequired | string | |
suffixrequired | string | |
startOffsetrequired | integer | -9007199254740991–9007199254740991. |
endOffsetrequired | integer | -9007199254740991–9007199254740991. |
noterequired | string or null | |
colorrequired | enum | One of yellow, green, blue, pink, purple. |
createdAtrequired | string | |
updatedAtrequired | string |
patch /v1/highlights/{id}
Edit your highlight’s note, colour or visibility.
Key or token with highlights:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
note | string or null | Up to 10,000 characters. |
color | enum | One of yellow, green, blue, pink, purple. |
visibility | enum | One 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)
| Name | Type | Description |
|---|---|---|
idrequired | uuid | |
bookmarkIdrequired | uuid | |
authorIdrequired | uuid or null | |
visibilityrequired | enum | One of private, library. |
textrequired | string | |
prefixrequired | string | |
suffixrequired | string | |
startOffsetrequired | integer | -9007199254740991–9007199254740991. |
endOffsetrequired | integer | -9007199254740991–9007199254740991. |
noterequired | string or null | |
colorrequired | enum | One of yellow, green, blue, pink, purple. |
createdAtrequired | string | |
updatedAtrequired | string |
delete /v1/highlights/{id}
Delete your highlight.
Key or token with highlights:write Returns 200
Parameters
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In 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)
| Name | Type | Description |
|---|---|---|
messagerequired | string |
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
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In 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)
| Name | Type | Description |
|---|---|---|
bookmarkIdrequired | uuid | |
bodyrequired | string | |
updatedAtrequired | string 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
| Name | Type | Description |
|---|---|---|
idrequired | uuid | In the path. |
Body
| Name | Type | Description |
|---|---|---|
bodyrequired | string | Up 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)
| Name | Type | Description |
|---|---|---|
bookmarkIdrequired | uuid | |
bodyrequired | string | |
updatedAtrequired | string or null |