curl astrology API quickstart
One shell command, no dependencies.
The fastest way to confirm your key works and see the response shape before you write any code. Every endpoint takes the same bearer token and returns the same envelope, so what you learn here transfers to all of them.
No SDK involved - this is the raw HTTP the language clients wrap.
Step 1
Keep the key out of your code
The key authenticates every call and should never reach a client bundle or a commit. Put it in the environment and read it from there.
# .env (git-ignored) ASTRONODE_API_KEY=aie_test_your_key_here
Step 2
Make the call
A birth chart needs a date, a time, a UTC offset in minutes, and a latitude/longitude. No place-name geocoding - you pass coordinates.
curl -X POST 'https://api.astronode.dev/v1/charts/birth' \
-H "Authorization: Bearer $ASTRONODE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data '{"date":"1993-07-04","time":"09:27:11","tz_offset_minutes":330,"lat":31.7473,"lng":77.7754}'Step 3
Read the envelope
Every response has the same four top-level keys. `data` is the endpoint-specific payload; `meta` names the engine version that produced it, which is what makes a result reproducible.
{
"request_id": "req_01J…",
"data": { "ascendant": { "sign": "Leo", "degree": 12.4 }, "planets": [ … ] },
"interpretation": null,
"meta": { "engine_version": "1.0.0", "computed_at": "2026-09-14T04:21:00.000Z" }
}Step 4
Handle the failure cases
Errors use the same envelope with an `error` object instead of `data`. The three you will actually hit are 400 (validation), 401 (bad or missing key) and 429 (rate limit).
# Add -w to see the status without opening the body
curl -s -o /dev/null -w '%{http_code}\n' \
-X POST 'https://api.astronode.dev/v1/charts/birth' \
-H "Authorization: Bearer $ASTRONODE_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"date":"not-a-date"}'
# → 400, with {"error":{"code":"…","message":"…"}} in the bodyNext
Where to go from here
The call above is one of 110 endpoints. They all take the same bearer token and return the same envelope, so the second one is a path change. Each endpoint page carries its request fields and constraints.
Free tier covers 1,000 requests / month. No card, and test keys work on every endpoint.
Other languages