Shelfie REST API

A small, friendly API for agents, scripts, the Shelfie CLI, and the MCP server. Bearer-token auth. JSON in, JSON out.

Get a key

Sign in at shelfiebook.com/login.
Go to /settings, scroll to API keys.
Click Create key. Copy the sb_live_... value -- you won't see it again.

Authentication

Send your key as a Bearer token on every request.

Authorization: Bearer sb_live_xxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

GET/api/v1/books

List books in the user's library. Supports `q`, `limit`, `offset`.

Sample request

curl https://shelfiebook.com/api/v1/books?q=pratchett \
  -H "Authorization: Bearer sb_live_..."

Sample response

{ "books": [ ... ], "limit": 100, "offset": 0 }

GET/api/v1/books/:id

Fetch a single book by id.

Sample request

curl https://shelfiebook.com/api/v1/books/<id> \
  -H "Authorization: Bearer sb_live_..."

Sample response

{ "id": "...", "title": "...", ... }

POST/api/v1/books

Add a book. Dedupes by normalized title + author.

Sample request

curl -X POST https://shelfiebook.com/api/v1/books \
  -H "Authorization: Bearer sb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Project Hail Mary","author":"Andy Weir"}'

Sample response

{ "id": "...", "title": "...", ... }

PATCH/api/v1/books/:id

Update read_status, rating, notes, lent_to, lent_at, wishlist, title, author, subjects, etc.

Sample request

curl -X PATCH https://shelfiebook.com/api/v1/books/<id> \
  -H "Authorization: Bearer sb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"read_status":"read","rating":5}'

Sample response

{ "ok": true }

DELETE/api/v1/books/:id

Soft-delete a book. Restorable from /library/trash for the user.

Sample request

curl -X DELETE https://shelfiebook.com/api/v1/books/<id> \
  -H "Authorization: Bearer sb_live_..."

Sample response

{ "ok": true }

Rate limits

200 requests per minute per key.
Cap may rise on Bibliophile and Collector tiers.
If you hit it, you'll get a 429. Back off and retry.

SDKs

MCP server for compatible apps: npx -y shelfie-mcp (see /docs/agents).
CLI for terminal lovers: npx -y shelfie-cli login, then shelfie list pratchett.
cURL works fine. The API is intentionally small.