Documentation
Saved charts and astrology events
Store a birth once, call any capability with its chart_id, and receive webhooks when a dasha begins, Sade Sati changes phase, a slow planet changes sign or an eclipse falls on the chart.
A saved chart is one person's birth stored under a label. Save it once, then send "chart_id" instead of the birth fields in any capability call. A saved chart can also subscribe to astrology events: the API works out what is coming for that chart and sends you a signed webhook when each event is due.
Saved charts and subscriptions cost no credits. They need a secret key, because they hold personal data. Each saved chart belongs to the key's project and environment, so a test key never sees a live key's charts.
Save a chart
POST /v1/charts
Authorization: Bearer sk_live_...
{
"label": "Asha Rao",
"external_id": "cust-42",
"datetime": "1990-10-18T14:30:00",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
}The birth fields follow the same rules as every request (local time without an offset, one of timezone or utc_offset). external_id is your own id for the person: list with GET /v1/charts?external_id=cust-42.
| Call | Does |
|---|---|
POST /v1/charts | Save a birth; returns the chart with its id |
GET /v1/charts | List, newest first (limit, after, external_id) |
GET /v1/charts/{id} | One chart |
PATCH /v1/charts/{id} | Change label or external_id. The birth cannot change: save a new chart |
DELETE /v1/charts/{id} | Delete it, its subscription and its pending events, at once |
An environment holds up to 10,000 saved charts.
Use it in any call
Send chart_id where the birth fields would go:
{ "chart_id": "5b0c3f0e-8a7d-4a51-9a51-2f2f0a6d9c11", "depth": "antardasha" }It works inside a two-person body too, for example "person_a": { "chart_id": "..." } or "groom": { "chart_id": "..." }. Other fields next to it stay as you send them (ayanamsha, name, language). Sending a birth field next to chart_id is refused with 422, because the request would give two different births. An unknown chart_id answers 404. Both errors name the field.
Subscribe to astrology events
PUT /v1/charts/{id}/events
{ "event_types": ["astro.dasha.started", "astro.transit.sign_change"], "notice_days": 3 }| Event | When |
|---|---|
astro.dasha.started | A Vimshottari mahadasha or antardasha begins |
astro.sade_sati.changed | A Sade Sati (or Ashtama/Kantaka) phase begins, or the Sade Sati ends |
astro.transit.sign_change | Jupiter, Saturn or Rahu changes sign. The event gives its house from the natal Moon and from the Lagna |
astro.eclipse.on_chart | A solar or lunar eclipse falls within 3° of the natal Sun, Moon or Lagna |
notice_days (0 to 30) sends each event that many days before it occurs. Use 0 to receive it on the day. The response lists the upcoming events, and GET /v1/charts/{id}/events shows them at any time. DELETE /v1/charts/{id}/events unsubscribes the chart and drops its pending events.
Events are computed with the same capabilities you can call: vimshottari-dasha, sade-sati, planetary-events, eclipses and planet-positions. So the dates match what those calls return. The API looks about 13 months ahead and keeps the timeline topped up. Each event is delivered once, to every enabled endpoint subscribed to its type. On live keys, delivery needs a plan that includes live webhooks. An environment can have up to 1,000 subscribed charts.
Each event's data carries chart_id, label, external_id, occurs_at and notice_days, plus the fields of the event. The webhooks page lists those fields for each event type.
PDF and audio jobs, and webhooks
Render a report as a PDF or a spoken MP3 in the background, poll the job or receive a signed webhook, and download the file. You can also follow jobs in your dashboard.
Audio reports
Turn any report into a spoken MP3 in 26 languages, with your choice of voice, tone and length.