# Tarefas para o agente

Esta página foi escrita a partir de logs de produção de 30 dias, não da imaginação. Abaixo estão as chamadas que os integradores realmente fazem com a chave, em ordem de frequência.

## O que é mais chamado

| Endpoint | Chamadas bem-sucedidas nos últimos 30 dias | Para quê |
|---|---|---|
| `POST /v1/human-design` | 12 563 | bodygraph: tipo, perfil, autoridade, canais |
| `POST /v1/chart` | 11 763 | mapa natal: planetas, casas, aspectos |
| `POST /v1/transits` | 1 999 | trânsitos para o natal numa data |
| `POST /v1/vedic/dashas/vimshottari/maha` | 1 272 | períodos védicos Vimshottari |
| `POST /v1/houses` | 861 | apenas cusps e ângulos, sem planetas |
| `POST /v1/planets` | 761 | apenas posições dos corpos |
| `POST /v1/acg` | 704 | astrocartografia, linhas pelo mundo |
| `POST /v1/transit-calendar` | 678 | calendário de trânsitos para um período |
| `POST /v1/horoscope/daily` | 549 | texto do dia (IA) |
| `POST /v1/synastry` | 437 | compatibilidade de dois mapas |

`GET /v1/auth/keys/me` (262) está nesta mesma lista: os agentes verificam a chave antes de trabalhar. É gratuito e não consome créditos.

## Chamada mínima

Um único corpo serve para `chart`, `houses`, `planets`, `human-design`, `transits` e outros endpoints de 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}'`} />

Regras precisos dos campos: [Formatos de campo](/agent-setup/field-formats/). A chave `aw_test_*` não consome créditos, por isso é ideal para desenvolvimento.

## Leia a especificação, não adivinhe

Cada página de operação tem um **duplicado em markdown**: o mesmo URL mais `.md`. Este é o que deve ser dado ao modelo em vez de HTML.

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

Ao lado: [`/llms.txt`](https://api.astroway.info/llms.txt) como ponto de entrada e [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json) como especificação completa.

## Quando a chave não é necessária

Sem chave, três namespaces funcionam, todos com limite por IP: `/v1/public/*` (nove endpoints de cálculo, listados na página [Gratuito](/free/)), `/v1/embed/*` (widgets prontos) e `/v1/reference/*` (referências: signos, planetas, aspectos).

A resposta sem chave inclui um campo adicional `_footer` com uma assinatura, e isso é normal, assim é marcado o nível gratuito.

## Próximo

- [Erros comuns](/agent-setup/mistakes/): o que mais frequentemente retorna 4xx
- [Armadilhas](/agent-setup/gotchas/): comportamento que surpreende
- [MCP](/agent-setup/): um catálogo de ferramentas para Claude, Cursor e o resto