API reference
Astronomical data from NASA/JPL DE440, any date 1800-2200. One HTTPS POST per call, JSON in, JSON out, a SHA-256 on every result.
New here? The 60-second quickstart takes you from a key to your first result. Prefer to click? The playground runs any route from a form.
Base URL and authentication
https://astro-agent.dev/v1/<route>, method POST, body JSON.
Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.
Routes
| Route | Path | Price | What it returns |
|---|---|---|---|
| Planetary positions for any date (ephemeris) | POST /v1/western/positions | $0.01 | Planetary positions for any date and time (ephemeris): tropical or sidereal longitude, latitude, speed and retrograde flag of the Sun, Moon, Mercury..Pluto, nodes and Lilith. |
| Sky today: retrogrades, Moon phase, next events | POST /v1/western/sky | $0.01 | The sky today (no location needed): planet positions, retrogrades and Moon phase now, plus the exact UTC times of the next ingresses, stations (Mercury retrograde), new and full moons and aspects. |
| Angles between bodies (aspects, parallels) | POST /v1/western/aspects | $0.02 | Aspects (with orb, exactness, applying/separating) for a moment, or for any longitudes you supply. |
| Celestial event calendar (eclipses, stations, ingresses) | POST /v1/finance/events | $0.25 | Eclipse and Mercury retrograde calendar: every solar and lunar eclipse, station (retrograde/direct), ingress, new and full moon, aspect, parallel and out-of-bounds between two dates (1800-2200), to the minute. |
| Planetary longitude series (geocentric + heliocentric) | POST /v1/finance/planetary-lines | $0.20 | Planetary longitudes (geocentric and heliocentric) at a moment or as a longitude time series at chosen intervals, with angular offsets and multi-body averages. |
| Sky similarity search (matching skies) | POST /v1/finance/analogues | $0.25 | Find the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance. |
| Local time resolver (historical time zones) | POST /v1/time/resolve | $0.01 | Local time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time. |
Every response
{"endpoint", "result", "meta"}: result holds the data, meta.input_sha256
and meta.result_sha256 identify the request and the result (POST /v1/verify recomputes the
hash, free). Every convention (frame, equinox, perspective, orbs) is stated in result.settings.
From JavaScript, send /v1/verify the result's raw JSON text, not JSON.stringify(data.result):
JSON.parse turns 180.0 into 180, and the hash rule (sorted keys, no whitespace,
floats rounded to 6 decimals) tells the two apart. Python's json keeps them apart and verifies
as is.
More
Errors · Catalog (JSON) · OpenAPI
· llms.txt · MCP server: https://astro-agent.dev/mcp