Dokumentacja

REST API i MCP · ostatnia aktualizacja: 2026-09-14

matura.lol to wyszukiwarka zadań szkolnych i egzaminacyjnych. Poniżej opisane są dwa sposoby dostępu do danych: REST API oraz serwer MCP (Model Context Protocol). Oba są publiczne, tylko do odczytu i korzystają z tej samej logiki co interfejs.

REST API

Bazowy adres: https://matura.lol. API nie wymaga klucza, jest tylko do odczytu, a CORS jest otwarty (Access-Control-Allow-Origin: *).

Metoda	Ścieżka	Opis
GET	`/api`	Katalog endpointów (JSON)
GET	`/api/openapi.json`	Pełny schemat OpenAPI 3
GET	`/api/health`	Liczba rekordów w korpusie
GET	`/api/facets`	Przedmioty, kategorie, poziomy, typy zadań, lata (+ liczby)
GET	`/api/search?q=…`	Wyszukiwanie pełnotekstowe
GET	`/api/paper/{paper_id}`	Metadane arkusza i wszystkie jego zadania
GET	`/api/question/{question_id}`	Jedno zadanie: treść, klucz/rozwiązanie, strony źródłowe
GET	`/pdf/{paper_id}`	Oryginalny arkusz PDF
GET	`/source/{paper_id}/{page}`	Render strony źródłowej (PNG)

Parametry `/api/search`

q (słowa po polsku, przedrostkowo — ciag pasuje do ciąg; przeszukiwane są też rozwiązania) oraz opcjonalnie subject, category, level (podstawowa/rozszerzona), ptype, topic (dział z /api/facets), has (solution/answer — tylko zadania z rozwiązaniem lub kluczem), year, sort (relevance/year), page i limit (maks. 100). Zduplikowane (błędnie opisane) arkusze są domyślnie ukryte; include_duplicates=1 je pokaże.

curl 'https://matura.lol/api/search?q=ciag%20geometryczny&subject=matematyka&year=2024&limit=20'

Liczenie: `count`

Dodaj count=subject|category|level|ptype|year|month|variant|topic, żeby zamiast listy wyników dostać liczby dla każdej wartości. Odpowiedź zawiera wtedy tablicę counts z polami id, label i count, a total to suma dopasowanych zadań. Wszystkie filtry (q, subject, category, …) działają jak zwykle, więc można policzyć np. trend roczny dla jednego przedmiotu. Gotowy interfejs: matura.lol/statystyka.

curl 'https://matura.lol/api/search?subject=matematyka&category=matura&count=year'

Składnia zapytań (operatory)

W polu wyszukiwania działają operatory w stylu SearXNG. Można ich też użyć w /api/search?q=, więc nadają się do linków i skryptów.

`!bang` — filtr przedmiotu, kategorii, poziomu i typu

Poprzedź słowo znakiem !, aby ustawić filtr. Operatory można łączyć, np. !mat !pr funkcje szuka zadań z matematyki na poziomie rozszerzonym. !matura (kategoria) to nie to samo co !matematyka (przedmiot). Krótsze i dłuższe formy są równoważne (!mat = !matematyka).

Przykład	Znaczenie
`!mat`, `!matematyka`	przedmiot: matematyka
`!bio`, `!chemia`, `!fiz`, `!geo`	przedmiot: biologia, chemia, fizyka, geografia
`!hist`, `!wos`, `!pol`, `!ang`	przedmiot: historia, WOS, język polski, język angielski
`!inf`, `!fil`, `!zawodowy`	przedmiot: informatyka, filozofia, egzamin zawodowy
`!matura`, `!probna`	kategoria: matura, matura próbna
`!osmo`, `!gim`	kategoria: egzamin ósmoklasisty, egzamin gimnazjalny
`!informator`, `!zbiory`	kategoria: informator maturalny, zbiory zadań
`!podrecznik`, `!skul`	źródło: zadania z podręczników skul.pl (bez demotacji w wynikach; bez banga podręczniki trafiają niżej niż zadania egzaminacyjne)
`!pp`, `!pr`	poziom: podstawowa, rozszerzona
`!zamkniete`, `!otwarte`, `!tf`	typ zadania: zamknięte, otwarte, prawda/fałsz
`!odpowiedz`, `!rozwiazanie`	tylko zadania z kluczem odpowiedzi / rozwiązaniem
`!najnowsze`	sortowanie od najnowszych
`!pdf`, `!arkusz`	pokaż też karty całych arkuszy do pobrania

Nieznany bang (np. !cokolwiek) jest traktowany jak zwykłe słowo. Pełną listę wartości filtrów znajdziesz w /api/facets, a podpowiedzi bangów zwraca /api/suggest.

Pozostałe operatory

