Grahvani API v1
Documentation

Quickstart

From nothing to a birth chart in about five minutes.

1. Get a key#

Keys look like gv_live_… or gv_test_… and are shown once, at creation. We store only a hash, so we cannot recover one for you — if it is lost, issue a new one and revoke the old.

Send it on every request:

X-API-Key: gv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Start in test mode. A gv_test_… key returns deterministic fixtures, is never billed, and never touches your live quota. Build the integration against it, then swap the key.

2. Your first chart#

curl -X POST https://api.grahvani.in/v1/charts/rasi \
  -H "X-API-Key: $GRAHVANI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "date": "1980-05-01",
      "time": "05:16:00",
      "place": {
        "latitude": 27.1767,
        "longitude": 78.0081,
        "timezone": "Asia/Kolkata"
      }
    }
  }'

3. What comes back#

Every successful response has the same three-part shape. Only data changes between endpoints.

{
  "data": { "ascendant": { … }, "planets": [ … ], "houses": [ … ] },

  "meta": {
    "request_id": "req_01J8ZK…",   // quote this to support
    "endpoint":   "charts.rasi",
    "units":      1,                // what this call cost
    "ayanamsa":   "lahiri",
    "computed_at":"2026-08-06T09:12:03Z"
  },

  "provenance": {                   // present when we have something citable
    "conventions": { "ayanamsa": "Lahiri (Chitrapakṣa)" }
  }
}

meta.units is on every response, so cost is never a surprise and never retroactive.

4. Three things worth knowing before you build#

Timezone must be an IANA name, not an offset:

"timezone": "Asia/Kolkata"    // ✅
"timezone": "+05:30"          // ❌ 400 invalid_timezone

An offset cannot express a historical daylight-saving transition, and a birth in 1980 may need one. Getting this wrong shifts a chart by the length of the error.

If the birth time is unknown, omit it entirely.

"birth": { "date": "1980-05-01", "place": { … } }   // no "time"

You get the full chart — lagna, daśās, everything — computed for 12:00 noon, with meta.birth_time_assumed: true so you can disclose the assumption to your user. We never refuse a reading for want of a birth time.

Read provenance before you present a number. Where the classical sources genuinely disagree — the yoni grid in Aṣṭakūṭa is the live example — the response says so in provenance.disputed rather than handing you a contested figure as though it were settled. See Provenance.

5. Errors#

One shape, always:

{
  "error": {
    "type":    "invalid_request",
    "code":    "missing_field",
    "message": "birth.time must be HH:MM:SS. Omit it entirely if unknown — we assume noon.",
    "field":   "birth.time",
    "doc_url": "https://docs.grahvani.in/errors/missing_field",
    "request_id": "req_01J8ZK…"
  }
}

4xx is yours, 5xx is ours. We never return a 5xx for bad input, and we never bill a non-2xx call. Full list in Errors.

6. Check what you can call#

curl https://api.grahvani.in/v1/meta/capabilities -H "X-API-Key: $GRAHVANI_KEY"

Free, 0 units. Read this before depending on a non-default ayanāṁśa — the schools are not equal in depth, and the difference is large enough to break an integration built on the assumption that they are. See Ayanāṁśa.

curl https://api.grahvani.in/v1/meta/usage -H "X-API-Key: $GRAHVANI_KEY"

Also free: plan, units used, units remaining, rate limit.

Next#

Introduction API reference Errors OpenAPI spec llms.txt
Grahvani API — a product of AstroCorp Techlab Pvt Ltd · GSTIN 36AAMCC3512G1ZU
Base URL https://api.grahvani.in
On this page