# Task per agenti

Questa pagina è scritta dai log delle vendite degli ultimi 30 giorni, non dalla fantasia. Di seguito le chiamate effettivamente effettuate dagli integratori con chiave, in ordine di frequenza.

## Cosa viene chiamato più frequentemente

| Endpoint | Chiamati con successo negli ultimi 30 giorni | Perché |
|---|---|---|
| `POST /v1/human-design` | 12 563 | bodygraph: tipo, profilo, autorità, canali |
| `POST /v1/chart` | 11 763 | carta natale: pianeti, case, aspetti |
| `POST /v1/transits` | 1 999 | transiti alla data di nascita |
| `POST /v1/vedic/dashas/vimshottari/maha` | 1 272 | periodi vedici Vimshottari |
| `POST /v1/houses` | 861 | solo cuspidi e angoli, senza pianeti |
| `POST /v1/planets` | 761 | solo posizioni dei corpi celesti |
| `POST /v1/acg` | 704 | astrocartografia, linee nel mondo |
| `POST /v1/transit-calendar` | 678 | calendario dei transiti per un periodo |
| `POST /v1/horoscope/daily` | 549 | testo del giorno (AI) |
| `POST /v1/synastry` | 437 | compatibilità tra due carte |

`GET /v1/auth/keys/me` (262) è anche in questo elenco: gli agenti controllano la chiave prima di lavorare. È gratuito e non consuma crediti.

## Chiamata minima

Un corpo celeste funziona per `chart`, `houses`, `planets`, `human-design`, `transits` e altri endpoint di carta:

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

Le regole esatte dei campi: [Formati dei campi](/agent-setup/field-formats/). La chiave `aw_test_*` non consuma crediti, quindi è quella che dovresti usare per lo sviluppo.

## Leggi la specifica, non indovinare

Ogni pagina operazione ha un **gemello markdown**: lo stesso URL più `.md`. Questo è ciò che dovresti dare al modello invece dell'HTML.

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

Accanto: [`/llms.txt`](https://api.astroway.info/llms.txt) come punto di ingresso e [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json) come specifica completa.

## Quando non serve una chiave

Senza chiave funzionano tre spazi dei nomi, tutti con limite per IP: `/v1/public/*` (nove endpoint di calcolo, elencati nella pagina [Gratuito](/free/)), `/v1/embed/*` (widget pronti) e `/v1/reference/*` (riferimenti: segni, pianeti, aspetti).

La risposta senza chiave include un campo aggiuntivo `_footer` con un watermark, e va bene, così si contrassegna il livello gratuito.

## Prossimo

- [Errori comuni](/agent-setup/mistakes/): ciò che restituisce più spesso 4xx
- [Insidie](/agent-setup/gotchas/): comportamenti che sorprendono
- [MCP](/agent-setup/): un catalogo di strumenti per Claude, Cursor e il resto