HTTP API

Resolver API reference

Versioned HTTP endpoints for searching, paging and resolving canonical book works with source-labelled access and rights context.

Contract

LibreLeaf exposes a read-only JSON API at https://libreleaf-books.netlify.app/api/v1. It requires no API key. GET and OPTIONS are supported, CORS is enabled, and successful responses include X-LibreLeaf-API-Version: 1.

The API returns canonical works, not a flat list of interchangeable files. Each work retains sourceRecords and offers so clients can distinguish a download from a read, listen, borrow or preview route. Compatible fields can be added during v1; existing meanings are not changed without a new version.

  • GET /api/v1/search — search six catalogues and page them independently.
  • GET /api/v1/works/{workId} — refresh one stable LibreLeaf work identity.
  • GET /api/v1/editions?workKey=/works/OL…W — inspect a bounded Open Library edition set.
  • GET /api/v1/lists — read independent live-list feed states.

Search and paging

Search accepts q, by, region and cursor. by is q, title, author or subject. region is GB, US or GLOBAL and selects the rights explanation shown with an offer; it is not geolocation or legal clearance.

Every source advances independently. Pass nextCursor back unchanged with the same q, by and region until nextCursor is null. A timeout, stale fallback or deferred source does not advance that source position, so later requests can retry it. There is no permanent 96-result stop.

curl 'https://libreleaf-books.netlify.app/api/v1/search?q=frankenstein&by=title&region=GB'

Work and offer fields

  • canonicalId and canonicalUrl identify the work across the web UI, API and MCP server.
  • sourceRecords retain each upstream record ID, details URL, language, country metadata and its own offers.
  • offers retain source, access, label, URL, optional format/language and edition-specific rights metadata.
  • why, clusterConfidence and ranking explain merging and Reciprocal Rank Fusion rather than hiding a relevance score.
  • sources, sourceHealth and searchTiming report bounded operational state without returning reader queries or raw upstream errors.

Errors and client behaviour

Invalid input returns 400. Missing works or editions return 404. Temporary catalogue failure can return 429, 502, 503 or 504. An all-source search failure includes an unchanged cursor and source diagnostics, allowing a client to retry safely.

Cache complete responses by query, search mode, region and cursor. Cache partial responses briefly, use exponential backoff, and do not crawl every page speculatively. LibreLeaf aggregates public services with their own limits and is not a bulk metadata mirror.

const page = await fetch(
  "https://libreleaf-books.netlify.app/api/v1/search?q=frankenstein&by=title&region=GB"
).then((response) => response.json());

if (page.nextCursor) {
  const next = new URL("https://libreleaf-books.netlify.app/api/v1/search");
  next.searchParams.set("q", "frankenstein");
  next.searchParams.set("by", "title");
  next.searchParams.set("region", "GB");
  next.searchParams.set("cursor", page.nextCursor);
  console.log(await fetch(next).then((response) => response.json()));
}

References