How to use the LibreLeaf public API

Search and page LibreLeaf's read-only JSON API while preserving work identity, provenance, access types, and rights context.

Make a bounded search

Send a GET request to /api/v1/search with q for the query. The by parameter can select a broad query, title, author, or subject, and region accepts GB, US, or GLOBAL. Encode parameter values and keep the same q, by, and region for every page in one result sequence.

For example, /api/v1/search?q=frankenstein&by=title&region=GB returns JSON containing books, source counts and status, a rights context, and an opaque nextCursor when more upstream pages may exist. Source timeouts or rate limits can produce useful partial results; inspect the source-status object instead of treating a smaller page as definitive exhaustion.

Page with the opaque cursor

  1. Read nextCursor from the response. If it is null, the participating sources are known to be exhausted for that query.
  2. If it is present, pass it unchanged as cursor on the next request with the original search parameters.
  3. Append new works by stable LibreLeaf ID rather than by array position. A later page can carry records from sources that advance independently.
  4. On a transient source failure, retain the returned cursor and retry with backoff. Do not decode or edit its internal state.

Render offers without changing their meaning

Each canonical book can contain several sourceRecords and offers. Display source, access type, format, details URL, and rights note together. A preview is not a download, a borrow route is not permanent ownership, and source-assessed public domain in the US is not a global determination.

Use why and clusterConfidence to explain ranking or merging. Stable work IDs can support saved items and work permalinks. For Open Library works, the editions endpoint can retrieve edition-level records with its own pagination; do not silently substitute a different translation, abridgement, or publication just because the titles resemble each other.

The service is read-only and aggregates upstream catalogues. Cache responsibly, identify your application where documented, and design for partial upstream availability.