Conventions d'URL et endpoints gratuits

Si vous obtenez un 404 sur une requête ordinaire, le plus probable est un mauvais préfixe, ou vous cherchez Swagger UI à un chemin non standard. Cette page recense toutes les URL canoniques et leurs alias.

Préfixe de chemin

Tous les endpoints se trouvent sous /v1/. Il n’y a pas d’autre préfixe.

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

Si vous avez utilisé par erreur /api/<endpoint>, nous renvoyons un 404 avec le champ error.code = "WRONG_PREFIX" et une indication: votre SDK peut le traiter et suggérer le bon chemin.

Ce n’est pas un proxy LLM

AstroWay est une API de calculs astrologiques, pas un proxy pour LLM. Si vous arrivez avec les réflexes du SDK OpenAI et essayez simplement de remplacer base_url par le nôtre, cela ne fonctionnera pas:

❌ 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

Nous ne publions pas la liste des fournisseurs d’IA, pour deux raisons:

Rien d’exploitable pour l’intégrateur. Vous appelez /v1/interpret/natal ou /v1/horoscope/daily, et notre serveur choisit lui-même un LLM parmi plusieurs fournisseurs avec fallback automatique. Un changement de fournisseur ne modifie pas la forme de la réponse, seulement la latence et parfois la formulation.
Liberté opérationnelle. La chaîne change sans préavis (retrait de HuggingFace le 2026-05-18, ajout de NIM/ZAI). Si nous annoncions une liste models[] précise, elle deviendrait de fait un contrat.

