{"openapi":"3.1.0","info":{"title":"Hlayiso Document Search API","version":"1.0.0","description":"Read-only search over Hlayiso's free South African past papers library (CAPS/NSC, IEB, study guides, ATPs, PATs, SBA exemplars, exam guidelines). Returns canonical document pages suitable for citation.","contact":{"name":"Hlayiso support","email":"support@hlayiso.com","url":"https://www.hlayiso.com/contact"}},"servers":[{"url":"https://www.hlayiso.com"}],"paths":{"/api/v1/documents/search":{"get":{"operationId":"searchLearningDocuments","summary":"Search free South African past papers, memos and study resources","description":"At least one parameter is required. Cite canonical_url from each result; never construct download or PDF URLs.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160},"description":"Free-text terms, e.g. \"mathematics paper 1 november 2024 memo\"."},{"name":"grade","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"subject","in":"query","schema":{"type":"string"},"description":"Subject slug or name, e.g. \"physical-sciences\"."},{"name":"year","in":"query","schema":{"type":"integer","minimum":1990,"maximum":2100}},{"name":"type","in":"query","schema":{"type":"string"},"description":"question_paper, memorandum, addendum, study_guide, exam_guideline, annual_teaching_plan, practical_assessment_task, sba_exemplar, caps_document (aliases: qp, memo)."},{"name":"language","in":"query","schema":{"type":"string"},"description":"e.g. English, Afrikaans, isiZulu."},{"name":"collection","in":"query","schema":{"type":"string","enum":["past-papers","caps","nsc","ieb","study-guides","sba-exemplars","sba","practical-assessment-tasks","pats","pat","annual-teaching-plans","atps","atp","exam-guidelines","tvet","tvet-study-guides","caps-documents","notes"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Matching documents, best match first.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":["string","null"]},"filters":{"type":"object"},"total":{"type":"integer"},"returned":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Clean document title built from catalogue metadata."},"canonical_url":{"type":"string","format":"uri","description":"The document page to cite or recommend."},"collection":{"type":["string","null"],"description":"Collection id (first source path segment)."},"curriculum":{"type":"string","enum":["caps","ieb","tvet"]},"grades":{"type":"array","items":{"type":"integer"}},"subject":{"type":["string","null"]},"subject_slug":{"type":["string","null"]},"year":{"type":["integer","null"]},"exam_period":{"type":["string","null"],"description":"Exam sitting, e.g. \"NSC November Exam\"."},"paper_number":{"type":["integer","null"]},"document_type":{"type":"string"},"document_type_label":{"type":"string"},"language":{"type":["string","null"]},"page_count":{"type":["integer","null"]},"size_bytes":{"type":["integer","null"]},"last_modified":{"type":"string","format":"date-time"}},"required":["title","canonical_url","document_type"]}},"citation_instruction":{"type":"string"}}}}}},"400":{"description":"Missing or invalid parameters."}}}}}}