"ciąg geometryczny" — wymagana fraza: słowa muszą stać obok siebie (odmiana jest tolerowana).
-pochodna lub -"pole trójkąta" — wyklucza wyniki zawierające dane słowo/frazę.
!! ciąg geometryczny — „feeling lucky": od razu przechodzi do pierwszego wyniku (albo /lucky?q=).

https://matura.lol/?q=!mat !pr "ciąg geometryczny" -pochodna
https://matura.lol/lucky?q=!! fotosynteza

Wyszukiwarka w przeglądarce (OpenSearch)

Możesz dodać matura.lol jako wyszukiwarkę w przeglądarce: opis OpenSearch jest pod /opensearch.xml, a podpowiedzi dostarcza /api/suggest. Wiele przeglądarek wykrywa go automatycznie z <link rel="search"> na stronie głównej.

Agregacje i podświetlanie (styl Elasticsearch)

Do /api/search możesz dodać aggs=<json>, żeby policzyć rozkłady po tym samym zbiorze wyników. Obsługiwane są terms (np. przedmioty), histogram / date_histogram (np. lata), stats, cardinality, range, percentiles oraz zagnieżdżony filter. Odpowiedź zawiera obiekt aggregations w formacie Elasticsearch (buckets/doc_count/values), a każdy kubełek terms ma też czytelną etykietę label.

curl 'https://matura.lol/api/search?subject=matematyka&aggs=%7B%22lata%22%3A%7B%22histogram%22%3A%7B%22field%22%3A%22year%22%2C%22interval%22%3A5%7D%7D%7D'

highlight=1, highlight=text,solution albo obiekt JSON dodaje do każdego wyniku pole highlight (pole → lista fragmentów z <em>). fields=id,text,answer zawęża zwracane pola wyniku (odpowiednik _source); id i paper_id są zawsze zwracane.

MCP (agenci i asystenci)

Serwer MCP działa pod https://matura.lol/mcp (streamable HTTP, bez sesji, odpowiedzi JSON). Udostępnia narzędzia: search_questions, get_question, get_paper i list_facets. Korzystają one z tej samej logiki co API, więc wyniki są zawsze spójne.

claude mcp add --transport http matura https://matura.lol/mcp

Lokalnie, po stdio (np. Claude Desktop, po zainstalowaniu projektu):

{
  "mcpServers": {
    "matura": {"command": "uv", "args": ["run", "search-matugen", "mcp"]}
  }
}

Mniej żądań

Potrzebujesz całego arkusza → jedno /api/paper/{paper_id} zamiast stronicowania.
Potrzebujesz jednego zadania → /api/question/{question_id}.
Wyniki wyszukiwania zawierają już identyfikatory, fragmenty, odpowiedzi i adresy obrazków — pobieraj szczegóły tylko dla trafień, których naprawdę użyjesz.
Cache'uj odpowiedzi; dane zmieniają się dopiero po przeładowaniu korpusu.

Odkrywanie dla agentów

/llms.txt — krótka wskazówka dla LLM-ów.
/agents.md — instrukcja dla agentów (endpointy, przykłady, mniej żądań).
/api/openapi.json — schemat OpenAPI.
/robots.txt — zezwala agentom na /api/ i /mcp, blokuje /*?q=.

Uwagi o korpusie i źródłach

Główną część stanowią oficjalne arkusze CKE i OKE; korpus obejmuje również zadania ze zbiorów i podręczników szkolnych (m.in. import zadań z podręczników ze skul.pl w kategorii zbiory, zadania z matematykaszkolna.pl oraz bank zadaniazmatur.pl).
Tekst pochodzi z warstwy tekstowej PDF lub OCR, po polsku; diakrytyki są składane na potrzeby wyszukiwania.
Pochodzenie odpowiedzi i rozwiązań (source / solution_source): "ocr" to oficjalny klucz CKE; źródła zewnętrzne (np. "skul", "odrabiamy", "matematykaorg", "maturaonline", "zadaniazmatur", "site") dostarczają nieoficjalne rozwiązania i odpowiedzi; source = "ai" oznacza rozwiązania wygenerowane modelem tam, gdzie nie ma oficjalnego klucza CKE — zaznaczaj to, cytując.
Zadania z arkuszy mają paper_id, page_from oraz odwołania do źródłowego PDF; zadania ze skul.pl zawierają metadane podręcznika (wydawnictwo, klasa, strona) i działy tematyczne.

Tryb nauki

Nauka na stronie głównej (fiszki z powtórkami SM-2, szybka powtórka i trening przekrojowy) działa w całości w Twojej przeglądarce. Jeśli ją wyłączyłeś, możesz włączyć ją ponownie tutaj.

Panele wyników i statystyk

Recap, Podobne zadania oraz Statystyki ruchu możesz ukryć przyciskiem ×. Jeśli je ukryjesz, włączysz je ponownie tutaj (odśwież stronę po zmianie).