{"openapi":"3.1.0","info":{"title":"ReadingList API","version":"1.0.0","summary":"Public, free, no-auth REST API for K-12 reading-list data.","description":"Six endpoints serve book metadata, curriculum and state reading lists, and grade-appropriate recommendations. Built for AI tutors integrating grade-level book suggestions, ed-tech apps, library systems, and researchers. Every response cites the classification methodology at /standard. Full HTML documentation: /api.","contact":{"name":"ReadingList","url":"https://readinglist.school/contact"},"license":{"name":"Site terms","url":"https://readinglist.school/about"}},"servers":[{"url":"https://readinglist.school","description":"Production"}],"externalDocs":{"description":"Full API documentation + classification methodology","url":"https://readinglist.school/api"},"tags":[{"name":"Recommendations","description":"Phase 5 endpoint returning ranked book recommendations by filter combination."},{"name":"Books","description":"Single-book detail with all assignments."},{"name":"Curricula","description":"Curriculum-aligned reading lists (Common Core, AP, IB, Cambridge)."},{"name":"States","description":"State-level reading lists (50 US state ELA frameworks + DOE guidance)."}],"paths":{"/api/v1/recommend":{"get":{"tags":["Recommendations"],"summary":"Grade-appropriate book recommendations","description":"Returns up to 50 books matching a grade (required) plus optional curriculum, state, theme, author, genre, decade, year, Lexile range, and banned-state exclusion filters. v1.1 (2026-05-20) adds entity-axis filters that mirror /theme · /author · /genre · /decade hubs. Rate limit: free tier 100/day, Pro 1,000/day, Enterprise 10,000+/day. Auth + server-side rate enforcement coming in Phase 3.","operationId":"recommend","parameters":[{"name":"grade","in":"query","required":true,"description":"Grade slug — K, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.","schema":{"type":"string","enum":["K","1","2","3","4","5","6","7","8","9","10","11","12"]}},{"name":"state","in":"query","required":false,"description":"State slug (e.g. california, texas, new-york). Filters to books cited in that state's ELA framework or DOE list. National curricula (Common Core, AP, IB, Cambridge) included alongside state-tagged rows.","schema":{"type":"string"}},{"name":"curriculum","in":"query","required":false,"description":"Curriculum slug (e.g. common-core, ap-literature, ib-dp-english-literature, cambridge-igcse-english-lit).","schema":{"type":"string"}},{"name":"lexile_min","in":"query","required":false,"description":"Minimum Lexile measure. Books below filtered out. Typical range 0L-2000L.","schema":{"type":"integer","minimum":0}},{"name":"lexile_max","in":"query","required":false,"description":"Maximum Lexile measure. Books above filtered out.","schema":{"type":"integer","minimum":0}},{"name":"exclude_banned","in":"query","required":false,"description":"Set to 'true' to exclude books with any banning record per PEN America's Index.","schema":{"type":"boolean","default":false}},{"name":"theme","in":"query","required":false,"description":"Theme slug from /theme (≥3-book floor). E.g. friendship, coming-of-age, holocaust, american-dream, racism. Conjunctive with other filters.","schema":{"type":"string"}},{"name":"author","in":"query","required":false,"description":"Author slug from /author (≥2-book floor). E.g. william-shakespeare, john-steinbeck, toni-morrison, george-orwell.","schema":{"type":"string"}},{"name":"genre","in":"query","required":false,"description":"Genre slug from /genre (≥3-book floor). E.g. middle-grade-fiction, literary-fiction, historical-fiction, drama, dystopian-fiction.","schema":{"type":"string"}},{"name":"decade","in":"query","required":false,"description":"Publication decade. Accepts '1960' or '1960s'. Range 1900-2020.","schema":{"type":"string","pattern":"^(19[0-9]{2}|20[0-9]{2})s?$"}},{"name":"year","in":"query","required":false,"description":"Exact first-publication year. Range 1500-2030.","schema":{"type":"integer","minimum":1500,"maximum":2030}},{"name":"limit","in":"query","required":false,"description":"Max books returned. Default 10. Cap 50; higher values silently capped.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Recommendations returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}},"headers":{"X-RateLimit-Tier":{"schema":{"type":"string","example":"free"},"description":"Currently always 'free' (auth not live)."},"X-RateLimit-Daily-Limit":{"schema":{"type":"string","example":"100"},"description":"Free-tier daily request cap."},"Cache-Control":{"schema":{"type":"string","example":"public, max-age=3600, s-maxage=86400"}}}},"400":{"description":"Validation error — missing required param or invalid value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Reference not found — grade/state/curriculum slug doesn't match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/book/{slug}":{"get":{"tags":["Books"],"summary":"Single book detail with all assignments","operationId":"getBook","parameters":[{"name":"slug","in":"path","required":true,"description":"Book slug from canonical URL — e.g. to-kill-a-mockingbird.","schema":{"type":"string"}}],"responses":{"200":{"description":"Book detail returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookDetail"}}}},"404":{"description":"Book not found for slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/curriculum/{slug}":{"get":{"tags":["Curricula"],"summary":"Books cited in a curriculum framework (all grades aggregated)","operationId":"getCurriculum","parameters":[{"name":"slug","in":"path","required":true,"description":"Curriculum slug — common-core, ap-literature, ap-language, ib-dp-english-literature, cambridge-igcse-english-lit, etc.","schema":{"type":"string"}}],"responses":{"200":{"description":"Curriculum reading list returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurriculumResponse"}}}},"404":{"description":"Curriculum not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/curriculum/{slug}/grade/{gradeSlug}":{"get":{"tags":["Curricula"],"summary":"Curriculum × grade intersection","operationId":"getCurriculumGrade","parameters":[{"name":"slug","in":"path","required":true,"description":"Curriculum slug.","schema":{"type":"string"}},{"name":"gradeSlug","in":"path","required":true,"description":"Grade slug — K through 12.","schema":{"type":"string"}}],"responses":{"200":{"description":"Books cited in this curriculum at this specific grade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurriculumGradeResponse"}}}},"404":{"description":"Curriculum or grade slug not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/state/{stateSlug}":{"get":{"tags":["States"],"summary":"Books cited at the state level (all grades aggregated)","operationId":"getState","parameters":[{"name":"stateSlug","in":"path","required":true,"description":"State slug — california, texas, florida, new-york, etc.","schema":{"type":"string"}}],"responses":{"200":{"description":"State reading list returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateResponse"}}}},"404":{"description":"State not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/state/{stateSlug}/grade/{gradeSlug}":{"get":{"tags":["States"],"summary":"State × grade intersection (national curricula included)","operationId":"getStateGrade","parameters":[{"name":"stateSlug","in":"path","required":true,"description":"State slug.","schema":{"type":"string"}},{"name":"gradeSlug","in":"path","required":true,"description":"Grade slug — K through 12.","schema":{"type":"string"}}],"responses":{"200":{"description":"Books cited at the state level for the grade, including national curricula","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateGradeResponse"}}}},"404":{"description":"State or grade slug not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/theme/{slug}":{"get":{"tags":["Themes"],"summary":"Books exploring a literary theme","description":"Returns all books in the corpus tagged with the named theme. Theme must meet the ≥3-book global floor (i.e. have a /theme/[slug] hub page). v1.1 — added 2026-05-20.","operationId":"getTheme","parameters":[{"name":"slug","in":"path","required":true,"description":"Theme slug — e.g. friendship, coming-of-age, holocaust, american-dream. List at /theme.","schema":{"type":"string"}}],"responses":{"200":{"description":"Theme detail + book list returned","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Theme slug doesn't match any hub-eligible theme","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/author/{slug}":{"get":{"tags":["Authors"],"summary":"Author with all titles + recurring themes + genres","description":"Returns the author entity with full title list + recurring themes + genres aggregated from this author's corpus. Wikipedia URL included when known (e.g. Shakespeare, Steinbeck, Morrison). Author must meet ≥2-book global floor. v1.1 — added 2026-05-20.","operationId":"getAuthor","parameters":[{"name":"slug","in":"path","required":true,"description":"Author slug — e.g. william-shakespeare, john-steinbeck. List at /author.","schema":{"type":"string"}}],"responses":{"200":{"description":"Author detail + book list returned","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Author slug doesn't match any hub-eligible author","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/genre/{slug}":{"get":{"tags":["Genres"],"summary":"Books in a literary genre + recurring themes + authors","description":"Returns books in the named genre with top recurring themes + top authors. Genre must meet ≥3-book global floor. v1.1 — added 2026-05-20.","operationId":"getGenre","parameters":[{"name":"slug","in":"path","required":true,"description":"Genre slug — e.g. middle-grade-fiction, literary-fiction, dystopian-fiction, drama. List at /genre.","schema":{"type":"string"}}],"responses":{"200":{"description":"Genre detail + book list returned","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Genre slug doesn't match any hub-eligible genre","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/decade/{slug}":{"get":{"tags":["Decades"],"summary":"Books written in a decade + themes + authors + genres","description":"Returns books written between [decade, decade+10) with recurring themes + top authors + genres. Slug accepts '1960' or '1960s'. Range 1900-2020. v1.1 — added 2026-05-20.","operationId":"getDecade","parameters":[{"name":"slug","in":"path","required":true,"description":"Decade slug — e.g. 1960s or 1960. Range 1900-2020.","schema":{"type":"string","pattern":"^(19[0-9]{2}|20[0-9]{2})s?$"}}],"responses":{"200":{"description":"Decade detail + book list returned","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid decade slug (must be /^(19|20)\\d{2}s?$/)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No books on file for this decade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Stable error code, e.g. missing_required_param, grade_not_found, invalid_lexile_param."},"message":{"type":"string","description":"Human-readable explanation."},"documentation_url":{"type":"string","format":"uri","description":"Link to the relevant /standard methodology section."}}},"Book":{"type":"object","required":["slug","title","author"],"properties":{"slug":{"type":"string","description":"Stable book slug (canonical /book/[slug] URL)."},"title":{"type":"string"},"author":{"type":"string"},"isbn13":{"type":"string","nullable":true},"isbn10":{"type":"string","nullable":true},"lexile":{"type":"integer","nullable":true,"description":"Lexile measure (0L-2000L typical). See /standard#lexile."},"lexile_range_min":{"type":"integer","nullable":true},"lexile_range_max":{"type":"integer","nullable":true},"grade_min":{"type":"integer","nullable":true,"description":"Min grade (0=K). See /standard#grade-band."},"grade_max":{"type":"integer","nullable":true},"first_published":{"type":"integer","nullable":true,"description":"Publication year of first edition."},"themes":{"type":"array","items":{"type":"string"},"description":"Themes / topical tags. Plain-text strings; not categorical."},"banned_in_states":{"type":"array","items":{"type":"string"},"description":"US state abbreviations where the book has formal removal/restriction records per PEN America. See /standard#banned-states."},"cover_url":{"type":"string","nullable":true,"format":"uri"},"permalink":{"type":"string","format":"uri","description":"Canonical HTML page for the book."},"api_url":{"type":"string","format":"uri","description":"Machine-readable detail endpoint."}}},"BookDetail":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/Assignment"}}}},"Assignment":{"type":"object","properties":{"curriculum_slug":{"type":"string","nullable":true},"curriculum_name":{"type":"string","nullable":true},"curriculum_type":{"type":"string","nullable":true},"state_slug":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"grade_slug":{"type":"string","nullable":true},"grade_label":{"type":"string","nullable":true},"category":{"type":"string","description":"e.g. recommended, required, exemplar, supplementary."},"context":{"type":"string","nullable":true,"description":"Seasonal/program tag — summer, back-to-school, AP-prep, etc. See /standard#context."},"source_url":{"type":"string","format":"uri","description":"Primary-source URL where this assignment is cited (state DOE page, AP framework, etc.)."},"source_document":{"type":"string","nullable":true,"description":"Section name within the source document."}}},"Filters":{"type":"object","properties":{"grade":{"type":"string"},"state":{"type":"string","nullable":true},"curriculum":{"type":"string","nullable":true},"lexile_min":{"type":"integer","nullable":true},"lexile_max":{"type":"integer","nullable":true},"exclude_banned":{"type":"boolean"},"limit":{"type":"integer"}}},"RateLimit":{"type":"object","properties":{"tier":{"type":"string","example":"free"},"daily_limit":{"type":"integer","example":100},"pro_tier_daily":{"type":"integer","example":1000},"enterprise_tier_daily":{"type":"string","example":"10000+"},"enforcement":{"type":"string"}}},"RecommendResponse":{"type":"object","required":["version","filters","count","books"],"properties":{"version":{"type":"string","example":"v1"},"generated_at":{"type":"string","format":"date-time"},"filters":{"$ref":"#/components/schemas/Filters"},"methodology_url":{"type":"string","format":"uri"},"methodology_summary":{"type":"string"},"rate_limit":{"$ref":"#/components/schemas/RateLimit"},"count":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}},"State":{"type":"object","properties":{"slug":{"type":"string"},"abbr":{"type":"string"},"name":{"type":"string"},"standards_name":{"type":"string","nullable":true},"doe_url":{"type":"string","format":"uri","nullable":true}}},"Grade":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"level":{"type":"integer"},"band":{"type":"string","nullable":true}}},"Curriculum":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"publisher":{"type":"string","nullable":true}}},"CurriculumResponse":{"type":"object","properties":{"curriculum":{"$ref":"#/components/schemas/Curriculum"},"count":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}},"CurriculumGradeResponse":{"type":"object","properties":{"curriculum":{"$ref":"#/components/schemas/Curriculum"},"grade":{"$ref":"#/components/schemas/Grade"},"count":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}},"StateResponse":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/State"},"count":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}},"StateGradeResponse":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/State"},"grade":{"$ref":"#/components/schemas/Grade"},"count":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}}}}}