{"openapi":"3.1.0","info":{"title":"Sheber Education — Agents API","version":"1.0.0","description":"Read-only API for AI agents: search 80,000+ teaching materials for Kazakhstan schools (Kazakh/Russian), browse sections, AI tools and prices. No auth. Always give the user the `url` field — downloading and payment happen on the site. Guide: https://sheber.education/agents","contact":{"email":"sheber.education@gmail.com","url":"https://sheber.education/agents"}},"servers":[{"url":"https://sheber.education"}],"paths":{"/api/agents/search":{"get":{"operationId":"searchMaterials","summary":"Search teaching materials by text and/or subject, grade, type","description":"Материал іздеу (ҚМЖ, презентация, тест, БЖБ/ТЖБ т.б.)","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Іздеу мәтіні, қазақша не орысша. Мысалы: «алгебра 8 сынып ҚМЖ»"},{"name":"subject","in":"query","required":false,"schema":{"type":"string"},"description":"Пән слагы (/api/agents/sections ішінен), мысалы matematika"},{"name":"grade","in":"query","required":false,"schema":{"type":"string"},"description":"Сынып слагы, мысалы 8-synyp"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Материал түрінің слагы, мысалы sabaq-zhospary"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Бет нөмірі, 1-ден"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Бір беттегі саны, 1–30 (әдепкі 10)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"has_more":{"type":"boolean"},"search_url":{"type":"string","format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Material"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/agents/materials/{uri}":{"get":{"operationId":"getMaterial","summary":"One material in full: description, format, pages, price, URL","description":"Бір материалдың толық сипаттамасы","parameters":[{"name":"uri","in":"path","required":true,"schema":{"type":"string"},"description":"Материал адресінің соңы, мысалы qmzh-2-synyp-176025"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Material"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/agents/sections":{"get":{"operationId":"listSections","summary":"Subjects, grades and material types with slugs and section pages; pass path= for one section","description":"Пәндер, сыныптар, материал түрлері — слагтары және бөлім беттері","parameters":[{"name":"path","in":"query","required":false,"schema":{"type":"string"},"description":"Бөлім жолы, мысалы pan/matematika/8-synyp. Берілсе — сол бөлімнің материалдары"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Бөлім ішіндегі бет нөмірі"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/agents/tools":{"get":{"operationId":"listTools","summary":"AI generators (lesson plans, slides, tests), classroom games and tools","description":"Sheber AI генераторлары, білім ойындары және сабаққа арналған құралдар","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/api/agents/pricing":{"get":{"operationId":"getPricing","summary":"Subscription prices (KZT) and what they include","description":"Жазылым бағалары және не кіретіні","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"Material":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri","description":"Адамға беретін сілтеме / link to give the user"},"uri":{"type":"string"},"subject":{"type":"string","nullable":true},"grade":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"format":{"type":"string","nullable":true,"example":"docx"},"pages":{"type":"integer","nullable":true},"price_kzt":{"type":"number","nullable":true},"downloads":{"type":"integer"},"author":{"type":"string","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"hint":{"type":"string"}}}}}}}}}