{"openapi":"3.1.0","info":{"title":"Sprawna Matura - API dla agentów","version":"1.0.0","summary":"Otwarty dostęp do zadań maturalnych CKE, rozwiązań i treści blogowych.","description":"Publiczne, bezpłatne API serwisu Sprawna Matura (sprawnamatura.pl) - polskiej platformy\ndo przygotowania do matury z matematyki na poziomie podstawowym.\n\nUdostępnia ponad 2400 prawdziwych zadań z arkuszy CKE z lat 2015-2025, każde z pełnym\nrozwiązaniem krok po kroku, wraz z treściami blogowymi i stronami działów matematyki.\n\nUwierzytelnianie nie jest wymagane. Treści są w języku polskim.\n\nPoza endpointami opisanymi poniżej każdą stronę serwisu można pobrać jako markdown:\ndopisz `.md` do adresu (np. `/topics/planimetria.md`) albo wyślij nagłówek\n`Accept: text/markdown`.","contact":{"name":"Sprawna Matura","email":"kontakt@sprawnamatura.pl","url":"https://www.sprawnamatura.pl/kontakt"},"license":{"name":"Warunki korzystania","url":"https://www.sprawnamatura.pl/regulamin"}},"servers":[{"url":"https://www.sprawnamatura.pl","description":"Produkcja"}],"externalDocs":{"description":"Dokumentacja dla deweloperów","url":"https://www.sprawnamatura.pl/dla-deweloperow"},"tags":[{"name":"Treść","description":"Pobieranie stron serwisu jako markdown."},{"name":"Wyszukiwanie","description":"Wyszukiwanie zadań i artykułów."},{"name":"Indeks","description":"Listy adresów i indeksy dla agentów."}],"paths":{"/api/ai/search":{"get":{"operationId":"searchContent","tags":["Wyszukiwanie"],"summary":"Szukaj zadań maturalnych i artykułów","description":"Wyszukiwanie pełnotekstowe po treści zadań CKE i artykułach blogowych. Wyniki są posortowane malejąco według trafności. Limit zapytań: 1000 na minutę na adres IP.","parameters":[{"name":"q","in":"query","required":true,"description":"Szukana fraza, minimum 2 znaki. Np. `logarytmy`, `ciąg arytmetyczny`.","schema":{"type":"string","minLength":2,"maxLength":200},"example":"logarytmy"},{"name":"limit","in":"query","required":false,"description":"Maksymalna liczba wyników.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"type","in":"query","required":false,"description":"Ograniczenie do jednego rodzaju treści.","schema":{"type":"string","enum":["all","blog","task","exam","topic","static"],"default":"all"}}],"responses":{"200":{"description":"Lista wyników posortowana według trafności.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ai/pages":{"get":{"operationId":"listPages","tags":["Indeks"],"summary":"Wypisz adresy stron serwisu","description":"Stronicowana lista wszystkich publicznych adresów: zadań, działów, arkuszy, artykułów i stron statycznych. Przydatna do zbudowania własnego indeksu.","parameters":[{"name":"limit","in":"query","required":false,"description":"Liczba adresów na stronę.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"description":"Przesunięcie względem początku listy.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"type","in":"query","required":false,"description":"Ograniczenie do jednego rodzaju stron.","schema":{"type":"string","enum":["all","blog","task","exam","topic","static"],"default":"all"}}],"responses":{"200":{"description":"Stronicowana lista adresów.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagesResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ai/content":{"get":{"operationId":"getPageAsMarkdown","tags":["Treść"],"summary":"Pobierz dowolną stronę jako markdown","description":"Zwraca treść wskazanej strony w formacie markdown, z nagłówkiem YAML (pola `route`, `title` i zależne od rodzaju strony). Równoważne dopisaniu `.md` do adresu strony.","parameters":[{"name":"route","in":"query","required":true,"description":"Ścieżka strony, ze slashem na początku. Np. `/topics/planimetria`, `/task/cke-2015-2023-pp-01`, `/exams/matura-2024-pp`.","schema":{"type":"string","pattern":"^/"},"example":"/topics/planimetria"}],"responses":{"200":{"description":"Treść strony w markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/MarkdownNotFound"}}}},"/api/ai/md/{route}":{"get":{"operationId":"getPageAsMarkdownByPath","tags":["Treść"],"summary":"Pobierz stronę jako markdown po ścieżce","description":"Wariant `getPageAsMarkdown` ze ścieżką w adresie zamiast w parametrze zapytania. Tu trafiają też żądania z nagłówkiem `Accept: text/markdown` oraz adresy z końcówką `.md`.","parameters":[{"name":"route","in":"path","required":true,"description":"Ścieżka strony bez początkowego slasha, np. `topics/planimetria`.","schema":{"type":"string"},"example":"topics/planimetria"}],"responses":{"200":{"description":"Treść strony w markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/MarkdownNotFound"}}}},"/llms.txt":{"get":{"operationId":"getLlmsIndex","tags":["Indeks"],"summary":"Skrócony indeks serwisu dla modeli językowych","description":"Zwięzły opis serwisu, kluczowe fakty i lista głównych stron - w formacie llms.txt.","responses":{"200":{"description":"Indeks w formacie tekstowym.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/llms-full.txt":{"get":{"operationId":"getLlmsFullIndex","tags":["Indeks"],"summary":"Pełny indeks serwisu dla modeli językowych","description":"Rozszerzona wersja llms.txt z pełną listą treści.","responses":{"200":{"description":"Pełny indeks w formacie tekstowym.","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"SearchResult":{"type":"object","required":["route","title","type"],"properties":{"route":{"type":"string","description":"Ścieżka strony w serwisie."},"title":{"type":"string","description":"Tytuł zadania lub artykułu."},"type":{"type":"string","enum":["task","blog","topic","exam","static"],"description":"Rodzaj treści."},"excerpt":{"type":"string","description":"Fragment treści pasujący do zapytania."},"category":{"type":"string","description":"Dział matematyki."},"score":{"type":"number","description":"Trafność - im wyżej, tym lepiej."}}},"SearchResponse":{"type":"object","required":["query","results","total"],"properties":{"query":{"type":"string","description":"Zapytanie, na które odpowiadamy."},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"total":{"type":"integer","description":"Liczba znalezionych wyników."}}},"PageRef":{"type":"object","required":["route","url"],"properties":{"route":{"type":"string","description":"Ścieżka względna."},"url":{"type":"string","format":"uri","description":"Pełny adres."},"title":{"type":"string"},"type":{"type":"string","enum":["task","blog","topic","exam","static"]}}},"PagesResponse":{"type":"object","required":["pages","total","limit","offset","hasMore"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/PageRef"}},"total":{"type":"integer","description":"Łączna liczba adresów."},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean","description":"Czy są kolejne strony wyników."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["not_found","invalid_request","rate_limited","forbidden","unauthorized","service_unavailable","internal_error"],"description":"Maszynowy kod błędu."},"message":{"type":"string","description":"Opis błędu po polsku."},"hint":{"type":"string","description":"Co zrobić, żeby żądanie się powiodło."},"docs":{"type":"string","format":"uri"}}}}}},"responses":{"BadRequest":{"description":"Nieprawidłowe parametry żądania.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Przekroczony limit zapytań. Nagłówek `Retry-After` mówi, ile odczekać.","headers":{"Retry-After":{"description":"Liczba sekund do kolejnej próby.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MarkdownNotFound":{"description":"Strona nie istnieje. Odpowiedź to krótki dokument markdown z linkami do mapy strony i indeksów.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}