Skip to content
bkmark.it
Docs menu

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.

  1. Send the person to https://api.bkmark.it/oauth/authorize with response_type=code, your client_id, redirect_uri, scope and state. Public clients (apps that can’t keep a secret) must add PKCE: code_challenge with code_challenge_method=S256.
  2. They see a consent screen listing your scopes, and can lock the grant to one library.
  3. Exchange the code (valid for 60 seconds, once) at POST /oauth/token, form-encoded, with grant_type=authorization_code, the same redirect_uri, and your client_secret or code_verifier.
  4. Access tokens last an hour. Ask for offline_access to 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

ScopeAllows
bookmarks:readSee your bookmarks and their saved copies
bookmarks:writeSave, edit and delete bookmarks
collections:readSee your collections
collections:writeCreate, change and delete collections
tags:readSee your tags
tags:writeCreate, change and delete tags
highlights:readSee your highlights and notes
highlights:writeAdd, change and delete highlights and notes
offline_accessStay 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 }
StatusCodeMeaning
400validation_errorThe request didn’t match the schema; the message says which field.
401unauthorizedNo credential, or the key or token is wrong, expired or revoked.
402plan_requiredThe library’s plan doesn’t include this (API keys and webhooks need Pro; Free gets one Shortcut key that can only save).
403forbiddenThe token or key lacks the scope, or your role can’t do this.
404not_foundNo such thing, or it’s in a library you can’t see.
409conflictIt clashes with something that exists, such as a tag name.
429rate_limitedToo 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.