# Tasks for an agent

This page is written from 30 days of production logs rather than from imagination. Below are the calls integrators with a key actually make, in order of frequency.

## What gets called most

| Endpoint | Successful calls in 30 days | What for |
|---|---|---|
| `POST /v1/human-design` | 12,563 | bodygraph: type, profile, authority, channels |
| `POST /v1/chart` | 11,763 | natal chart: planets, houses, aspects |
| `POST /v1/transits` | 1,999 | transits to a natal chart on a date |
| `POST /v1/vedic/dashas/vimshottari/maha` | 1,272 | Vimshottari periods |
| `POST /v1/houses` | 861 | cusps and angles only, no planets |
| `POST /v1/planets` | 761 | body positions only |
| `POST /v1/acg` | 704 | astrocartography lines across the world |
| `POST /v1/transit-calendar` | 678 | a calendar of transits over a period |
| `POST /v1/horoscope/daily` | 549 | text for the day (AI) |
| `POST /v1/synastry` | 437 | compatibility of two charts |

`GET /v1/auth/keys/me` (262) belongs on the same list: agents check the key before working. It is free and spends no credits.

## The minimal call

One body fits `chart`, `houses`, `planets`, `human-design`, `transits` and the rest of the chart-shaped endpoints:

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

The exact field rules: [Field formats](/en/agent-setup/field-formats/). An `aw_test_*` key spends no credits, which is what makes it the one to develop against.

## Read the spec instead of guessing

Every operation page has a **markdown twin**: the same URL plus `.md`. That is what to hand a model instead of HTML.

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

Alongside it: [`/llms.txt`](https://api.astroway.info/llms.txt) as the entry point and [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json) as the full specification.

## When no key is needed

Three namespaces work without a key, all limited per IP: `/v1/public/*` (nine calculation endpoints, listed on the [Free](/en/free/) page), `/v1/embed/*` (ready-made widgets) and `/v1/reference/*` (lookups: signs, planets, aspects).

A keyless answer carries an extra `_footer` field with a credit line, which is normal and marks the free tier.

## Next

- [Common mistakes](/en/agent-setup/mistakes/): what returns 4xx most often
- [Gotchas](/en/agent-setup/gotchas/): behaviour that surprises people
- [MCP](/en/agent-setup/): one tool catalogue for Claude, Cursor and the rest