Czym jest to API
Strona snok.ai nie udostępnia API produktowego ani integracyjnego. Opisane niżej endpointy obsługują formularze strony, a ich kontrakt publikujemy, żeby był jawny i sprawdzalny. W sprawie usług SNOK zapraszamy do kontaktu przez formularz kontaktowy albo pod adresem office@snok.ai. Przewodnik dla agentów AI publikujemy w /llms.txt.
Zasoby maszynowe
- /openapi.json - opis OpenAPI 3.1 wszystkich publicznych endpointów, kodów błędów i nagłówków.
- /llms.txt i /llms-full.txt - kompetencje, usługi i dane kontaktowe SNOK dla agentów AI.
- Wariant Markdown każdej strony: nagłówek
Accept: text/markdownalboindex.mddopisane do adresu strony. - /sitemap.xml, /rss.xml (wpisy polskie) i /en/rss.xml (wpisy angielskie).
Endpointy
Wersja 2026-10-07. Schematy żądań i odpowiedzi opisuje /openapi.json; każda ścieżka kończy się ukośnikiem.
POST /api/contact/(submitContactForm)POST /api/apply/(submitJobApplication)POST /api/ksc-check/score/(scoreKscCheck)POST /api/ksc-check/submit/(requestKscCheckReport)POST /api/materials/request/(requestGatedMaterial)GET /api/materials/download/(downloadGatedMaterial)
Uwierzytelnienie
Odczyt opisanych plików nie wymaga uwierzytelnienia. Endpointy formularzy przyjmują żądania wyłącznie ze źródła snok.ai, a poza punktacją KSC-CHECK także z jednorazowym tokenem Cloudflare Turnstile, który otrzymuje formularz w przeglądarce. Agent AI nie otrzyma takiego tokenu, dlatego tych endpointów celowo nie można wywołać programowo. Żądanie z innego źródła dostaje odpowiedź 403 origin_forbidden.
Wersjonowanie i wycofywanie
Każda odpowiedź JSON spod /api/ niesie nagłówek API-Version: 2026-10-07, zgodny z polem info.version w specyfikacji. Klient może przypiąć wersję, wysyłając API-Version z datą. Obsługujemy każdą datę do wersji bieżącej włącznie. Data późniejsza albo wartość w złym formacie kończy się odpowiedzią 400 unsupported_version. Zmiana łamiąca kontrakt dostaje nową ścieżkę, a stara działa co najmniej 90 dni z nagłówkami Deprecation (RFC 9745) i Sunset (RFC 8594). Obecnie żadna operacja nie jest wycofywana.
Limity zapytań
Limity obowiązują per adres IP i per endpoint. Odpowiedzi niosą pola RateLimit i RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11) oraz RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset; odpowiedź 429 rate_limited dodaje Retry-After. Licznik działa w pamięci każdej instancji funkcji serwerowej, dlatego deklarowany limit jest górną granicą, której klient powinien przestrzegać.
Błędy
Każdy błąd ma postać JSON ze stałym kodem maszynowym code, komunikatem error w języku formularza, wskazówką hint po angielsku oraz polami RFC 9457: type, title i status. Nieznana ścieżka pod /api/ zwraca 404 not_found, a metoda spoza kontraktu - 405 method_not_allowed z nagłówkiem Allow.
Przykłady
Pobranie specyfikacji:
curl -s https://snok.ai/openapi.jsonOdczyt strony w Markdownie:
curl -s -H 'Accept: text/markdown' https://snok.ai/pl/oferta/Sprawdzenie kontraktu endpointu bez wysyłania danych (405 z nagłówkami Allow: POST i API-Version):
curl -si https://snok.ai/api/contact/