Convenzioni URL ed endpoint gratuiti

Se ricevi un 404 su una richiesta tipica, molto probabilmente il prefisso è sbagliato oppure stai cercando Swagger UI su un percorso non standard. Questa pagina elenca tutti gli URL canonici e gli alias.

Prefisso del percorso

Tutti gli endpoint vivono sotto /v1/. Non esistono altri prefissi.

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

Se per errore hai usato /api/<endpoint>, restituiamo 404 con il campo error.code = "WRONG_PREFIX" e un suggerimento: il tuo SDK può gestirlo e indicare il percorso corretto.

Non è un proxy LLM

AstroWay è un’API di calcoli astrologici, non un proxy per LLM. Se arrivi con la memoria muscolare dell’SDK di OpenAI e provi semplicemente a cambiare base_url con il nostro, non funzionerà:

❌ 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

Non pubblichiamo l’elenco dei provider AI per due motivi:

Non serve a chi integra. Chiami /v1/interpret/natal o /v1/horoscope/daily, e il nostro server sceglie da solo l’LLM tra diversi provider con fallback automatico. Il cambio di provider non modifica la forma della risposta, solo la latenza e qualche occasionale differenza di formulazione.
Libertà operativa. La catena cambia senza preavviso (esclusione di HuggingFace il 2026-05-18, aggiunta di NIM/ZAI). Se annunciassimo un models[] concreto, diventerebbe di fatto un contratto.