L’IA n’est qu’un détail d’implémentation dans /v1/interpret/* (natal, synastrie, transits), /v1/horoscope/* (horoscope quotidien/hebdomadaire), /v1/dev-assistant (assistant pour la documentation) et /v1/reports/* (récits PDF). Les 750+ autres endpoints sont du Swiss Ephemeris déterministe, sans IA.

Spécification OpenAPI 3.1

L’adresse canonique est /v1/openapi.json. Pour faciliter les intégrations, des alias ont été ajoutés:

Alias	Vers	Pourquoi il existe
`/v1/swagger.json`	301 → `/v1/openapi.json`	Convention Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Valeur par défaut de 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`	Hôte Swagger UI

Le Swagger UI interactif est disponible à /v1/docs (également reproduit dans la documentation navigateur sur /docs/api/).

Endpoints système gratuits

Ces chemins ne nécessitent pas de clé API et ne débitent pas de crédits: vous pouvez les appeler depuis n’importe quel frontend, outil de monitoring ou health-check.

Chemin	Ce qu’il renvoie
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - sonde de liveness rapide
`GET /v1/health/deep`	Vérification d’accessibilité de chaque base de données (pour UptimeRobot / Pingdom), 503 si au moins une base est inaccessible
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - auto-vérification détaillée pour les SDK
`GET /v1/openapi.json`	Spécification OpenAPI 3.1 complète avec exemples + `x-codeSamples`
`GET /v1/docs`	Swagger UI interactif
`GET /v1/reference/*`	Référentiels canoniques (signes, planètes, maisons, aspects) - rate-limit par IP, sans clé
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Liste des langues et dictionnaires d’interface, pour les widgets

Endpoints gratuits nécessitant une inscription

Les endpoints de compte sont accessibles uniquement avec un jeton JWT (émis à la connexion), mais ne débitent pas de crédits du solde du plan.

Préfixe	Ce que c’est
`/v1/auth/*`	Inscription, connexion, refresh, réinitialisation du mot de passe
`/v1/me`, `/v1/me/*`	Profil, statistiques, appels récents
`/v1/keys`, `/v1/keys/*`	Gestion des clés API
`/v1/admin/*`	Panneau d’administration (nécessite `api_role = admin`)
`/v1/messages`	Retours depuis le widget (anonyme, rate-limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Assistant IA pour la documentation (anonyme, limite distincte)
`/v1/widget-config`	Feature flags d’exécution pour le widget
`/v1/embed/*`	Widgets iframe intégrables (rate-limit par IP)
`/v1/oauth/*`	Connexion Google / GitHub
`/v1/books/*`	Birth Book - JWT à scope dédié (émis par le mu-plugin WordPress)

Endpoints de calcul payants

Tous les calculs astrologiques débitent des crédits de votre plan tarifaire. Le coût exact de chacun figure sur la page Coût des endpoints. En bref:

Tier	Crédits	Exemples
0	0	`/v1/reference/*` - référentiels publics, sans clé
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - tables statiques
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`, récits IA `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Rapports PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Remises de cache: X-Cache: HIT (cache d’idempotence de 5 min) - 0 crédit. Endpoints IA (/interpret/*) - 50% de remise sur un cache hit.

Les en-têtes de réponse contiennent X-Credits-Used, X-Credits-Remaining, X-Credits-Limit: les SDK peuvent suivre le solde automatiquement.

Langue des réponses

La langue se définit via ?lang= ou l’en-tête Accept-Language. 21 langues sont prises en charge.

Les champs issus d’ensembles fermés (signes, planètes, jours de la semaine, phases de la Lune, vocabulaire Human Design, noms des Arcanes majeurs du Tarot) sont renvoyés deux fois: l’identifiant anglais reste à sa place comme contrat stable, et un objet localized avec la traduction l’accompagne:

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

Comparez les valeurs anglaises, affichez localized. Ces noms proviennent d’une table de termes explicite dans le code, et non d’une traduction automatique: la terminologie ne se traduit pas mot à mot, sinon une phase de la Lune se transforme en terme financier.

En Human Design, les centres dans localized.centers ont pour clés les mêmes identifiants que centers[].name, la correspondance se fait donc par la clé et non par la chaîne traduite. Pour le Tarot, localized.cards fait de même, avec pour clé le slug de la carte.

Les champs issus d’ensembles ouverts restent pour l’instant en anglais et sont documentés comme tels: themes[] de la planète du jour, mots-clés et significations des cartes de Tarot, noms des canaux et des portes Human Design. Les noms des Arcanes mineurs sont composés à partir de formes figées du rang et de la couleur, donc le jeu entier de 78 cartes est localisé et nameLocalized vaut true pour lui; le champ ne reste false que là où la table ne peut pas fournir de nom. Traduisez les ensembles ouverts de votre côté ou attendez des dictionnaires dédiés.

Réponse compacte: `fields` et `precision`

Un agent paie chaque token qu’il lit. POST /v1/chart renvoie environ 32 Ko, alors que le modèle n’a généralement besoin que de deux colonnes, et chaque longitude arrive avec quatorze décimales là où personne ne construit plus précis qu’une minute d’arc.

Deux paramètres de requête règlent cela à la dernière étape, ils fonctionnent donc sur tous les endpoints:

fields - liste de chemins séparés par des virgules, relatifs à data. Un chemin s’applique à chaque élément d’un tableau, donc planets.name désigne le nom de chaque planète, et non une clé du tableau.
precision - entier de 0 à 15, arrondit tous les nombres non entiers de la réponse. Les entiers ne sont pas touchés: un identifiant n’est pas une mesure.

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

Sur une carte natale, cette paire de paramètres donne 511 octets au lieu de 32 410, soit une réponse soixante fois plus petite.

Un chemin qui n’a rien trouvé ne disparaît pas en silence. Il revient dans le champ _fields_unmatched à côté de la réponse: certains champs sont réellement facultatifs et absents d’une réponse donnée, ce n’est donc pas une erreur. En revanche, une liste où aucun chemin ne correspond est une faute de frappe, et elle renvoie 400 FIELDS_UNKNOWN avec la liste. Un objet vide à la place d’une carte serait une mauvaise réponse assurée.

Les deux paramètres vont dans la query et non dans un en-tête, et c’est voulu: le cache des réponses est indexé par méthode, chemin, corps, query triée et plan. Un mode passé en en-tête reproduirait l’incident du 2026-08-22, où Accept-Language ne faisait pas partie de la clé et où une réponse allemande avait été servie à l’appelant suivant comme ukrainienne.

Le façonnage ne concerne que data. L’enveloppe, _footer et _warning restent intacts.

La même chose fonctionne via MCP. Chaque outil sur mcp.astroway.info accepte fields et precision à côté de ses propres paramètres et les transmet à l’API dans la même query. Une carte natale via MCP pesait 91 737 octets, car les données arrivaient deux fois: en bloc de texte indenté et en champ structuré. Avec les trois mêmes chemins et precision: 2, cela fait 1 182 octets.

Appel de carte natale	Octets
MCP, comme avant le 21.09.2026	91 737
MCP, sans indentation dans le bloc de texte	72 484
MCP, `precision: 2`	61 356
MCP, trois chemins dans `fields` plus `precision: 2`	1 182
REST, trois chemins dans `fields` plus `precision=2`	559

Heure de naissance inconnue

Une bonne partie des utilisateurs finaux ne connaît pas l’heure exacte de sa naissance. Si l’on prend midi par convention et que l’on calcule la carte normalement, la réponse contiendra un ascendant et des cuspides de maisons qui semblent fiables, mais se trompent d’environ un signe pour chaque tranche de deux heures d’écart.

C’est pourquoi, à la place de time, vous pouvez passer 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 que renvoie l’API dans ce mode:

Champ	Valeur
`planets`	calculées pour midi local
`aspects`	calculés, mais les aspects avec la Lune ne sont pas fiables (voir ci-dessous)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	bloc explicatif: ce qui est omis exactement et où peut se trouver la Lune

Le bloc timeUnknown.moon contient la longitude de la Lune au début et à la fin de la journée, l’arc parcouru en une journée (11.8-15.4°), la liste des signes où elle s’est trouvée et l’indicateur changesSign. La Lune peut changer de signe en une journée, il vaut donc mieux montrer cette plage à l’utilisateur que la cacher derrière un seul nombre.

L’indicateur est accepté par /v1/chart et /v1/synastry (en synastrie, il peut être défini séparément pour chacun des partenaires). Les autres endpoints dépendent des maisons ou des angles et répondent 400 TIME_UNKNOWN_UNSUPPORTED: mieux vaut une erreur explicite qu’un indicateur ignoré en silence et un ascendant inventé dans la réponse.

Versionnement de l’API

Version majeure dans l’URL (/v1/). Les breaking changes n’arrivent qu’avec /v2/, jamais sur place. Détails: Versionnement.

GET /v1/version renvoie le déploiement actuel:

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

Les SDK peuvent l’appeler au démarrage pour déboguer un “pourquoi le comportement a-t-il soudain changé”: le champ build_commit identifie précisément le déploiement.

Les appels erronés que nous voyons le plus souvent

D’après l’analyse des logs de production sur 90 jours, 5 erreurs typiques d’intégrateurs:

/api/<endpoint> au lieu de /v1/<endpoint>: habitude venue de wp-json de WordPress. Nous renvoyons désormais un 404 JSON avec une indication.
/v1/v1/<endpoint>: SDK configuré avec baseUrl = .../v1 qui ajoute /v1/X par-dessus. Désormais une redirection 308.
/swagger.json au lieu de /v1/openapi.json: auto-détection de Postman/Insomnia. Désormais une redirection 301.
/v1/me, /v1/auth/keys/me sans Authorization: Bearer <jwt> → 401. Vérifiez que le jeton est bien passé dans l’en-tête.
/v1/embed/natal avec une clé API au lieu d’un jeton embed → 401. Les endpoints embed acceptent un jeton embed public issu du tableau de bord, pas une clé API.