# SNOK dla deweloperów - API, OpenAPI i llms.txt

> Zasoby SNOK dla deweloperów i agentów AI: pliki maszynowe, opis OpenAPI endpointów formularzy snok.ai, uwierzytelnienie, wersjonowanie, limity i przykłady.

- Source: https://snok.ai/pl/dla-deweloperow/

---

# SNOK dla deweloperów

Pliki maszynowe i publiczne endpointy, z których korzystają formularze snok.ai.

## 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](https://snok.ai/pl/kontakt/) albo pod adresem [office@snok.ai](mailto:office@snok.ai). Przewodnik dla agentów AI publikujemy w [/llms.txt](https://snok.ai/llms.txt).

## Zasoby maszynowe

- [/openapi.json](https://snok.ai/openapi.json) - opis OpenAPI 3.1 wszystkich publicznych endpointów, kodów błędów i nagłówków.
- [/llms.txt](https://snok.ai/llms.txt) i [/llms-full.txt](https://snok.ai/llms-full.txt) - kompetencje, usługi i dane kontaktowe SNOK dla agentów AI.
- Wariant Markdown każdej strony: nagłówek `Accept: text/markdown` albo `index.md` dopisane do adresu strony.
- [/sitemap.xml](https://snok.ai/sitemap.xml), [/rss.xml](https://snok.ai/rss.xml) (wpisy polskie) i [/en/rss.xml](https://snok.ai/en/rss.xml) (wpisy angielskie).

## Endpointy

Wersja 2026-10-07. Schematy żądań i odpowiedzi opisuje [/openapi.json](https://snok.ai/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.json`
```

Odczyt 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/`
```