Dokumentacja API.

Pierwsze żądanie

Adres bazowy: https://api.zapytajkodeks.pl/api/v1. Żądania wymagają nagłówka Authorization: Bearer …. W żądaniach POST ustaw Content-Type: application/json. Przechowuj klucz na swoim serwerze; nie umieszczaj go w kodzie przeglądarki ani w repozytorium.

W terminalu ustaw zmienną ZK_API_KEY z otrzymanym kluczem. Poniższy przykład wykonuje wyszukiwanie i zużywa 1 request.

curl https://api.zapytajkodeks.pl/api/v1/provisions/search \
  -H "Authorization: Bearer $ZK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "odpowiedzialność za szkodę",
  "actName": "Kodeks cywilny",
  "limit": 3
}'

Interaktywna specyfikacja zawiera wszystkie pola wejściowe, schematy odpowiedzi i kody HTTP. Alias /v1 jest obsługiwany dla zgodności z dotychczasowymi integracjami.

Endpointy

Ścieżki poniżej są względne wobec adresu bazowego. Identyfikatory numeryczne pobierz z wyniku wyszukiwania, a identyfikator edycji — z listy wersji aktu.

Dane i źródła

Wyszukiwanie zwraca items, odczyt źródła — source. W odpowiedziach źródłowych znajdziesz schemaVersion i warnings. Uwzględnij ostrzeżenia w swojej integracji. Brak źródła zwraca HTTP 404.

• provision:123 i judgment:123 są identyfikatorami źródeł. W adresie GET użyj części numerycznej. Identyfikatory z analizy AI mają inny zakres — opis poniżej.
• contentKind: verbatim oznacza tekst źródłowy, ai_summary — gotowe opracowanie AI. Orzeczenia zwracane przez wyszukiwanie są opracowaniami; tekst pobierz przez GET.
• W pełnym orzeczeniu text to tekst źródłowy, a details.aiAnalysis i details.aiTheses to opracowania AI.
• Interpretacje mają contentKind: source_with_ai_enrichment. thesis pochodzi od organu, a questions.issue i questions.outcome są opracowane przez AI. Pełny tekst znajduje się w textContentHtml.
• Akt zawiera instrument, edition, structureNodes i provisions. HTML w contentHtml jest danymi źródłowymi — przed wyświetleniem zastosuj sanitizację.
• canonicalUrl lub sourceUrl może być null. Nie tworzymy brakujących adresów ani dat aktualności.

Wyszukiwanie

Tryby: lexical, semantic, hybrid (domyślny). Zapytanie ma 2–500 znaków, limit 1–20 wyników. Orzeczenia i interpretacje przyjmują 1–5 zapytań w queries. To wyszukiwanie najlepszych wyników, bez stronicowania całego zbioru i bez eksportu masowego.

curl https://api.zapytajkodeks.pl/api/v1/judgments/search \
  -H "Authorization: Bearer $ZK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "queries": [
    "odpowiedzialność członka zarządu"
  ],
  "courtTypes": [
    "SUPREME"
  ],
  "dateFrom": "2020-01-01",
  "limit": 5
}'

Typy aktów: PL_ACT, PL_REGULATION, EU_REGULATION. Kategorie sądów: COMMON, SUPREME, CONSTITUTIONAL_TRIBUNAL, SUPREME_ADMINISTRATIVE_COURT, VOIVODESHIP_ADMINISTRATIVE_COURT, NATIONAL_APPEAL_CHAMBER. Poziomy sądów powszechnych: appeal, regional, district. Daty podawaj jako YYYY-MM-DD.

Wersje i zakres bazy

Najpierw pobierz GET /acts/123/editions, następnie GET /acts/123?editionId=456. Liczby w przykładzie zastąp rzeczywistymi identyfikatorami. Serwer sprawdza, czy edycja należy do aktu. Lista zawiera wersje dostępne w naszej bazie; data publikacji nie oznacza automatycznie stanu prawnego na tę datę.

API nie ustala jeszcze stanu prawnego na dowolny dzień i nie deklaruje kompletności wszystkich źródeł. Pobranie przepisu po ID korzysta z dostępnej najnowszej edycji, a historyczny tekst przepisu odczytasz z wybranej edycji aktu.

Analiza AI

question przyjmuje do 10 000 znaków. Analiza wykorzystuje ten sam agent badawczy co aplikacja i zużywa 1 analizę z limitu AI. Jej wewnętrzne wyszukiwania są w cenie. Maksymalny czas operacji wynosi 240 sekund.

