Konwencje URL i darmowe endpointy

Jeśli widzisz 404 przy typowym żądaniu - najpewniej prefiks jest niepoprawny albo szukasz Swagger UI pod niestandardową ścieżką. Ta strona zbiera wszystkie kanoniczne URL i aliasy.

Prefiks ścieżki

Wszystkie endpointy żyją pod /v1/. Innych prefiksów nie ma.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

Jeśli omyłkowo użyłeś /api/<endpoint>, zwracamy 404 z polem error.code = "WRONG_PREFIX" i podpowiedzią - Twój SDK może to obsłużyć i wskazać poprawną ścieżkę.

To nie jest proxy LLM

AstroWay to API obliczeń astrologicznych, a nie proxy dla LLM. Jeśli przychodzisz z nawykami z OpenAI SDK i próbujesz po prostu zmienić base_url na nasz - to nie zadziała:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

Nie publikujemy listy dostawców AI z dwóch powodów:

Integrator nie może z tym nic zrobić. Wywołujesz /v1/interpret/natal albo /v1/horoscope/daily - nasz serwer sam wybiera LLM spośród kilku dostawców z automatycznym fallbackiem. Zmiana dostawcy nie zmienia kształtu odpowiedzi, tylko latencję i od czasu do czasu sformułowania.
Swoboda operacyjna. Łańcuch zmienia się bez uprzedzenia (wyłączenie HuggingFace 2026-05-18, dodanie NIM/ZAI). Gdybyśmy ogłaszali konkretne models[], stawałoby się to de facto kontraktem.

