Convenții URL și endpoint-uri gratuite

Dacă primești 404 la o cerere obișnuită, cel mai probabil prefixul e greșit sau cauți Swagger UI la o cale nestandard. Această pagină fixează toate URL-urile canonice și aliasurile.

Prefixul căii

Toate endpoint-urile se află sub /v1/. Nu există alte prefixe.

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

Dacă ai folosit din greșeală /api/<endpoint>, returnăm 404 cu câmpul error.code = "WRONG_PREFIX" și un indiciu - SDK-ul tău poate trata asta și sugera calea corectă.

Nu este un proxy LLM

AstroWay este un API de calcule astrologice, nu un proxy pentru LLM. Dacă vii cu muscle memory de la OpenAI SDK și încerci doar să schimbi base_url cu al nostru, nu va funcționa:

❌ 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

Nu publicăm lista furnizorilor AI din două motive:

Nu e actionable pentru integrator. Apelezi /v1/interpret/natal sau /v1/horoscope/daily - serverul nostru alege singur LLM-ul dintre mai mulți furnizori, cu fallback automat. Schimbarea furnizorului nu schimbă forma răspunsului, doar latența și ocazional formularea.
Libertate operațională. Lanțul se schimbă fără preaviz (excluderea HuggingFace pe 2026-05-18, adăugarea NIM/ZAI). Dacă am anunța un models[] concret, ar deveni de facto un contract.