curl https://api.zapytajkodeks.pl/api/v1/ai/analysis \
  -H "Authorization: Bearer $ZK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: analiza-001" \
  -d '{
  "question": "Jakie są przesłanki odpowiedzialności deliktowej?"
}'

Kontekst i format

• settings.messages: historia z rolami user i assistant, do 10 000 znaków w wiadomości. Serwer przyjmuje do 32 wiadomości i zachowuje ostatnie 8. Nie dodawaj tu bieżącego pytania.
• settings.additional_context: tekst, np. fragment dokumentu. Serwer przyjmuje do 50 000 znaków i zachowuje pierwsze 10 000, zgodnie z dotychczasowym kontraktem. Dla przewidywalności wysyłaj maksymalnie 10 000 znaków.
• settings.output_format_prompt: instrukcja formatu do 2000 znaków. To instrukcja dla modelu; wynik nie jest walidowany względem schematu JSON.

API przyjmuje tekst. Załączniki plikowe i OCR nie są obecnie obsługiwane. Nieznane pola są odrzucane.

{
  "response": "Odpowiedź z odwołaniami do źródeł…",
  "sources": [
    {
      "type": "provision",
      "id": 1,
      "fields": {
        "title": "Tytuł źródła",
        "snippet": null,
        "external_id": "123"
      }
    }
  ],
  "finishReason": "stop"
}

sources[].id jest lokalnym numerem odwołania w danej analizie. Nie przekazuj go jako identyfikatora GET. fields.external_id jest identyfikatorem zależnym od typu źródła — do odczytu przez endpoint danych używaj tylko numerycznego identyfikatora odpowiadającego właściwemu typowi.

Strumień NDJSON

Wyślij to samo żądanie do /ai/analysis/stream. Odpowiedź ma typ application/x-ndjson; każda linia to osobny JSON. Odczytuj zdarzenia text-delta, a finalną treść i źródła bierz z finish — agent może skorygować wcześniejszy tekst.

{"type":"text-delta","textDelta":"Treść odpowiedzi…"}
{"type":"finish","response":"Finalna treść…","sources":[],"finishReason":"stop","usage":{"meter":"ai","units":1},"request_id":"00000000-0000-4000-8000-000000000001"}

Limit jest rezerwowany przed wysłaniem HTTP 200. Błąd wykonania jest zdarzeniem error, kończy się finishReason: error i zwalnia niepotwierdzoną rezerwację. finish.usage.reservationStatus wskazuje stan rozliczenia: refunded lub expired oznacza brak zużycia limitu analiz AI; committed oznacza potwierdzony koszt, a reserved — stan wymagający sprawdzenia przez /usage. Utrata odpowiedzi po potwierdzeniu kosztu nie cofa rozliczenia. Nagłówki pokazują początkową rezerwację. Zerwanie połączenia przerywa analizę.

Cytaty

Ekstrakcja zużywa 1 analizę z limitu AI i zwraca tylko fragmenty znalezione dosłownie w tekście źródła. Gdy model nie wybierze poprawnych fragmentów lub jest niedostępny, stosujemy dobór zdań według dopasowania tekstowego. Model analizuje pierwsze 150 000 znaków źródła; brak cytatu nie dowodzi braku istotnego fragmentu w dalszej części.

curl https://api.zapytajkodeks.pl/api/v1/ai/quotes/extract \
  -H "Authorization: Bearer $ZK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceId": "judgment:123",
  "query": "przesłanki odpowiedzialności",
  "maxQuotes": 3
}'

Weryfikacja kosztuje 1 request i nie uruchamia modelu generatywnego. Obsługujemy przepisy i orzeczenia. Wynik exact, corrected lub not_found dotyczy zgodności tekstowej — nie potwierdza poprawności tezy prawnej.

curl https://api.zapytajkodeks.pl/api/v1/citations/verify \
  -H "Authorization: Bearer $ZK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceId": "provision:123",
  "quotes": [
    {
      "quoteId": "cytat-1",
      "text": "Treść cytatu do porównania ze źródłem."
    }
  ]
}'

locator.start i locator.end to indeksy jednostek UTF-16 w kanonicznym tekście (koniec jest wyłączny). Używaj text.slice(start, end) w JavaScript. Dla orzeczeń tekst odpowiada polu source.text z GET; nie są to offsety w oryginalnym HTML.

