Konvence URL a bezplatné endpointy

Pokud vidíš 404 na běžný požadavek, nejspíš máš špatný prefix nebo hledáš Swagger UI na nestandardní cestě. Tahle stránka shrnuje všechny kanonické URL a aliasy.

Prefix cesty

Všechny endpointy žijí pod /v1/. Jiné prefixy neexistují.

✅ 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)

Pokud jsi omylem použil /api/<endpoint>, vrátíme 404 s polem error.code = "WRONG_PREFIX" a nápovědou, takže tvoje SDK to může zpracovat a navrhnout správnou cestu.

Tohle není LLM proxy

AstroWay je API pro astrologické výpočty, ne proxy pro LLM. Pokud přicházíš se svalovou pamětí z OpenAI SDK a zkusíš jen změnit base_url na náš, nebude to fungovat:

❌ 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

Seznam AI poskytovatelů nezveřejňujeme ze dvou důvodů:

Pro integrátora to není užitečná informace. Voláš /v1/interpret/natal nebo /v1/horoscope/daily a náš server sám vybere LLM z několika poskytovatelů s automatickým fallbackem. Změna poskytovatele nemění tvar odpovědi, jen latenci a občas formulaci.
Provozní volnost. Řetězec se mění bez předchozího upozornění (vyřazení HuggingFace 2026-05-18, přidání NIM/ZAI). Kdybychom zveřejňovali konkrétní models[], stal by se z toho de facto kontrakt.

