← The Vedic Catalyst Chart Engine API — developer portal

Chart Engine API — Docs

v1 · JSON over HTTP · key-based auth · sandbox tier free at 60 req/min.

Authentication

Every request except /api/v1/chart/test-vector requires an API key. Send it in the X-API-Key header, or as Authorization: Bearer <key>. Get a sandbox key at the developer dashboard.

Rate limits

Sandbox: 60 requests per rolling 60 seconds per key. Over-limit responses return HTTP 429 with a Retry-After header (seconds to wait).

Error shape

{
  "error":   "human-readable message",
  "code":    "machine-readable code",   // e.g. rate_limited, invalid_request, chart_compute_error
  "details": { ... } | null
}

POST /api/v1/chart

Compute a natal chart. Auth required.

Request body

Field	Type	Required	Notes
dob	string	yes*	YYYY-MM-DD
tob	string	yes*	HH:MM or HH:MM:SS (24h, local)
tzoffset	number	yes*	Hours from UTC (e.g. 5.5 for IST)
lat	number	yes*	Decimal degrees, positive north
lon	number	yes*	Decimal degrees, positive east
name	string	no	Free-text label (echoed only)
place	string	no	Free-text location label

* You can equivalently pass the engine-native spelling year/month/date/hour/minute/second/latitude/longitude/timezone — the API normalizes both.

curl

curl -X POST https://YOUR-HOST/api/v1/chart \
  -H "X-API-Key: jpe_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"dob":"1990-01-01","tob":"12:00","tzoffset":5.5,"lat":13.08,"lon":80.27,"place":"Chennai"}'

Response (200)

{
  "planets": [
    {"name":"SUN","sign":"Sagittarius","sign_num":9,"house":6,
     "degrees_in_sign":16.42,"longitude":256.42,"nakshatra":"Purva Ashadha",
     "pada":2,"retrograde":false,"combust":false,"speed_dpd":1.0186},
    ...
  ],
  "lagna":   {"sign_num": 1},
  "vargas":  {"D1": {...}, "D9": {...}, "D10": {...}},
  "dasha":   {"vimshottari": [{"md":"Ketu","ad":null,"start":"1988-04-27","level":1}, ...]},
  "computed_at": 1721571000
}

POST /api/v1/chart/test-vector

No auth. Returns a deterministic chart for a fixed birth (1990-01-01 12:00 IST, Chennai 13.08 N / 80.27 E). Useful as a “hello world” and as a canary — if the response ever changes, the underlying engine drifted.

curl -X POST https://YOUR-HOST/api/v1/chart/test-vector

GET /api/v1/usage

Auth required. Returns the calling key’s calendar-month usage (UTC).

curl https://YOUR-HOST/api/v1/usage \
  -H "X-API-Key: jpe_sk_..."

Response (200)

{
  "key_id": "ak_abc123def456",
  "window": {"from_ts": 1720000000, "to_ts": 1721571000, "label": "2026-07 (UTC month-to-date)"},
  "plan":   "sandbox",
  "limit_per_minute": 60,
  "usage": {
    "total_calls": 142,
    "total_ms": 8134,
    "by_endpoint": {"/api/v1/chart": {"calls": 140, "ms": 8100, "errors": 0}, ...},
    "by_day": [{"date": "2026-07-20", "calls": 42}, ...]
  }
}

Response contract stability

The v1 response is a curated subset of the engine’s internal chart dict. Fields listed above are stable. The internal engine may grow additional fields — we’ll surface them in v2 once they are ready to freeze.