Brak dopasowania cytatu jest zakończoną operacją: weryfikacja zużywa 1 request, a ekstrakcja 1 analizę z limitu AI. Może zwrócić HTTP 200 z ostrzeżeniem i error.code: QUOTE_NOT_FOUND. Nieistniejące źródło zwraca 404 i zwalnia rezerwację.

Zużycie i limity

Liczniki data (requesty) i ai (analizy AI) są niezależne i wspólne dla wszystkich kluczy jednego właściciela. Każde wywołanie endpointu danych lub konta zużywa 1 request; ekstrakcja cytatów i analiza zużywają po jednej analizie z limitu AI. Liczba zapytań w jednym wyszukiwaniu ani rozmiar aktu nie zwiększają kosztu. Wewnętrzne wyszukiwania analizy są w cenie. Każde zaakceptowane żądanie liczy się także do limitu ruchu w oknie 60 sekund.

Koszt jest rezerwowany przed wykonaniem. Błędy źródła lub wykonania zwalniają rezerwację; zakończone wyszukiwanie bez wyników nadal liczy się jako 1 request. Rezerwacje porzucone po awarii procesu wygasają po 15 minutach i są porządkowane przy kolejnym zaakceptowanym żądaniu.

curl https://api.zapytajkodeks.pl/api/v1/usage -H "Authorization: Bearer $ZK_API_KEY"

Nagłówki: X-Request-Id, X-Usage-Meter, X-Usage-Units, X-Usage-Limit, X-Usage-Remaining, X-Usage-Resets-At, X-Processing-Profile. Pozostały limit uwzględnia rezerwacje w toku i jest stanem z chwili rezerwacji. X-Usage-Units wynosi 1 dla sukcesu i 0 przy potwierdzonym zwrocie. Odczyt /usage i /capabilities również zużywa 1 zwykły request; po wyczerpaniu tego limitu skontaktuj się z operatorem.

Okres i odnowienie ustala operator; X-Usage-Resets-At wskazuje koniec bieżącego okresu, nie gwarantuje automatycznego odnowienia. Nie ma automatycznych dopłat ani przenoszenia niewykorzystanych requestów ani analiz AI. Przekroczenie puli, tempa lub równoległości zwraca 429. Limit treści całego żądania to 2 MB. Oferta API.

Błędy i ponowienia

{
  "message": "The request or AI analysis limit has been reached. Contact the operator to increase it.",
  "error_code": "QUOTA_EXCEEDED",
  "request_id": "00000000-0000-4000-8000-000000000001",
  "link": "https://zapytajkodeks.pl/dokumentacje/api#bledy"
}

Idempotencja

Dodaj Idempotency-Key (1–128 znaków: litery ASCII, cyfry, kropka, podkreślenie, dwukropek lub myślnik), szczególnie do operacji AI. Klucz jest przypisany do klucza API i operacji. To ochrona przed ponownym wykonaniem, bez odtwarzania zapisanej odpowiedzi.

Po zaakceptowaniu klucza kolejne żądanie zwraca 409 REQUEST_ALREADY_PROCESSED; zmiana znormalizowanych danych wejściowych zwraca IDEMPOTENCY_CONFLICT. Dotyczy to także operacji, która później zakończyła się błędem. Gdy świadomie zlecasz nową próbę po takim błędzie, użyj nowego klucza. Brak nagłówka oznacza niezależne żądanie i nowy koszt.

Przy ograniczeniu tempa lub równoległości respektuj Retry-After. Przy wyczerpaniu puli potrzebne jest odnowienie lub zwiększenie limitu przez operatora. Nie ponawiaj w ciemno analizy po utracie połączenia — stały klucz pozwoli uniknąć drugiego wykonania.

Przetwarzanie danych

Obecnie działa wyłącznie profil standard. Analizy korzystają z konfiguracji dostawców AI używanej przez aplikację. Treść analiz, źródła, utworzone dokumenty i metadane operacyjne mogą być zapisywane. Nie deklarujemy dla tego profilu wyłącznego przetwarzania w EOG ani braku retencji.

Przyszły profil eea_zero_retention jest uwzględniony w kontrakcie i pozostaje niedostępny. Żądanie z X-Processing-Profile: eea_zero_retention zwraca 501 przed wywołaniem usług danych i modeli. Nie przełączamy go automatycznie na standard.

Dostępne możliwości sprawdzisz przez GET /capabilities. Eksport masowy, trenowanie modeli i redystrybucja wymagają osobnej umowy. REST ma osobne limity od istniejącej usługi MCP. Skontaktuj się z nami, aby ustalić warunki integracji.