L’AI è presente solo come dettaglio di implementazione in /v1/interpret/* (natale, sinastria, transiti), /v1/horoscope/* (oroscopo giornaliero/settimanale), /v1/dev-assistant (assistente per la documentazione) e /v1/reports/* (narrazioni PDF). Gli altri 750+ endpoint sono Swiss Ephemeris deterministico, senza AI.

Specifica OpenAPI 3.1

L’indirizzo canonico è /v1/openapi.json. Per comodità delle integrazioni sono stati aggiunti degli alias:

Alias	Destinazione	Perché esiste
`/v1/swagger.json`	301 → `/v1/openapi.json`	Convenzione Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Default di 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 di Swagger UI

Lo Swagger UI interattivo è disponibile su /v1/docs (e rispecchiato anche nella documentazione del browser su /docs/api/).

Endpoint di sistema gratuiti

Questi percorsi non richiedono una chiave API e non consumano crediti: puoi chiamarli da qualsiasi frontend, sistema di monitoraggio o health check.

Percorso	Cosa restituisce
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - liveness probe rapido
`GET /v1/health/deep`	Controllo di raggiungibilità per ogni DB (per UptimeRobot / Pingdom), 503 se almeno un DB non è disponibile
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - self-check dettagliato per gli SDK
`GET /v1/openapi.json`	Specifica OpenAPI 3.1 completa con esempi + `x-codeSamples`
`GET /v1/docs`	Swagger UI interattivo
`GET /v1/reference/*`	Riferimenti canonici (segni, pianeti, case, aspetti) - rate limit per IP, senza chiave
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Elenco delle lingue e dizionari UI - per i widget

Endpoint gratuiti che richiedono la registrazione

Gli endpoint dell’account sono accessibili solo con un token JWT (rilasciato al login), ma non consumano crediti dal saldo del piano.

Prefisso	Cos’è
`/v1/auth/*`	Registrazione, login, refresh, reset della password
`/v1/me`, `/v1/me/*`	Profilo, statistiche, chiamate recenti
`/v1/keys`, `/v1/keys/*`	Gestione delle chiavi API
`/v1/admin/*`	Pannello di amministrazione (richiede `api_role = admin`)
`/v1/messages`	Feedback dal widget (anonimo, rate limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Assistente AI per la documentazione (anonimo, limite separato)
`/v1/widget-config`	Feature flag runtime per il widget
`/v1/embed/*`	Widget iframe incorporabili (rate limit per IP)
`/v1/oauth/*`	Login con Google / GitHub
`/v1/books/*`	Birth Book - JWT con scope dedicato (rilasciato dal mu-plugin di WordPress)

Endpoint di calcolo a pagamento

Tutti i calcoli astrologici consumano crediti del tuo piano tariffario. Il costo esatto di ciascuno è nella pagina Costo degli endpoint. In breve:

Tier	Crediti	Esempi
0	0	`/v1/reference/*` - riferimenti pubblici, senza chiave
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - tabelle statiche
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`, narrazioni AI `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Report PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Sconti cache: X-Cache: HIT (cache di idempotenza di 5 minuti) - 0 crediti. Endpoint AI (/interpret/*) - 50% di sconto su cache hit.

Gli header di risposta contengono X-Credits-Used, X-Credits-Remaining, X-Credits-Limit: gli SDK possono tenere traccia del saldo automaticamente.

Lingua delle risposte

La lingua si imposta con ?lang= o con l’header Accept-Language. Sono supportate 21 lingue.

I campi degli insiemi chiusi (segni, pianeti, giorni della settimana, fasi lunari, vocabolario di Human Design, nomi degli Arcani Maggiori dei Tarocchi) vengono restituiti due volte: l’identificatore inglese resta al suo posto come contratto stabile, e accanto arriva un oggetto localized con la traduzione:

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

Confronta i valori inglesi, mostra localized. Questi nomi provengono da una tabella esplicita di termini nel codice, non da una traduzione automatica: la terminologia non si può tradurre parola per parola, altrimenti una fase lunare diventa un termine finanziario.

In Human Design i centri in localized.centers hanno come chiavi gli stessi identificatori di centers[].name, quindi l’abbinamento avviene per chiave e non per stringa tradotta. Nei Tarocchi fa lo stesso localized.cards, con chiave lo slug della carta.

I campi degli insiemi aperti per ora sono in inglese e documentati come tali: themes[] nel pianeta del giorno, parole chiave e significati delle carte dei Tarocchi, nomi di canali e porte di Human Design. I nomi degli Arcani Minori sono composti da forme fisse di rango e seme, quindi l’intero mazzo di 78 carte è localizzato e nameLocalized per esso vale true; il campo resta false solo dove la tabella non può fornire un nome. Traduci gli insiemi aperti dalla tua parte oppure attendi dizionari dedicati.

Risposta compatta: `fields` e `precision`

Un agente paga ogni token che legge. POST /v1/chart restituisce circa 32 KB, mentre al modello di solito servono due colonne, e ogni longitudine arriva con quattordici cifre decimali là dove nessuno costruisce con precisione superiore al minuto d’arco.

Due parametri di query risolvono il problema all’ultimo passaggio, quindi funzionano su tutti gli endpoint:

fields - un elenco di percorsi separati da virgola, relativi a data. Il percorso si applica a ogni elemento di un array, quindi planets.name significa il nome di ogni pianeta, non una chiave dell’array.
precision - un intero da 0 a 15, arrotonda tutti i numeri non interi della risposta. Gli interi non vengono toccati: un identificatore non è una misura.

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

Questa coppia di parametri sulla carta natale dà 511 byte invece di 32 410, cioè una risposta sessanta volte più piccola.

Un percorso che non ha trovato nulla non sparisce in silenzio. Arriva nel campo _fields_unmatched accanto alla risposta: alcuni campi sono davvero facoltativi e assenti in una data risposta, quindi non è un errore. Invece un elenco in cui non corrisponde nessun percorso è un refuso, e restituisce 400 FIELDS_UNKNOWN con l’elenco. Un oggetto vuoto al posto della carta sarebbe una risposta sbagliata data con sicurezza.

Entrambi i parametri vanno nella query e non in un header, ed è voluto: la cache delle risposte usa come chiave metodo, percorso, body, query ordinata e piano. Una modalità nell’header ripeterebbe l’incidente del 2026-08-22, quando Accept-Language non faceva parte della chiave e una risposta in tedesco è stata servita alla richiesta successiva come se fosse in ucraino.

Il filtraggio riguarda solo data. L’envelope, _footer e _warning restano intatti.

Lo stesso funziona tramite MCP. Ogni strumento su mcp.astroway.info accetta fields e precision accanto ai propri parametri e li passa all’API con la stessa query. La carta natale tramite MCP pesava 91 737 byte perché i dati arrivavano due volte: come blocco di testo indentato e come campo strutturato. Con gli stessi tre percorsi e precision: 2 sono 1 182 byte.

Chiamata della carta natale	Byte
MCP, come prima del 21.09.2026	91 737
MCP, senza indentazione nel blocco di testo	72 484
MCP, `precision: 2`	61 356
MCP, tre percorsi in `fields` più `precision: 2`	1 182
REST, tre percorsi in `fields` più `precision=2`	559

Ora di nascita sconosciuta

Una parte consistente degli utenti finali non conosce l’ora esatta di nascita. Se si inserisce un mezzogiorno convenzionale e si calcola la carta come al solito, nella risposta compaiono un ascendente e delle cuspidi delle case che sembrano attendibili, ma sbagliano di circa un segno ogni due ore di errore.

Per questo, al posto di time si può passare 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}'

Cosa restituisce l’API in questa modalità:

Campo	Valore
`planets`	calcolati per il mezzogiorno locale
`aspects`	calcolati, ma gli aspetti con la Luna sono inaffidabili (vedi sotto)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	blocco con spiegazione: cosa è stato omesso esattamente e dove può trovarsi la Luna

Il blocco timeUnknown.moon contiene la longitudine della Luna all’inizio e alla fine della giornata, l’arco percorso nella giornata (11.8-15.4°), l’elenco dei segni in cui si è trovata e il flag changesSign. In un giorno la Luna può cambiare segno, quindi conviene mostrare questo intervallo all’utente invece di nasconderlo dietro un unico numero.

Il flag è accettato da /v1/chart e /v1/synastry (nella sinastria si può impostare separatamente per ciascuno dei partner). Gli altri endpoint dipendono dalle case o dagli angoli e rispondono 400 TIME_UNKNOWN_UNSUPPORTED: meglio un errore esplicito che un flag ignorato in silenzio e un ascendente inventato nella risposta.

Versionamento dell’API

Versione major nell’URL (/v1/). Le breaking change arrivano solo con /v2/, mai in-place. Dettagli: Versionamento.

GET /v1/version restituisce il deploy corrente:

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

Gli SDK possono chiamarlo all’avvio per il debug di “perché all’improvviso il comportamento è diverso”: il campo build_commit identifica con precisione il deploy.

Le chiamate errate che vediamo più spesso

Dall’analisi dei log di produzione degli ultimi 90 giorni, 5 errori tipici di chi integra:

/api/<endpoint> invece di /v1/<endpoint>: abitudine presa da wp-json di WordPress. Ora restituiamo un 404 JSON con un suggerimento.
/v1/v1/<endpoint>: l’SDK è configurato con baseUrl = .../v1 e aggiunge /v1/X sopra. Ora è un redirect 308.
/swagger.json invece di /v1/openapi.json: auto-probe di Postman/Insomnia. Ora è un redirect 301.
/v1/me, /v1/auth/keys/me senza Authorization: Bearer <jwt> → 401. Verifica che il token venga passato nell’header.
/v1/embed/natal con una chiave API invece di un token embed → 401. Gli endpoint embed accettano un token embed pubblico dalla dashboard, non una chiave API.