API reference
Save, organise and search a library from your own code. Everything the apps do goes through this API.
The API speaks JSON over HTTPS at https://api.bkmark.it. Routes live under /v1. Timestamps are ISO 8601 strings in UTC. The machine-readable
description is at https://api.bkmark.it/v1/openapi.json (OpenAPI 3, version 1.0.0).
curl 'https://api.bkmark.it/v1/search?q=rank%20fusion' \
-H "Authorization: Bearer $BKMARK_TOKEN" Authentication
Every request carries one credential. Both kinds below act for one person and are limited by scopes.
API keys
For your own scripts, Shortcuts and servers. Create one under Settings → API and webhooks (Pro), pick its scopes, and optionally lock it to one library. The key
(bk_live_…) is shown once. Send it as Authorization: Bearer bk_live_… or X-API-Key: bk_live_…. Revoking a key stops it on the next request.
OAuth 2
For apps that act on someone else’s behalf. bkmark.it is an OAuth 2 authorization server using the authorization code grant.
- Send the person to
https://api.bkmark.it/oauth/authorizewithresponse_type=code, yourclient_id,redirect_uri,scopeandstate. Public clients (apps that can’t keep a secret) must add PKCE:code_challengewithcode_challenge_method=S256. - They see a consent screen listing your scopes, and can lock the grant to one library.
- Exchange the
code(valid for 60 seconds, once) atPOST /oauth/token, form-encoded, withgrant_type=authorization_code, the sameredirect_uri, and yourclient_secretorcode_verifier. - Access tokens last an hour. Ask for
offline_accessto also get a refresh token; it lasts 60 days and is replaced on every use. Using an old refresh token again revokes the whole grant.
POST /oauth/revoke revokes a token, and GET /oauth/token-info tells you who a token or key belongs to. To register an app, write to support@bkmark.it.
Scopes
| Scope | Allows |
|---|---|
bookmarks:read | See your bookmarks and their saved copies |
bookmarks:write | Save, edit and delete bookmarks |
collections:read | See your collections |
collections:write | Create, change and delete collections |
tags:read | See your tags |
tags:write | Create, change and delete tags |
highlights:read | See your highlights and notes |
highlights:write | Add, change and delete highlights and notes |
offline_access | Stay connected until you disconnect it |
A :write scope doesn’t include the matching :read; ask for both if you need both. Account, security and billing routes aren’t available to keys or tokens at all.
Libraries
Every bookmark, collection and tag belongs to a library: your personal one, or a team library you’re a member of. Requests use your personal library unless you send X-Library-Id: <id> (or ?library=<id>). GET /v1/libraries lists the ones you can use. A key or grant locked to a library
always uses that one. Libraries you can’t see answer 404, so their existence isn’t revealed.
Errors
Every error has the same shape, with a stable error code for programs and a message for people:
{ "error": "plan_required", "message": "API keys are part of Pro.", "statusCode": 402 } | Status | Code | Meaning |
|---|---|---|
| 400 | validation_error | The request didn’t match the schema; the message says which field. |
| 401 | unauthorized | No credential, or the key or token is wrong, expired or revoked. |
| 402 | plan_required | The library’s plan doesn’t include this (API keys and webhooks need Pro; Free gets one Shortcut key that can only save). |
| 403 | forbidden | The token or key lacks the scope, or your role can’t do this. |
| 404 | not_found | No such thing, or it’s in a library you can’t see. |
| 409 | conflict | It clashes with something that exists, such as a tag name. |
| 429 | rate_limited | Too many requests. Wait the number of seconds in Retry-After. |
Pagination and limits
Lists return { "data": [...], "nextCursor": "..." }. Pass nextCursor back as cursor for the next page, until it is null. limit is 1 to 100 (default 50). Requests are limited per key or token, 300 a minute by default; a 429 carries Retry-After.
Webhooks and live events
To hear about changes, subscribe a URL with webhooks (signed, retried, Pro): the webhooks guide covers payloads and signature checks. A browser or long-running process can also listen on server-sent events.