ReadingList API Documentation

Public REST API · v1 · CORS open · No auth required (free tier)

What this API serves

ReadingList exposes a free, public, read-only REST API over its source-cited K-12 reading-list dataset. Six endpoints serve book metadata, curriculum and state reading lists, and grade-appropriate recommendations. The API is designed for AI tutors integrating grade-level book suggestions, ed-tech apps building reading-companion features, library systems doing collection development, and researchers studying assigned reading.

Every response references the classification standard — the public 6-dimension methodology that documents how each field is sourced and verified.

Authentication & rate limits

Free tier (current). No authentication required. Recommended client-side rate limit: ≤100 requests per day per IP. Server-side rate limit enforcement is not yet live; please honor the cap so the free tier remains available to everyone.

Paid tiers (coming). Pro tier (1,000/day) and Enterprise tier (10,000+/day with SLA) ship alongside auth in a future release. Token-based authentication via Bearer headers; pricing will be published on the pricing page when tiers go live.

Rate limit headers appear on every response: X-RateLimit-Tier, X-RateLimit-Daily-Limit, X-RateLimit-Pro-Tier-Daily, X-RateLimit-Enterprise-Tier-Daily.

Conventions

  • All endpoints respond with application/json. No XML, no HTML, no GraphQL.
  • CORS is open (Access-Control-Allow-Origin: *) so the API can be called directly from browser-side code.
  • Responses are edge-cached; Cache-Control headers indicate freshness (typically 1 hour browser, 1 day edge).
  • Errors return a JSON envelope with { error, message, documentation_url } plus the appropriate HTTP status (400 / 404 / 500).
  • Slugs are lowercase, hyphenated, and stable. The slug for a book / curriculum / state / grade matches its canonical page URL on the site.
  • Field semantics follow the classification standard. When a book has no data for a dimension, the field is empty or null — never fabricated.

Endpoints

Six endpoints. The newest (and most flexible) is /api/v1/recommend.

GET /api/v1/recommend

Grade-appropriate book recommendations with optional filters

Returns up to 50 books matching grade × optional curriculum × optional state × optional Lexile range × optional banned-state exclusion. Designed for AI tutors integrating grade-level reading suggestions.

Parameters

graderequired
Grade slug — K, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
stateoptional
State slug (e.g. california, texas, new-york). Filters to books cited in that state's ELA framework or DOE list (national curricula included).
curriculumoptional
Curriculum slug (e.g. common-core, ap-literature, ib-dp-english-literature, cambridge-igcse-english-lit).
lexile_minoptional
Minimum Lexile measure (non-negative integer). Books below this filtered out.
lexile_maxoptional
Maximum Lexile measure (non-negative integer). Books above this filtered out.
exclude_bannedoptional
Set to 'true' to exclude books with any documented banning or removal record per PEN America's Index.
limitoptional
Maximum books returned. Default 10, max 50. Higher values silently capped at 50.

Example

curl 'https://readinglist.school/api/v1/recommend?grade=9&curriculum=common-core&exclude_banned=true&limit=5'

Response shape

{
  "version": "v1",
  "generated_at": "2026-04-30T...",
  "filters": { "grade": "9", "curriculum": "common-core", "state": null,
               "lexile_min": null, "lexile_max": null,
               "exclude_banned": true, "limit": 5 },
  "methodology_url": "https://readinglist.school/standard",
  "methodology_summary": "Recommendations derive from the 6-dimension classification standard...",
  "rate_limit": { "tier": "free", "daily_limit": 100, ... },
  "count": 5,
  "books": [
    {
      "slug": "lord-of-the-flies",
      "title": "Lord of the Flies",
      "author": "William Golding",
      "isbn13": "9780399501487",
      "lexile": 770,
      "lexile_range_min": 770,
      "lexile_range_max": 770,
      "grade_min": 9,
      "grade_max": 12,
      "themes": ["civilization", "human nature", "morality"],
      "banned_in_states": [],
      "permalink": "https://readinglist.school/book/lord-of-the-flies",
      "api_url": "https://readinglist.school/api/book/lord-of-the-flies"
    },
    { ... }
  ]
}

GET /api/book/{slug}

Single-book detail with all assignments + sources

Returns the full book record (title, author, ISBNs, Lexile, grade band, themes, banning records, cover URL) and every documented assignment (curriculum, state, grade, source URL).

Parameters

{slug}required
Book slug from the canonical book URL, e.g. to-kill-a-mockingbird.

Example

curl 'https://readinglist.school/api/book/to-kill-a-mockingbird'

Response shape

{
  "book": { "slug", "title", "author", "isbn13", "lexile", ... },
  "assignments": [ { "curriculum_slug", "state_slug", "grade_slug",
                     "source_url", "source_document", "context" }, ... ]
}

GET /api/curriculum/{slug}

Books cited in a curriculum framework (all grades)

Returns every book cited under the named curriculum, aggregated across all grade levels. Use this to seed a curriculum-aligned reading list at any grade.

Parameters

{slug}required
Curriculum slug — common-core, ap-literature, ap-language, ib-dp-english-literature, cambridge-igcse-english-lit, etc.

Example

curl 'https://readinglist.school/api/curriculum/common-core'

Response shape

{
  "curriculum": { "slug", "name", "type", "publisher", ... },
  "count": N,
  "books": [ { "slug", "title", "author", "lexile", "grade_min",
               "grade_max", ... }, ... ]
}

GET /api/curriculum/{slug}/grade/{gradeSlug}

Curriculum × grade intersection

Narrower than the curriculum-only endpoint. Returns books cited under the curriculum at the specific grade level.

Parameters

{slug}required
Curriculum slug.
{gradeSlug}required
Grade slug — K through 12.

Example

curl 'https://readinglist.school/api/curriculum/ap-literature/grade/11'

Response shape

{
  "curriculum": {...}, "grade": {...}, "count": N, "books": [...]
}

GET /api/state/{stateSlug}

Books cited at the state level (all grades)

Returns books documented in a US state's ELA framework, summer-reading list, or DOE guidance. Aggregated across all grades.

Parameters

{stateSlug}required
State slug — california, texas, florida, new-york, etc.

Example

curl 'https://readinglist.school/api/state/california'

Response shape

{
  "state": { "slug", "abbr", "name", "standards_name", "doe_url" },
  "count": N,
  "books": [...]
}

GET /api/state/{stateSlug}/grade/{gradeSlug}

State × grade intersection (includes national curricula)

Books cited at the state level for the specific grade, including national curricula (Common Core, AP, IB, Cambridge) that apply nationally — these are surfaced alongside state-tagged rows.

Parameters

{stateSlug}required
State slug.
{gradeSlug}required
Grade slug — K through 12.

Example

curl 'https://readinglist.school/api/state/california/grade/9'

Response shape

{
  "state": {...}, "grade": {...}, "count": N, "books": [...]
}

Versioning

The newer recommendation endpoint is namespaced /api/v1/ to allow forward-compatible evolution. Breaking changes will land under /api/v2/ with a deprecation window for v1 (typically 12 months). The non-versioned endpoints (/api/book, /api/curriculum, /api/state) are treated as stable v1 contracts and changes follow the same policy.

Citation

Researchers, journalists, ed-tech developers, and AI tutors are welcome to cite this API in derivative work. Suggested citation: ReadingList (readinglist.school) Classification Standard v1.0, 2026, accessed via /api/v1/recommend. The canonical methodology URL is https://readinglist.school/standard.

Bug reports, feature requests, and integration questions go through the contact page.