URL-konvenciók és ingyenes endpointok

Ha egy tipikus kérésre 404-et kapsz, valószínűleg rossz az előtag, vagy nem szabványos útvonalon keresed a Swagger UI-t. Ez az oldal rögzíti az összes kanonikus URL-t és aliast.

Útvonal-előtag

Minden endpoint a /v1/ alatt él. Más előtag nincs.

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

Ha tévedésből az /api/<endpoint> formát használtad, 404-et adunk vissza error.code = "WRONG_PREFIX" mezővel és egy tippel, így az SDK-d ezt le tudja kezelni, és megmutathatja a helyes útvonalat.

Ez nem LLM-proxy

Az AstroWay asztrológiai számítási API, nem LLM-proxy. Ha az OpenAI SDK megszokásaival érkezel, és egyszerűen a miénkre cserélnéd a base_url értékét, az nem fog működni:

❌ 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

Két okból nem tesszük közzé az AI-szolgáltatók listáját:

Az integrátor számára nem hasznosítható. Te a /v1/interpret/natal vagy a /v1/horoscope/daily endpointot hívod, a szerverünk pedig maga választ LLM-et több szolgáltató közül, automatikus fallbackkel. A szolgáltató cseréje nem változtatja meg a válasz szerkezetét, csak a latenciát és alkalmanként a megfogalmazást.
Üzemeltetési szabadság. A lánc előzetes értesítés nélkül változik (a HuggingFace kivezetése 2026-05-18-án, a NIM/ZAI hozzáadása). Ha konkrét models[] listát hirdetnénk, az de facto szerződéssé válna.

