Vedic astrology, as an API

Quickstart

Your first call in three steps

1. Sign in at /developer and create a sandbox key. Sandbox calls are free, with no time limit, and return fixed sample responses.
2. Call any endpoint. A sandbox key validates your request exactly as live does, then returns a fixed sample response.
3. When your integration works, create a live key for real readings. Your account gets 100 free live credits once, valid for 60 days from your first live key; after that, buy a credit pack. See the free terms.

curl -X POST https://www.astronest.ai/api/developer/v1/chart \
  -H "Authorization: Bearer astro_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}'

Call the API from your server. Keys are secret, and the API sends no CORS headers, so browser calls fail by design.

Keys

Live and sandbox

Send the key as Authorization: Bearer <key>. Each key is scoped to the endpoints you choose; all keys on an account share one credit balance. The secret is shown once; if you lose it, rotate the key in the portal.

Credits and pricing

Free to start, pay as you go

Every account gets 100 free live credits once, spent first. They do not renew and are valid for 60 days from your first live key; any left after that expire. Beyond that, buy a pack in the portal. Paid credits are one-time purchases and do not expire. Only successful (2xx) calls are charged; a failed call costs nothing. When credits run out the API answers 402 credits_exhausted.

For astrology platforms, practitioner networks, matchmaking services and high-volume applications. Volume pricing · Higher concurrency · Dedicated support · Commercial SLA · Custom integration · Consolidated billing. Talk to us.

Ephemeris calls are fractional. Positions, angles, ayanamsa and sunrise cost 0.1 credit each: the call that opens each block of 10 is charged 1 credit and the next nine are free, counted across the four per account. Failed calls do not count. A series costs 1 credit per started 100 points.

Free accounts may run 2 requests at once; buying any pack raises that to 5.

Endpoints

Reference

Base URL https://www.astronest.ai/api/developer. Every endpoint is POST with a JSON body. Full request and response schemas are in the OpenAPI spec; the OpenAPI guide shows how to import it into Postman, generate a client, or connect an AI app over MCP. The MCP server is listed on Smithery and in the official MCP Registry, and every endpoint is ready to send in our public Postman workspace.

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }
}

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career"
}

{
  "a": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209,
    "name": "A"
  },
  "b": {
    "date": "1991-11-03",
    "time": "06:10",
    "timezone": "Asia/Kolkata",
    "latitude": 19.076,
    "longitude": 72.8777,
    "name": "B"
  }
}

{
  "subject": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "eventPlace": {
    "latitude": 19.076,
    "longitude": 72.8777,
    "timezone": "Asia/Kolkata",
    "label": "Mumbai"
  },
  "freeText": "signing a lease",
  "rangeStart": "2026-11-01",
  "rangeEnd": "2026-11-15"
}

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career",
  "question": "How will the next year unfold for my work?"
}

{
  "birthData": {
    "date": "1990-05-12",
    "time": "14:35",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  },
  "domain": "career",
  "question": "Should I accept the offer?",
  "targetDate": "2026-11-15"
}

{
  "datetime": "2026-10-06T06:00:00Z",
  "bodies": [
    "Sun",
    "Moon",
    "Mars",
    "Jupiter",
    "Saturn",
    "TrueNode"
  ],
  "zodiac": "sidereal",
  "ayanamsa": "lahiri"
}

{
  "datetime": "1990-05-12T14:35:00+05:30",
  "latitude": 28.6139,
  "longitude": 77.209,
  "houseSystem": "placidus"
}

{
  "datetime": "2026-10-06T00:00:00Z"
}

{
  "date": "2026-10-06",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.209
}

{
  "start": "2026-10-01T00:00:00Z",
  "end": "2026-10-10T00:00:00Z",
  "stepMinutes": 1440,
  "bodies": [
    "Mercury",
    "Venus"
  ]
}

Birth data

One object, validated before anything runs

Every reading takes a birthData object: date (YYYY-MM-DD), time (HH:MM or HH:MM:SS, local; omit if unknown), timezone (IANA, e.g. Asia/Kolkata), latitude and longitude. It is validated before anything is computed, so a malformed request is never charged. The API is stateless: birth data is used for the call and not stored.

Ephemeris inputs

A moment, not birth data

The Ephemeris operations take a moment instead of birth data: ISO 8601 with Z or an explicit offset (2026-10-06T06:00:00Z, 1990-05-12T14:35:00+05:30). A time without a zone is refused rather than guessed. Coverage is 1800-01-02 to 2149-12-31 UTC, from NASA JPL DE440. The zodiac defaults to sidereal with the Lahiri ayanamsa; pass zodiac: "tropical" or another ayanamsa to change it. One key scope, ephemeris, covers all five operations; keys created before it existed gain it by editing the key's scopes in the portal.

Domains

What a reading can be about

For interpret, forecast and timing/resolve:

Errors

Every failure is named, and none is charged

Errors return { "error": "<code>", "message": "…", "requestId": "…", "statusCode": n }. Quote the requestId in any support request. No error is charged.

Readings carry qualitative confidence and plain-language reasons. They never include internal scores, rule identifiers or verbatim passages from the source texts. Where an endpoint cites its classical grounding, it names book titles only.

Rate limits

120 requests a minute per account

Each account may make up to 120 requests a minute (sandbox included) and run 2 at once (5 after any purchase). Over the limit, the API answers 429 rate_limited or 429 concurrency_limit with a Retry-After header; neither is charged. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset when limited.

Beta terms

What you agree to

Version beta-1-2026-10-07. You accept these in the portal before creating a live key or buying credits.

1. The API is in beta. It is provided as is, without an SLA, and may change; we will try to give notice of breaking changes.
2. Readings are symbolic interpretation only — not medical, legal, financial or psychological advice. You show the response's disclaimer to your users and do not present a reading as a diagnosis or a guarantee.
3. You do not use readings to make decisions about people in employment, credit, insurance, housing or matchmaking on the basis of caste or religion, or any decision with legal effect based solely on a reading.
4. You keep your keys secret and call the API from your server. You are responsible for calls made with your keys.
5. You may display responses inside your own product. You do not resell raw API access, scrape the API to build a competing dataset or model, or try to reverse-engineer the rules behind the readings.
6. You are responsible for your end users' personal data and for having a lawful basis to send it. We process birth data only to answer each call and do not store request bodies or responses.
7. Credits are prepaid and non-refundable except where the law requires; failed calls are never charged. We may suspend keys used in breach of these terms.
8. Full terms of service and a data processing addendum are being finalised. When they are published you will be asked to accept them before your next live key or purchase.