ReadingRate for Developers
Book intelligence — difficulty scores, literary regard, reading-time estimates — for your apps and agents. Catalog reads are free and need no API key. Personal reading data flows through the MCP server behind OAuth.
Public API
Two read-only endpoints, no authentication, CORS-open. The contract is the OpenAPI 3.1 spec at /openapi.json.
Get one book
curl https://readingrate.com/api/v1/books/blood-meridianReturns title, authors, difficulty (0–100 composite with per-dimension breakdown), literary regard, word count, reading time, genres, and edition facts. Unknown slugs are a real HTTP 404.
Search the catalog
curl "https://readingrate.com/api/v1/search?q=in+search+of+lost+time&limit=5"Fuzzy title/author search; results carry the slugs to feed into the book endpoint. Start at /api/v1 for a machine-readable index.
MCP server
The Model Context Protocol server at https://mcp.readingrate.com/mcp serves the same book intelligence as tools, plus — after OAuth sign-in — personal tools: log reading sessions, save quotes, query your own analytics. Install guide: mcp.readingrate.com/install.
Authorization is OAuth 2.0 with PKCE and dynamic client registration. Discovery documents: authorization server metadata · protected resource metadata (RFC 9728).
| Scope | Grants |
|---|---|
catalog:read | Public book intelligence: difficulty, regard, metadata, awards |
user:read | The signed-in reader's library, logs, quotes, analytics |
user:write | Log reading, save quotes, update the reader's library |
Content for agents
- /llms.txt — site guide with when-to-use guidance; /llms-full.txt — full book data
- Markdown negotiation: send
Accept: text/markdownto/or any/books/{slug}page and get markdown back - Real 404s: unknown paths return HTTP 404 with a markdown body, so a 200 means the page exists
- /sitemap.xml — every public page
Rate limits
The public API allows approximately 120 requests per minute per IP. Every /api/v1 response carries the standard fields — RateLimit-Policy: 120;w=60, plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset — so agents can self-throttle in real time. Past the limit you get a 429 with Retry-After in seconds. Counters are approximate ("about 120"): enforcement is per-IP with an eventually-consistent store, tuned to stop accidental hammering, not to shave legitimate use.
Versioning and deprecation
The API is versioned in the URL path (/api/v1). Within a version, changes are additive only — new fields may appear, existing fields keep their names, types, and meaning. Breaking changes ship as a new path (/api/v2), never in place.
If a version is ever retired: it keeps working for at least six months after its replacement ships, its responses carry Deprecation and Sunset headers with the removal date for that whole period, and the timeline is announced here and in llms.txt. No version has ever been deprecated; there is currently no sunset planned for v1.
Fair use
The read endpoints are a free tier, self-serve, no sign-up. Cache responses (they carry cache headers), keep request rates polite, and attribute scores to ReadingRate with a link to the book page. For anything heavier, talk to us.