# Tâches pour l'agent

Cette page est rédigée à partir des logs de production sur 30 jours, et non à partir d'imagination. Ci-dessous, les appels que les intégrateurs réellement effectuent avec leur clé, par ordre de fréquence.

## Les appels les plus fréquents

| Endpoint | Appels réussis en 30 jours | Pourquoi |
|---|---|---|
| `POST /v1/human-design` | 12 563 | bodygraph : type, profil, autorité, canaux |
| `POST /v1/chart` | 11 763 | carte natale : planètes, maisons, aspects |
| `POST /v1/transits` | 1 999 | transits vers la natale pour une date |
| `POST /v1/vedic/dashas/vimshottari/maha` | 1 272 | périodes védiques Vimshottari |
| `POST /v1/houses` | 861 | seulement les cusps et angles, sans planètes |
| `POST /v1/planets` | 761 | seulement les positions des corps |
| `POST /v1/acg` | 704 | astrocartographie, lignes dans le monde |
| `POST /v1/transit-calendar` | 678 | calendrier de transits pour une période |
| `POST /v1/horoscope/daily` | 549 | texte pour la journée (IA) |
| `POST /v1/synastry` | 437 | compatibilité de deux cartes |

`GET /v1/auth/keys/me` (262) est aussi dans cette liste : les agents vérifient la clé avant de travailler. C'est gratuit et ne consomme pas de crédits.

## Appel minimal

Un seul corps convient pour `chart`, `houses`, `planets`, `human-design`, `transits` et les autres endpoints de type carte :

<Code lang="bash" title="terminal" code={`curl -X POST https://api.astroway.info/v1/chart \\
  -H "X-Api-Key: aw_test_YOUR_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"date":"1990-05-15","time":"15:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'`} />

Les règles précises des champs : [Formats des champs](/agent-setup/field-formats/). La clé `aw_test_*` ne consomme pas de crédits, donc c'est celle qu'il faut utiliser pour le développement.

## Lire la spécification plutôt que de deviner

Chaque page d'opération a un **double markdown** : le même URL plus `.md`. C'est ce qu'il faut donner au modèle au lieu du HTML.

<Code lang="bash" title="terminal" code={`curl https://api.astroway.info/docs/api/operations/acg_categories_get.md`} />

À côté : [`/llms.txt`](https://api.astroway.info/llms.txt) comme point d'entrée et [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json) comme spécification complète.

## Quand la clé n'est pas nécessaire

Trois espaces de noms fonctionnent sans clé, tous avec une limite par IP : `/v1/public/*` (neuf endpoints de calcul, listés sur la page [Gratuit](/free/)), `/v1/embed/*` (widgets prêts à l'emploi) et `/v1/reference/*` (références : signes, planètes, aspects).

La réponse sans clé inclut un champ supplémentaire `_footer` avec une signature, et c'est normal, c'est ainsi que le niveau gratuit est marqué.

## Suite

- [Erreurs courantes](/agent-setup/mistakes/) : ce qui retourne le plus souvent 4xx
- [Pièges à éviter](/agent-setup/gotchas/) : le comportement qui surprend
- [MCP](/agent-setup/) : un catalogue d'outils pour Claude, Cursor et les autres