AI występuje wyłącznie jako szczegół implementacji w /v1/interpret/* (urodzeniowy, synastria, tranzyty), /v1/horoscope/* (horoskop dzienny/tygodniowy), /v1/dev-assistant (asystent do dokumentacji) i /v1/reports/* (narracje PDF). Pozostałe 750+ endpointów to deterministyczny Swiss Ephemeris bez AI.

Specyfikacja OpenAPI 3.1

Kanoniczny adres to /v1/openapi.json. Dla wygody integracji dodano aliasy:

Alias	Dokąd	Dlaczego istnieje
`/v1/swagger.json`	301 → `/v1/openapi.json`	Konwencja Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Domyślna ścieżka springdoc
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`, `/v1/swagger-ui`, `/v1/swagger-ui.html`	302 → `/v1/docs`	Host Swagger UI

Interaktywny Swagger UI jest dostępny pod /v1/docs (odzwierciedlony też w dokumentacji przeglądarkowej na /docs/api/).

Darmowe endpointy systemowe

Te ścieżki nie wymagają klucza API i nie pobierają kredytów - można je wywoływać z dowolnego frontendu, monitoringu czy health-checku.

Ścieżka	Co zwraca
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - szybka sonda liveness
`GET /v1/health/deep`	Sprawdzenie osiągalności każdej bazy (dla UptimeRobot / Pingdom), 503, jeśli choć jedna baza jest niedostępna
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - szczegółowy self-check dla SDK
`GET /v1/openapi.json`	Pełna specyfikacja OpenAPI 3.1 z przykładami + `x-codeSamples`
`GET /v1/docs`	Interaktywny Swagger UI
`GET /v1/reference/*`	Kanoniczne słowniki (znaki, planety, domy, aspekty) - limit per IP, bez klucza
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Lista języków i słowniki UI - dla widżetów

Darmowe endpointy wymagające rejestracji

Endpointy kont są dostępne tylko z tokenem JWT (wydawanym przy logowaniu), ale nie pobierają kredytów z budżetu planu.

Prefiks	Co to jest
`/v1/auth/*`	Rejestracja, logowanie, refresh, reset hasła
`/v1/me`, `/v1/me/*`	Profil, statystyki, ostatnie wywołania
`/v1/keys`, `/v1/keys/*`	Zarządzanie kluczami API
`/v1/admin/*`	Panel administracyjny (wymaga `api_role = admin`)
`/v1/messages`	Informacja zwrotna z widżetu (anonimowo, rate-limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Asystent AI do dokumentacji (anonimowo, osobny limit)
`/v1/widget-config`	Runtime feature-flags dla widżetu
`/v1/embed/*`	Osadzane widżety iframe (limit per IP)
`/v1/oauth/*`	Logowanie przez Google / GitHub
`/v1/books/*`	Birth Book - osobny JWT ze scope (wydawany przez mu-plugin WordPress)

Płatne endpointy obliczeniowe

Wszystkie obliczenia astrologiczne pobierają kredyty z Twojego planu taryfowego. Dokładny koszt każdego - na stronie Koszt endpointów. W skrócie:

Tier	Kredytów	Przykłady
0	0	`/v1/reference/*` - publiczne słowniki, bez klucza
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - tabele statyczne
1	10	`/v1/planets`, `/v1/sun-times`, `/v1/moon-phase`
2	20	`/v1/chart`, `/v1/harmonics`, `/v1/horary`
3	50	`/v1/synastry`, `/v1/progressions`, `/v1/acg`
4	100	`/v1/transit-calendar`, `/v1/group-synastry`
5	250	`/v1/rectification/trutine`, narracje AI `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Raporty PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Zniżki za cache: X-Cache: HIT (5-minutowy cache idempotentności) - 0 kredytów. Endpointy AI (/interpret/*) - 50% zniżki przy cache hit.

Nagłówki odpowiedzi zawierają X-Credits-Used, X-Credits-Remaining, X-Credits-Limit - SDK mogą automatycznie śledzić saldo.

Język odpowiedzi

Język ustawia się przez ?lang= albo nagłówek Accept-Language. Obsługiwanych jest 21 języków.

Pola ze zbiorów zamkniętych (znaki, planety, dni tygodnia, fazy Księżyca, słownik Human Design, nazwy Arkanów Wielkich Tarota) są zwracane dwukrotnie: angielski identyfikator zostaje na swoim miejscu jako stabilny kontrakt, a obok przychodzi obiekt localized z tłumaczeniem:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

Porównuj wartości angielskie, wyświetlaj localized. Te nazwy pochodzą z jawnej tabeli terminów w kodzie, a nie z tłumaczenia maszynowego: terminologii nie można tłumaczyć słowo w słowo, inaczej faza Księżyca zamienia się w termin finansowy.

W Human Design centra w localized.centers mają jako klucze te same identyfikatory co centers[].name, więc dopasowanie odbywa się po kluczu, a nie po przetłumaczonym ciągu. W Tarocie to samo robi localized.cards, kluczem jest slug karty.

Pola ze zbiorów otwartych są na razie angielskie i udokumentowane jako takie: themes[] w planecie dnia, słowa kluczowe i znaczenia kart Tarota, nazwy kanałów i bram Human Design. Nazwy Arkanów Małych są składane z zamrożonych form rangi i koloru, więc zlokalizowana jest cała talia 78 kart, a nameLocalized ma dla niej wartość true; pole zostaje false tylko tam, gdzie tabela nie jest w stanie podać nazwy. Zbiory otwarte tłumacz po swojej stronie albo poczekaj na osobne słowniki.

Kompaktowa odpowiedź: `fields` i `precision`

Agent płaci za każdy token, który czyta. POST /v1/chart zwraca około 32 KB, a modelowi zwykle potrzebne są z tego dwie kolumny, przy czym każda długość ekliptyczna przychodzi z czternastoma miejscami po przecinku tam, gdzie nikt nie buduje dokładniej niż do minuty kątowej.

Dwa parametry zapytania rozwiązują to na ostatnim kroku, więc działają na wszystkich endpointach:

fields - lista ścieżek rozdzielonych przecinkami, względem data. Ścieżka jest stosowana do każdego elementu tablicy, więc planets.name oznacza nazwę każdej planety, a nie klucz tablicy.
precision - liczba całkowita od 0 do 15, zaokrągla wszystkie liczby niecałkowite w odpowiedzi. Całkowitych nie rusza: identyfikator to nie pomiar.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

Ta para parametrów na kosmogramie urodzeniowym daje 511 bajtów zamiast 32 410, czyli odpowiedź jest sześćdziesiąt razy mniejsza.

Ścieżka, która niczego nie znalazła, nie znika po cichu. Przychodzi w polu _fields_unmatched obok odpowiedzi: część pól jest naprawdę opcjonalna i nieobecna w konkretnej odpowiedzi, więc to nie jest błąd. Natomiast lista, w której nie pasowała żadna ścieżka, to literówka i zwraca 400 FIELDS_UNKNOWN z wyliczeniem. Pusty obiekt zamiast horoskopu byłby pewną siebie błędną odpowiedzią.

Oba parametry idą w query, a nie w nagłówku, i to celowo: cache odpowiedzi jest kluczowany metodą, ścieżką, body, posortowanym query i planem. Tryb w nagłówku powtórzyłby incydent z 2026-08-22, gdy Accept-Language nie wchodził do klucza i niemiecką odpowiedź oddano następnemu klientowi jako ukraińską.

Kształtowanie dotyczy tylko data. Koperta, _footer i _warning pozostają nietknięte.

To samo działa przez MCP. Każde narzędzie na mcp.astroway.info przyjmuje fields i precision obok swoich parametrów i przekazuje je do API tym samym query. Kosmogram urodzeniowy przez MCP ważył 91 737 bajtów, bo dane przychodziły dwa razy: jako blok tekstowy z wcięciami i jako pole strukturalne. Z tymi samymi trzema ścieżkami i precision: 2 to 1 182 bajty.

Wywołanie kosmogramu urodzeniowego	Bajtów
MCP, jak było przed 21.09.2026	91 737
MCP, bez wcięć w bloku tekstowym	72 484
MCP, `precision: 2`	61 356
MCP, trzy ścieżki w `fields` plus `precision: 2`	1 182
REST, trzy ścieżki w `fields` plus `precision=2`	559

Nieznana godzina urodzenia

Znaczna część użytkowników końcowych nie zna dokładnej godziny urodzenia. Jeśli podstawić umowne południe i policzyć horoskop jak zwykle, w odpowiedzi pojawią się ascendent i wierzchołki domów, które wyglądają wiarygodnie, ale mylą się mniej więcej o znak na każde dwie godziny błędu.

Dlatego zamiast time można przekazać timeUnknown: true:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

Co zwraca API w tym trybie:

Pole	Wartość
`planets`	obliczone na lokalne południe
`aspects`	obliczone, ale aspekty z Księżycem są niepewne (patrz niżej)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	blok z wyjaśnieniem: co dokładnie pominięto i gdzie może być Księżyc

Blok timeUnknown.moon zawiera długość Księżyca na początek i koniec doby, łuk przebyty w ciągu doby (11.8-15.4°), listę znaków, w których przebywał, i flagę changesSign. Księżyc może w ciągu doby zmienić znak, więc ten zakres warto pokazać użytkownikowi, a nie ukrywać za jedną liczbą.

Flagę przyjmują /v1/chart i /v1/synastry (w synastrii można ją ustawić każdemu z partnerów osobno). Pozostałe endpointy zależą od domów lub osi i odpowiadają 400 TIME_UNKNOWN_UNSUPPORTED: lepszy jawny błąd niż po cichu zignorowana flaga i zmyślony ascendent w odpowiedzi.

Wersjonowanie API

Wersja major w URL (/v1/). Zmiany łamiące kompatybilność przychodzą tylko z /v2/, nie in-place. Szczegóły - Wersjonowanie.

GET /v1/version zwraca bieżący deploy:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

SDK mogą wywoływać to na starcie przy debugowaniu “dlaczego nagle inne zachowanie” - pole build_commit dokładnie identyfikuje deploy.

Błędne wywołania, które widzimy najczęściej

Z analizy logów produkcyjnych z 90 dni, 5 typowych błędów integratorów:

/api/<endpoint> zamiast /v1/<endpoint>: nawyk z WordPress wp-json. Teraz zwracamy JSON 404 z podpowiedzią.
/v1/v1/<endpoint>: SDK skonfigurowany z baseUrl = .../v1 dokleja na wierzch /v1/X. Teraz 308 redirect.
/swagger.json zamiast /v1/openapi.json: auto-probe w Postman/Insomnia. Teraz 301 redirect.
/v1/me, /v1/auth/keys/me bez Authorization: Bearer <jwt> → 401. Sprawdź, czy token jest przekazywany w nagłówku.
/v1/embed/natal z kluczem API zamiast tokenu embed → 401. Endpointy embed przyjmują publiczny token embed z panelu, a nie klucz API.