AI je přítomná jen jako implementační detail v /v1/interpret/* (natální horoskop, synastrie, tranzity), /v1/horoscope/* (denní/týdenní horoskop), /v1/dev-assistant (asistent pro dokumentaci) a /v1/reports/* (PDF narativy). Zbylých 750+ endpointů je deterministický Swiss Ephemeris bez AI.

Specifikace OpenAPI 3.1

Kanonická adresa je /v1/openapi.json. Pro pohodlí integrací jsou přidány aliasy:

Alias	Kam	Proč existuje
`/v1/swagger.json`	301 → `/v1/openapi.json`	Konvence Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Výchozí cesta 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`	Hostitel Swagger UI

Interaktivní Swagger UI je dostupné na /v1/docs (zrcadlí se také v prohlížečové dokumentaci na /docs/api/).

Bezplatné systémové endpointy

Tyto cesty nepotřebují API klíč a neodečítají kredity, takže je můžeš volat z libovolného frontendu, monitoringu nebo health-checku.

Cesta	Co vrací
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}`: rychlá liveness probe
`GET /v1/health/deep`	Kontrola dostupnosti každé DB (pro UptimeRobot / Pingdom), 503 pokud je aspoň jedna DB nedostupná
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}`: podrobná self-check pro SDK
`GET /v1/openapi.json`	Úplná specifikace OpenAPI 3.1 s příklady + `x-codeSamples`
`GET /v1/docs`	Interaktivní Swagger UI
`GET /v1/reference/*`	Kanonické číselníky (znamení, planety, domy, aspekty), IP rate limit, bez klíče
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Seznam jazyků a UI slovníky pro widgety

Bezplatné endpointy, které vyžadují registraci

Účtové endpointy jsou dostupné jen s JWT tokenem (vydává se při přihlášení), ale neodečítají kredity ze zůstatku plánu.

Prefix	Co to je
`/v1/auth/*`	Registrace, přihlášení, refresh, reset hesla
`/v1/me`, `/v1/me/*`	Profil, statistiky, nedávná volání
`/v1/keys`, `/v1/keys/*`	Správa API klíčů
`/v1/admin/*`	Administrace (vyžaduje `api_role = admin`)
`/v1/messages`	Zpětná vazba z widgetu (anonymně, rate limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI asistent pro dokumentaci (anonymně, samostatný limit)
`/v1/widget-config`	Runtime feature flagy pro widget
`/v1/embed/*`	Vložitelné iframe widgety (IP rate limit)
`/v1/oauth/*`	Přihlášení přes Google / GitHub
`/v1/books/*`	Birth Book: samostatný scope JWT (vydává ho WordPress mu-plugin)

Placené výpočetní endpointy

Všechny astrologické výpočty odečítají kredity z tvého tarifu. Přesná cena každého je na stránce Náklady na endpointy. Stručně:

Tier	Kreditů	Příklady
0	0	`/v1/reference/*`: veřejné číselníky, bez klíče
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog`: statické tabulky
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`, AI narativy `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF reporty: `/v1/reports/natal`, `/v1/reports/synastry`

Slevy za cache: X-Cache: HIT (5minutová idempotency cache) znamená 0 kreditů. AI endpointy (/interpret/*): 50% sleva při cache hit.

Hlavičky odpovědi obsahují X-Credits-Used, X-Credits-Remaining, X-Credits-Limit, takže SDK může zůstatek sledovat automaticky.

Jazyk odpovědí

Jazyk se nastavuje přes ?lang= nebo hlavičku Accept-Language. Podporovaných jazyků je 21.

Pole z uzavřených množin (znamení, planety, dny v týdnu, fáze Měsíce, slovník Human Design, názvy Velkých arkán tarotu) se vracejí dvakrát: anglický identifikátor zůstává na svém místě jako stabilní kontrakt a vedle něj přichází objekt localized s překladem:

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

Porovnávej anglické hodnoty, zobrazuj localized. Tyto názvy pocházejí z explicitní tabulky termínů v kódu, ne ze strojového překladu: terminologii nelze překládat slovo od slova, jinak se z fáze Měsíce stane finanční termín.

V Human Design mají centra v localized.centers jako klíče tytéž identifikátory jako centers[].name, takže párování probíhá podle klíče, ne podle přeloženého řetězce. V tarotu totéž dělá localized.cards, klíčem je slug karty.

Pole z otevřených množin jsou zatím anglická a takto zdokumentovaná: themes[] u planety dne, klíčová slova a významy tarotových karet, názvy kanálů a bran Human Design. Názvy Malých arkán se skládají ze zmrazených tvarů hodnosti a barvy, takže je lokalizovaný celý balíček 78 karet a nameLocalized je pro něj true; pole zůstává false jen tam, kde tabulka nedokáže název poskytnout. Otevřené množiny si překládej na své straně nebo počkej na samostatné slovníky.

Kompaktní odpověď: `fields` a `precision`

Agent platí za každý token, který přečte. POST /v1/chart vrací zhruba 32 KB, přičemž model z toho obvykle potřebuje dva sloupce, a každá délka přichází se čtrnácti desetinnými místy tam, kde nikdo nepočítá přesněji než na obloukovou minutu.

Dva parametry dotazu to řeší v posledním kroku, a proto fungují na všech endpointech:

fields: seznam cest oddělených čárkou, relativně k data. Cesta se aplikuje na každý prvek pole, takže planets.name znamená název každé planety, ne klíč pole.
precision: celé číslo od 0 do 15, zaokrouhlí všechna neceločíselná čísla v odpovědi. Celá čísla nemění: identifikátor není měření.

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}'

Tahle dvojice parametrů dává u natálního horoskopu 511 bajtů místo 32 410, tedy odpověď šedesátkrát menší.

Cesta, která nic nenašla, nemizí potichu. Přijde v poli _fields_unmatched vedle odpovědi: část polí je opravdu nepovinná a v konkrétní odpovědi chybí, takže to není chyba. Zato seznam, kde nesouhlasila ani jedna cesta, je překlep a vrací 400 FIELDS_UNKNOWN s výčtem. Prázdný objekt místo horoskopu by byl sebejistě špatnou odpovědí.

Oba parametry jdou v query, ne v hlavičce, a to záměrně: cache odpovědí se klíčuje podle metody, cesty, těla, seřazeného query a plánu. Režim v hlavičce by zopakoval incident z 2026-08-22, kdy Accept-Language nebyl součástí klíče a německá odpověď se dalšímu volajícímu vrátila jako ukrajinská.

Tvarování se týká jen data. Obálka, _footer a _warning zůstávají celé.

Totéž funguje přes MCP. Každý nástroj na mcp.astroway.info přijímá fields a precision vedle svých parametrů a předává je API stejným query. Natální horoskop přes MCP vážil 91 737 bajtů, protože data přicházela dvakrát: jako textový blok s odsazením a jako strukturované pole. Se stejnými třemi cestami a precision: 2 je to 1 182 bajtů.

Volání natálního horoskopu	Bajtů
MCP, jak to bylo před 21.09.2026	91 737
MCP, bez odsazení v textovém bloku	72 484
MCP, `precision: 2`	61 356
MCP, tři cesty ve `fields` plus `precision: 2`	1 182
REST, tři cesty ve `fields` plus `precision=2`	559

Neznámý čas narození

Značná část koncových uživatelů nezná přesný čas svého narození. Pokud dosadíš smluvené poledne a spočítáš horoskop jako obvykle, objeví se v odpovědi ascendent a hroty domů, které vypadají věrohodně, ale mýlí se zhruba o jedno znamení za každé dvě hodiny chyby.

Proto můžeš místo time poslat 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 API v tomto režimu vrací:

Pole	Hodnota
`planets`	spočítané na místní poledne
`aspects`	spočítané, ale aspekty s Měsícem jsou nespolehlivé (viz níže)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	blok s vysvětlením: co přesně je vynecháno a kde může být Měsíc

Blok timeUnknown.moon obsahuje délku Měsíce na začátku a konci dne, oblouk urazený za den (11.8-15.4°), výčet znamení, ve kterých se nacházel, a příznak changesSign. Měsíc může během dne změnit znamení, proto je vhodné tento rozsah uživateli ukázat, a ne ho schovávat za jedno číslo.

Příznak přijímají /v1/chart a /v1/synastry (v synastrii ho lze nastavit každému z partnerů zvlášť). Ostatní endpointy závisí na domech nebo úhlech a odpovídají 400 TIME_UNKNOWN_UNSUPPORTED: lepší explicitní chyba než potichu ignorovaný příznak a vymyšlený ascendent v odpovědi.

Verzování API

Major verze je v URL (/v1/). Breaking changes přicházejí jen s /v2/, ne na místě. Podrobnosti: Verzování.

GET /v1/version vrací aktuální nasazení:

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 to může volat při startu kvůli ladění “proč se to najednou chová jinak”: pole build_commit přesně identifikuje nasazení.

Chybná volání, která vidíme nejčastěji

Z analýzy produkčních logů za 90 dní, 5 typických chyb integrátorů:

/api/<endpoint> místo /v1/<endpoint>: zvyk z WordPress wp-json. Teď vracíme JSON 404 s nápovědou.
/v1/v1/<endpoint>: SDK nakonfigurované s baseUrl = .../v1 přidává navrch /v1/X. Teď 308 redirect.
/swagger.json místo /v1/openapi.json: automatické zkoušení v Postman/Insomnia. Teď 301 redirect.
/v1/me, /v1/auth/keys/me bez Authorization: Bearer <jwt> → 401. Zkontroluj, zda se token posílá v hlavičce.
/v1/embed/natal s API klíčem místo embed tokenu → 401. Embed endpointy přijímají veřejný embed token z dashboardu, ne API klíč.