AI-ul este prezent doar ca detaliu de implementare în /v1/interpret/* (natală, sinastrie, tranzite), /v1/horoscope/* (horoscop zilnic/săptămânal), /v1/dev-assistant (asistent pentru documentație) și /v1/reports/* (narațiuni PDF). Restul de 750+ endpoint-uri sunt Swiss Ephemeris determinist, fără AI.

Specificația OpenAPI 3.1

Adresa canonică este /v1/openapi.json. Pentru comoditatea integrărilor am adăugat aliasuri:

Alias	Unde	De ce există
`/v1/swagger.json`	301 → `/v1/openapi.json`	Convenția Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Implicit în 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`	Gazda Swagger UI

Swagger UI interactiv este disponibil la /v1/docs (reflectat și în documentația din browser la /docs/api/).

Endpoint-uri de sistem gratuite

Aceste căi nu necesită cheie API și nu consumă credite - le poți apela din orice frontend, monitorizare sau health-check.

Cale	Ce returnează
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - liveness probe rapid
`GET /v1/health/deep`	Verificare de accesibilitate per bază de date (pentru UptimeRobot / Pingdom), 503 dacă măcar o bază de date e indisponibilă
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - self-check detaliat pentru SDK
`GET /v1/openapi.json`	Specificația OpenAPI 3.1 completă cu exemple + `x-codeSamples`
`GET /v1/docs`	Swagger UI interactiv
`GET /v1/reference/*`	Referințe canonice (semne, planete, case, aspecte) - rate limit pe IP, fără cheie
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Lista limbilor și dicționarele UI - pentru widget-uri

Endpoint-uri gratuite care necesită înregistrare

Endpoint-urile de cont sunt disponibile doar cu token JWT (emis la autentificare), dar nu consumă credite din soldul planului.

Prefix	Ce este
`/v1/auth/*`	Înregistrare, autentificare, refresh, resetarea parolei
`/v1/me`, `/v1/me/*`	Profil, statistici, apeluri recente
`/v1/keys`, `/v1/keys/*`	Gestionarea cheilor API
`/v1/admin/*`	Panou de administrare (necesită `api_role = admin`)
`/v1/messages`	Feedback din widget (anonim, rate limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Asistent AI pentru documentație (anonim, limită separată)
`/v1/widget-config`	Feature flags la runtime pentru widget
`/v1/embed/*`	Widget-uri iframe încorporabile (rate limit pe IP)
`/v1/oauth/*`	Autentificare Google / GitHub
`/v1/books/*`	Birth Book - JWT cu scope separat (emis de mu-plugin-ul WordPress)

Endpoint-uri de calcul plătite

Toate calculele astrologice consumă credite din planul tău tarifar. Costul exact al fiecăruia este pe pagina Costul fiecărui endpoint. Pe scurt:

Tier	Credite	Exemple
0	0	`/v1/reference/*` - referințe publice, fără cheie
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - tabele statice
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`, narațiuni AI `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Rapoarte PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Reduceri de cache: X-Cache: HIT (cache de idempotency de 5 min) - 0 credite. Endpoint-urile AI (/interpret/*) - reducere de 50% la cache hit.

Antetele răspunsului conțin X-Credits-Used, X-Credits-Remaining, X-Credits-Limit - SDK-urile pot urmări automat soldul.

Limba răspunsurilor

Limba se setează prin ?lang= sau prin antetul Accept-Language. Sunt suportate 21 de limbi.

Câmpurile din mulțimi închise (semne, planete, zile ale săptămânii, fazele Lunii, vocabularul Human Design, numele Arcanelor Majore din Tarot) sunt returnate de două ori: identificatorul englezesc rămâne la locul lui ca un contract stabil, iar alături vine un obiect localized cu traducerea:

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

Compară valorile englezești, afișează localized. Aceste nume vin dintr-un tabel explicit de termeni din cod, nu din traducere automată: terminologia nu poate fi tradusă cuvânt cu cuvânt, altfel faza Lunii devine un termen financiar.

În Human Design, centrele din localized.centers au drept chei aceiași identificatori ca centers[].name, deci corespondența se face după cheie, nu după șirul tradus. În Tarot, același lucru îl face localized.cards, cheia fiind slug-ul cărții.

Câmpurile din mulțimi deschise sunt deocamdată în engleză și documentate ca atare: themes[] la planeta zilei, cuvintele-cheie și semnificațiile cărților de Tarot, numele canalelor și porților Human Design. Numele Arcanelor Minore sunt compuse din forme înghețate de rang și culoare, deci întregul pachet de 78 de cărți este localizat, iar nameLocalized este true pentru el; câmpul rămâne false doar acolo unde tabelul nu poate da un nume. Mulțimile deschise traduce-le de partea ta sau așteaptă dicționarele separate.

Răspuns compact: `fields` și `precision`

Un agent plătește pentru fiecare token pe care îl citește. POST /v1/chart returnează circa 32 KB, iar modelului îi trebuie de obicei două coloane din ele, și fiecare longitudine vine cu paisprezece zecimale acolo unde nimeni nu construiește mai precis de un minut de arc.

Doi parametri de query rezolvă asta la ultimul pas, deci funcționează pe toate endpoint-urile:

fields - listă de căi separate prin virgulă, relative la data. Calea se aplică fiecărui element al unui array, deci planets.name înseamnă numele fiecărei planete, nu o cheie a array-ului.
precision - un întreg de la 0 la 15, rotunjește toate numerele neîntregi din răspuns. Pe cele întregi nu le atinge: un identificator nu este o măsurătoare.

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

Această pereche de parametri dă pe o hartă natală 511 octeți în loc de 32 410, adică un răspuns de șaizeci de ori mai mic.

O cale care n-a găsit nimic nu dispare pe tăcute. Ea apare în câmpul _fields_unmatched alături de răspuns: o parte din câmpuri sunt într-adevăr opționale și lipsesc dintr-un răspuns anume, deci nu e o eroare. În schimb, o listă în care nu s-a potrivit nicio cale este o greșeală de tastare și returnează 400 FIELDS_UNKNOWN cu enumerarea lor. Un obiect gol în locul hărții ar fi un răspuns greșit dat cu încredere.

Ambii parametri merg în query, nu în antet, și asta intenționat: cache-ul răspunsurilor are cheia formată din metodă, cale, corp, query sortat și plan. Un mod în antet ar fi repetat incidentul din 2026-08-22, când Accept-Language nu intra în cheie și un răspuns în germană a fost servit următorului client drept ucrainean.

Modelarea se aplică doar pe data. Plicul, _footer și _warning rămân întregi.

Același lucru funcționează prin MCP. Fiecare instrument de pe mcp.astroway.info acceptă fields și precision alături de parametrii săi și îi transmite API-ului în același query. Harta natală prin MCP cântărea 91 737 de octeți, pentru că datele veneau de două ori: ca bloc de text indentat și ca câmp structurat. Cu aceleași trei căi și precision: 2 sunt 1 182 de octeți.

Apel de hartă natală	Octeți
MCP, ca înainte de 21.09.2026	91 737
MCP, fără indentare în blocul de text	72 484
MCP, `precision: 2`	61 356
MCP, trei căi în `fields` plus `precision: 2`	1 182
REST, trei căi în `fields` plus `precision=2`	559

Ora nașterii necunoscută

O parte importantă a utilizatorilor finali nu își știe ora exactă a nașterii. Dacă pui o amiază convențională și calculezi harta ca de obicei, în răspuns apar un ascendent și cuspizi ale caselor care arată credibil, dar greșesc cu aproximativ un semn pentru fiecare două ore de eroare.

De aceea, în locul lui time poți trimite 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}'

Ce returnează API-ul în acest mod:

Câmp	Valoare
`planets`	calculate pentru amiaza locală
`aspects`	calculate, dar aspectele cu Luna nu sunt de încredere (vezi mai jos)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	un bloc cu explicații: ce anume a fost omis și unde poate fi Luna

Blocul timeUnknown.moon conține longitudinea Lunii la începutul și la sfârșitul zilei, arcul parcurs într-o zi (11.8-15.4°), lista semnelor în care s-a aflat și indicatorul changesSign. Într-o zi Luna poate schimba semnul, de aceea acest interval merită arătat utilizatorului, nu ascuns în spatele unui singur număr.

Indicatorul este acceptat de /v1/chart și /v1/synastry (în sinastrie îl poți seta separat pentru oricare dintre parteneri). Celelalte endpoint-uri depind de case sau de unghiuri și răspund cu 400 TIME_UNKNOWN_UNSUPPORTED: mai bine o eroare explicită decât un indicator ignorat pe tăcute și un ascendent inventat în răspuns.

Versionarea API-ului

Versiunea major în URL (/v1/). Schimbările breaking vin doar cu /v2/, nu in-place. Detalii - Versionare.

GET /v1/version returnează deploy-ul curent:

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-urile îl pot apela la pornire pentru a depana “de ce s-a schimbat brusc comportamentul” - câmpul build_commit identifică exact deploy-ul.

Apelurile greșite pe care le vedem cel mai des

Din analiza logurilor de producție pe 90 de zile, 5 greșeli tipice ale integratorilor:

/api/<endpoint> în loc de /v1/<endpoint>: obicei din WordPress wp-json. Acum returnăm un JSON 404 cu hint.
/v1/v1/<endpoint>: SDK-ul e configurat cu baseUrl = .../v1 și adaugă /v1/X deasupra. Acum 308 redirect.
/swagger.json în loc de /v1/openapi.json: auto-probe din Postman/Insomnia. Acum 301 redirect.
/v1/me, /v1/auth/keys/me fără Authorization: Bearer <jwt> → 401. Verifică dacă tokenul este transmis în antet.
/v1/embed/natal cu cheie API în loc de token embed → 401. Endpoint-urile embed acceptă un token embed public din dashboard, nu o cheie API.