Vedika API reference

Endpoints by system

Counted from the served OpenAPI spec. Pick a system to read about it, or open it in the explorer to see every endpoint.

1,128 endpoints

The OpenAPI file lists 1,293 operations because it also lists the 148 Vastu routes under their second spelling, /v2/vastu/, and 17 sandbox, console and key-file routes that the endpoint count leaves out. The copy served at api.vedika.io/openapi.json is the same file and lists the same 1,293.

Base URL

https://api.vedika.io

https://api.vedika.io/sandbox

The sandbox serves a fixed list of the live routes with /sandbox in place of the /v2 prefix, for example /sandbox/astrology/birth-chart. GET /sandbox/endpoints lists them. It needs no key, costs nothing and returns fixed sample data, so use it to test your integration and a key for real charts.

Authentication

Send your API key in the Authorization header as a Bearer token. The X-API-Key header is also accepted when no Bearer credential is present, until 18 January 2027; after that date only Bearer works. Responses to calls that still use X-API-Key carry Deprecation and Sunset headers. Create and rotate keys in the dashboard.

Authorization: Bearer vk_live_your_key

A missing, malformed, expired or revoked key gets 401 with a body that names the problem, and a WWW-Authenticate header. Do not retry a 401; fix the key. Keep keys on your server and never ship them in a browser or mobile app.

A complete example

A Vedic birth chart for a Mumbai birth. Send the same body to https://api.vedika.io/sandbox/astrology/birth-chart without the header to try it for free.

curl https://api.vedika.io/v2/astrology/birth-chart \
  -H "Authorization: Bearer $VEDIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-05-15T10:30:00",
    "latitude": 19.07,
    "longitude": 72.87,
    "timezone": "+05:30",
    "ayanamsa": "lahiri"
  }'

Do not add an idempotency header to this call. The birth-chart endpoint does not accept one and answers 422 if you send it. Every successful call is charged, so store the chart on your side if you will show it again. See Retries and repeat requests for the endpoints that do accept a retry key.

Responses

Successful calls return JSON with four parts: success, the result in data, request details in meta, and what the call cost in billing. This is a real sandbox response to the example above, shortened; the sandbox marks itself with "mode": "sandbox" and charges nothing.

{
  "success": true,
  "data": {
    "ascendant": {
      "sign": "Pisces",
      "signLord": "Jupiter",
      "degree": 13.56,
      "fullDegree": 343.56
    },
    "moonSign": "Sagittarius",
    "sunSign": "Sagittarius",
    "planets": "[ ... nine grahas with sign, house, degree, nakshatra ... ]"
  },
  "meta": {
    "contentMode": "fixture",
    "engine": "vedika-intelligence",
    "fixtureId": "demo-birth-1995-new-delhi",
    "inputUsage": "ignored",
    "mode": "sandbox",
    "sample": true,
    "version": "2.1.0"
  },
  "billing": {
    "balanceAfter": 100,
    "balanceBefore": 100,
    "category": "astrology",
    "charged": 0,
    "currency": "USD",
    "endpoint": "/sandbox/astrology/birth-chart"
  }
}

Every response also carries X-Request-Id. Quote it when you contact support and we can find the exact call.

Errors

Errors use the HTTP status code and a JSON body with status, code and message. Branch on the status first and on code second.

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authentication required. Pass your API key as `Authorization: Bearer vk_live_...`."
}

Retries and repeat requests

Every successful call is charged. That includes asking again for a chart, horoscope or match you already fetched. Charts are deterministic, so if your users view the same result again, store the first response on your side, for example under a hash of the birth details, and serve it from there.

A retry key is narrower. Send it as an Idempotency-Key header. It stops a retry of the same request, with the same body, from being charged again within 24 hours. Only these endpoints accept it:

• AI answers: POST /api/v1/astrology/query and POST /api/v1/batch.
• Panchang elements: /v2/astrology/tithi, /v2/astrology/nakshatra, /v2/astrology/yoga and /v2/astrology/karana.
• Dasha: /v2/astrology/vimshottari-dasha, /v2/astrology/dasha, /v2/astrology/dasha-periods, /v2/astrology/mahadasha and /v2/astrology/antardasha.
• Ashtakoota matching: /v2/astrology/matching/ashtakoota.
• The 18 Vastu calculation routes (reference, direction, mandala, room and floor-plan audit, entrance, AR scan quality and plot), under both /v2/vastu/ and /v2/astrology/vastu/.
• Endpoints that require a key: prebuilt reports, Vastu jobs and assessment batches, and Vastu chat uploads. Their reference pages give the exact rules.

Most other chart endpoints refuse a retry key. That includes birth chart, kundli, panchang, horoscope, kundli matching and the matrimony routes. On the /v2 chart endpoints, Idempotency-Key, X-Idempotency-Key and your own X-Request-Id all count as a retry key. Send any of them to an endpoint that refuses it and you get 422 IDEMPOTENCY_NOT_SUPPORTED, with nothing charged; send the request again without it. These endpoints have no retry protection: if a call succeeded and only the response was lost, a retry is charged as a new call.

Rate limits

Each plan has a per-minute and a per-day request limit. The figures for every plan are on the rate limits page. Every response reports where you stand:

• X-RateLimit-Limit: requests allowed in the current window
• X-RateLimit-Remaining: requests left in it
• X-RateLimit-Reset: when the window resets

When you hit the limit you get 429 with Retry-After. A 429 is about speed, not money: a call your wallet cannot cover returns 402 instead, so read the body code before deciding to wait or to top up.

Next steps