Tokens and limits

Keepsake offers two ways in for your own tools:

• The REST API saves bookmarks, edits and deletes them, and reads your library, its archives, its tags, and search.
• The MCP server lets an assistant such as Claude search and read your library through tools that change nothing.

Both are part of every plan.

Make a token

1. Open Settings, then API tokens.
2. Name the token for where it will live, such as a laptop script or a shortcut, and create it.
3. Copy the token now, since Keepsake shows it once and stores only a fingerprint of it.

A token acts as you, with the same access to your library that you have. Keep each one in one place, and delete it under API tokens the moment you stop using it. The list shows when each token was last used, so a forgotten one is easy to spot.

Keepsake caps how many tokens one account keeps, and the tokens page says so when you reach the cap.

Send a request

Every request carries the token as a bearer credential:

curl https://app.keepsake.run/api/v1/bookmarks \
  -H "Authorization: Bearer $KEEPSAKE_TOKEN"

Requests and answers are JSON, and times are ISO 8601 strings in UTC. The reference lists every route, its parameters, and every field of its answer, generated from the API's own OpenAPI document. The document itself is published at https://app.keepsake.run/api/v1/openapi.json for tools that generate clients from it.

Save from a script

curl https://app.keepsake.run/api/v1/bookmarks \
  -H "Authorization: Bearer $KEEPSAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/post", "tags": ["reading"], "readLater": true}'

The bookmark is saved at once, and its page is archived a moment later. Send the page's HTML as html to archive the copy you already have, such as one behind a sign-in, instead of having Keepsake fetch the address.

Errors

A refused request answers with an HTTP status and a JSON body whose message says what went wrong in words meant for a person:

Status	Meaning
400	The request was not valid, such as a missing field or a value out of range.
401	The token is missing, mistyped, or deleted.
404	The bookmark does not exist or belongs to someone else.
413	The request body is too large.
429	Too many requests in a short time; wait a minute and try again.

Rate limits

Requests made with a token share one rate limit per account, counted over each minute. A script that saves or reads in bulk should pause and retry when it receives a 429.