Az AI csak megvalósítási részletként van jelen a /v1/interpret/* (születési képlet, szinasztria, tranzitok), a /v1/horoscope/* (napi/heti horoszkóp), a /v1/dev-assistant (dokumentációs asszisztens) és a /v1/reports/* (PDF-narratívák) alatt. A többi 750+ endpoint determinisztikus Swiss Ephemeris, AI nélkül.

OpenAPI 3.1 specifikáció

A kanonikus cím a /v1/openapi.json. Az integrációk kényelméért aliasokat is felvettünk:

Alias	Hova	Miért létezik
`/v1/swagger.json`	301 → `/v1/openapi.json`	Swagger 2.0 / openapi-generator konvenció
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	springdoc alapértelmezés
`/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`	Swagger UI hoszt

Az interaktív Swagger UI a /v1/docs címen érhető el (a böngészős dokumentációban is tükrözve, a /docs/api/ oldalon).

Ingyenes rendszerendpointok

Ezek az útvonalak nem igényelnek API-kulcsot, és nem vonnak le kreditet: bármely frontendről, monitoringból vagy health-checkből hívhatók.

Útvonal	Mit ad vissza
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}`, gyors liveness probe
`GET /v1/health/deep`	Adatbázisonkénti elérhetőségi ellenőrzés (UptimeRobot / Pingdom számára), 503, ha legalább egy adatbázis elérhetetlen
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}`, részletes önellenőrzés SDK-k számára
`GET /v1/openapi.json`	Teljes OpenAPI 3.1 specifikáció példákkal és `x-codeSamples` mezővel
`GET /v1/docs`	Interaktív Swagger UI
`GET /v1/reference/*`	Kanonikus referenciák (jegyek, bolygók, házak, fényszögek), IP-alapú rate limit, kulcs nélkül
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Nyelvek listája és UI-szótárak widgetekhez

Ingyenes, regisztrációhoz kötött endpointok

A fiókendpointok csak JWT-tokennel érhetők el (bejelentkezéskor kapod), de nem vonnak le kreditet a csomagod egyenlegéből.

Előtag	Mi ez
`/v1/auth/*`	Regisztráció, bejelentkezés, refresh, jelszó-visszaállítás
`/v1/me`, `/v1/me/*`	Profil, statisztika, legutóbbi hívások
`/v1/keys`, `/v1/keys/*`	API-kulcsok kezelése
`/v1/admin/*`	Adminfelület (`api_role = admin` szükséges)
`/v1/messages`	Visszajelzés a widgetből (névtelenül, rate limittel)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	AI-asszisztens a dokumentációhoz (névtelenül, külön limittel)
`/v1/widget-config`	Futásidejű feature flagek a widgethez
`/v1/embed/*`	Beágyazható iframe-widgetek (IP-alapú rate limit)
`/v1/oauth/*`	Google / GitHub bejelentkezés
`/v1/books/*`	Birth Book, külön scope-os JWT (a WordPress mu-plugin adja ki)

Fizetős számítási endpointok

Minden asztrológiai számítás kreditet von le a csomagodból. Az egyes endpointok pontos költsége az Endpointok költsége oldalon található. Röviden:

Tier	Kredit	Példák
0	0	`/v1/reference/*`, nyilvános referenciák, kulcs nélkül
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog`, statikus táblázatok
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-narratívák `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	PDF-jelentések: `/v1/reports/natal`, `/v1/reports/synastry`

Gyorsítótár-kedvezmények: X-Cache: HIT (5 perces idempotency cache) esetén 0 kredit. AI-endpointoknál (/interpret/*) cache hit esetén 50% kedvezmény.

A válaszfejlécek tartalmazzák az X-Credits-Used, X-Credits-Remaining, X-Credits-Limit értékeket, így az SDK-k automatikusan követhetik az egyenleget.

A válaszok nyelve

A nyelvet a ?lang= paraméterrel vagy az Accept-Language fejléccel adod meg. 21 nyelv támogatott.

A zárt halmazokból származó mezők (jegyek, bolygók, a hét napjai, holdfázisok, a Human Design szókincse, a Tarot Nagy Árkánumainak nevei) kétszer jönnek vissza: az angol azonosító stabil szerződésként a helyén marad, mellette pedig egy localized objektum érkezik a fordítással:

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

Az angol értékeket hasonlítsd össze, a localized értékeket jelenítsd meg. Ezek a nevek a kódban lévő explicit terminustáblázatból jönnek, nem gépi fordításból: a terminológiát nem lehet szó szerint fordítani, különben a holdfázisból pénzügyi kifejezés lesz.

A Human Designban a localized.centers alatti központok kulcsai ugyanazok az azonosítók, mint a centers[].name értékei, így az összerendelés kulcs alapján történik, nem a lefordított szöveg alapján. A Tarotban ugyanezt a localized.cards végzi, a kulcs a kártya slug értéke.

A nyílt halmazokból származó mezők egyelőre angolok, és így is vannak dokumentálva: a nap bolygójának themes[] mezője, a Tarot-kártyák kulcsszavai és jelentései, a Human Design csatornáinak és kapuinak nevei. A Kis Árkánumok nevei a rang és a szín rögzített alakjaiból állnak össze, így mind a 78 lapos pakli lokalizált, és a nameLocalized értéke erre true; a mező csak ott marad false, ahol a táblázat nem tud nevet adni. A nyílt halmazokat fordítsd a saját oldaladon, vagy várd meg a külön szótárakat.

Kompakt válasz: `fields` és `precision`

Az ügynök minden elolvasott tokenért fizet. A POST /v1/chart körülbelül 32 KB-ot ad vissza, a modellnek pedig általában két oszlop kell belőle, és minden hosszúság tizennégy tizedesjeggyel érkezik ott, ahol senki sem számol ívpercnél pontosabban.

Két lekérdezési paraméter ezt az utolsó lépésben oldja meg, ezért minden endpointon működik:

fields: vesszővel elválasztott útvonalak listája, a data-hoz képest. Az útvonal a tömb minden elemére vonatkozik, így a planets.name minden bolygó nevét jelenti, nem a tömb egy kulcsát.
precision: egész szám 0 és 15 között, a válaszban szereplő összes nem egész számot kerekíti. Az egészekhez nem nyúl: egy azonosító nem mérés.

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

Ez a paraméterpár egy születési képleten 32 410 helyett 511 bájtot ad, vagyis a válasz hatvanszor kisebb.

Az az útvonal, amely semmit sem talált, nem tűnik el csendben. A válasz mellett a _fields_unmatched mezőben érkezik: a mezők egy része valóban opcionális, és egy adott válaszból hiányzik, ezért ez nem hiba. Az a lista viszont, amelyben egyetlen útvonal sem egyezett, elírás, és 400 FIELDS_UNKNOWN hibát ad a listával. Egy üres objektum a képlet helyett magabiztosan hibás válasz volna.

Mindkét paraméter a query-ben megy, nem fejlécben, és ez szándékos: a válaszgyorsítótár kulcsa a metódus, az útvonal, a törzs, a rendezett query és a csomag. Egy fejlécben megadott mód megismételné a 2026-08-22-i incidenst, amikor az Accept-Language nem volt része a kulcsnak, és egy német választ a következő kérőnek ukránként adtunk ki.

Az alakítás csak a data mezőt érinti. A boríték, a _footer és a _warning érintetlen marad.

Ugyanez működik MCP-n keresztül is. Az mcp.astroway.info minden eszköze a saját paraméterei mellett elfogadja a fields és precision paramétert, és ugyanazzal a query-vel adja tovább őket az API-nak. Egy születési képlet MCP-n keresztül 91 737 bájtot nyomott, mert az adat kétszer érkezett: behúzásokkal tagolt szövegblokként és strukturált mezőként. Ugyanazzal a három útvonallal és precision: 2 beállítással ez 1 182 bájt.

Születési képlet hívása	Bájt
MCP, ahogy 2026.09.21. előtt volt	91 737
MCP, behúzások nélkül a szövegblokkban	72 484
MCP, `precision: 2`	61 356
MCP, három útvonal a `fields`-ben és `precision: 2`	1 182
REST, három útvonal a `fields`-ben és `precision=2`	559

Ismeretlen születési idő

A végfelhasználók jelentős része nem tudja a pontos születési idejét. Ha egy feltételezett delet írsz be, és a képletet szokásos módon számolod, a válaszban megjelenik egy aszcendens és házcsúcsok, amelyek hitelesnek látszanak, de minden két óra eltérés után nagyjából egy jegyet tévednek.

Ezért a time helyett átadhatod a timeUnknown: true értéket:

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

Mit ad vissza az API ebben a módban:

Mező	Érték
`planets`	helyi délre számolva
`aspects`	kiszámolva, de a Holddal alkotott fényszögek megbízhatatlanok (lásd lent)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	magyarázó blokk: pontosan mi maradt ki, és hol lehet a Hold

A timeUnknown.moon blokk tartalmazza a Hold hosszúságát a nap elején és végén, a nap alatt bejárt ívet (11.8-15.4°), azoknak a jegyeknek a listáját, amelyekben tartózkodott, és a changesSign jelzőt. A Hold egy nap alatt jegyet válthat, ezért ezt a tartományt érdemes megmutatni a felhasználónak, nem pedig egyetlen szám mögé rejteni.

A jelzőt a /v1/chart és a /v1/synastry fogadja el (a szinasztriában bármelyik partnerre külön beállítható). A többi endpoint házaktól vagy tengelyektől függ, és 400 TIME_UNKNOWN_UNSUPPORTED választ ad: jobb egy egyértelmű hiba, mint egy csendben figyelmen kívül hagyott jelző és egy kitalált aszcendens a válaszban.

API-verziózás

A főverzió az URL-ben van (/v1/). Breaking change csak /v2/-vel jön, nem helyben. Részletek: Verziózás.

A GET /v1/version az aktuális deployt adja vissza:

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/"
# }

Az SDK-k indításkor meghívhatják ezt a hibakereséshez (“miért viselkedik hirtelen másképp”): a build_commit mező pontosan azonosítja a deployt.

A leggyakoribb hibás hívások, amelyeket látunk

90 nap éles naplóinak elemzéséből, 5 tipikus integrátori hiba:

/api/<endpoint> a /v1/<endpoint> helyett: WordPress wp-json-szokás. Most JSON 404-et adunk vissza tippel.
/v1/v1/<endpoint>: az SDK baseUrl = .../v1 beállítással van konfigurálva, és erre még ráteszi a /v1/X részt. Most 308 redirect.
/swagger.json a /v1/openapi.json helyett: Postman/Insomnia automatikus próbálkozás. Most 301 redirect.
/v1/me, /v1/auth/keys/me Authorization: Bearer <jwt> nélkül → 401. Ellenőrizd, hogy a token átmegy-e a fejlécben.
/v1/embed/natal API-kulccsal embed-token helyett → 401. Az embed-endpointok nyilvános embed-tokent fogadnak el a dashboardról, nem API-kulcsot.