Docs

API for scripts and agents

Everything you can do on the dashboard, except billing, over plain JSON. Made for a script that keeps a collection in sync, and for an AI agent that curates refs for you from a chat.

Token

Make a token on Account. It looks like srk_xxxxxxxx_… and is shown once. Send it on every request:

Authorization: Bearer srk_xxxxxxxx_your32charsecret

A token has the rights of your account. Make one per client, name it, and revoke it the moment it leaks. Tokens are not for browsers: there is no CORS, on purpose.

Endpoints

Base URL https://shelfref.com/api/v1. The machine-readable spec is at /api/v1/openapi.json; a short brief for language models at /llms.txt.

`GET /me`	Who you are, quota (free, blocks, used, remaining) and the rate limits.
`GET /refs`	Your refs, oldest first. `?state=set\|card\|unset`, `?limit=` (≤200), `?cursor=` from the previous page's `next_cursor`.
`POST /refs`	`{"count": 3, "label": "…"}` mints new refs within your quota. `402` if there is no room.
`GET /refs/{id}`	One ref.
`PATCH /refs/{id}`	Any of `label`, `url`, `title`, `text`, `links`. Absent fields are kept; `null` clears. `links` is an array of up to three `{"label","url"}` or `"Label\|url"` strings.
`POST /refs/{id}/claim`	Claim an unowned ref from a pre-printed pack.

Example

curl -s https://shelfref.com/api/v1/refs \
  -H "Authorization: Bearer $SHELFREF_TOKEN"

curl -s -X PATCH https://shelfref.com/api/v1/refs/k7m2xq4 \
  -H "Authorization: Bearer $SHELFREF_TOKEN" -H "Content-Type: application/json" \
  -d '{"label":"Dune (1965)","url":"http://192.168.1.10/books/dune.epub"}'

curl -s -X PATCH https://shelfref.com/api/v1/refs/k7m2xq4 \
  -H "Authorization: Bearer $SHELFREF_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":null,"title":"Catan","links":["Rules|https://…/catan.pdf","How to play|https://youtu.be/…"]}'

Responses

A ref is returned as:

{"id":"k7m2xq4","url":"http://…","label":"Dune (1965)","title":null,"text":null,"links":[],
 "state":"set","public_url":"https://shelfref.com/t/k7m2xq4","created_at":"…","updated_at":"…"}

Errors are {"error":{"code":"…","message":"…"}} with the HTTP status: 401 bad token, 402 quota or read-only ref, 404 not yours, 409 already owned, 422 invalid field, 429 rate limited.

Rate limits

Per token: 60 requests per minute and 5 000 per day. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the minute window, plus X-RateLimit-Day-Remaining. A 429 carries Retry-After. A whole collection fits in a few requests: list, then patch the rows that changed.

For AI agents

The intended loop: the owner makes a token and pastes it into their agent's configuration. The agent reads /llms.txt and the OpenAPI spec, lists the refs, and from then on can answer "point the Dune token at the new server" or "make cards for all my board games from this spreadsheet" by itself. Nothing is deleted by design, so the worst an agent can do is set a wrong target, which the owner fixes in one edit.

There is no bulk endpoint yet. Patch rows one by one; at 60 per minute a thousand refs take under twenty minutes, and a real collection is usually a few hundred.