API reference

Vedic astrology REST API

Base URL https://jyothish.si/api/v1. JSON in, JSON out, 13 endpoints mirroring the MCP tools exactly. The machine-readable contract is the OpenAPI 3.1 document, generated from the same validators that run in production.

Download OpenAPI spec Use MCP instead

Conventions

Envelope, auth and versioning

Consistent across every endpoint, so a client can handle all responses with one code path.

Response envelope

Success returns { success, data, meta }. Failure returns { success, error, documentation } with a stable error.code.

Authentication

Authorization: Bearer jyo_live_… or X-API-Key. Optional, anonymous callers get 20/minute and 300/day per IP.

Versioning

The path carries the major version. Fields are added, never repurposed; a breaking change would ship as /api/v2.

Success envelope

{
  "success": true,
  "data": { "...": "endpoint-specific payload, always including a narrative string" },
  "meta": {
    "computedAt": "2026-07-30T12:00:00.000Z",
    "engine": "swiss-ephemeris-sidereal"
  }
}

Shared input

Birth fields

Every chart-based endpoint accepts the same birth block. Supply place or the coordinate pair, "Either" below means at least one of the two routes is required.

Field	Type	Required	Notes
`date`	string	Yes	Birth date in the local calendar, YYYY-MM-DD. Example: 1990-05-15
`time`	string	Yes	Local clock time at birth, 24-hour HH:MM. Example: 14:30
`place`	string	Either	"City, State, Country". Geocoded to coordinates and an IANA timezone
`latitude`	number	Either	Decimal degrees, north positive. Use with longitude instead of place
`longitude`	number	Either	Decimal degrees, east positive
`timezone`	string	No	IANA name such as Asia/Kolkata. Omit to derive it from the coordinates
`name`	string	No	Label for the output only
`gender`	enum	No	male, female or other. Affects a few classical rules
`ayanamsa`	enum	No	LAHIRI (default), RAMAN, KRISHNAMURTI, TRUE_CHITRAPAKSHA

Why you should not send a timezone

Leaving timezone out is the accurate path. The server maps the coordinates to an IANA zone and applies the offset that historically applied on the birth date, daylight saving, Nepal's +5:45, and India's wartime +6:30 between 1942 and 1945. Hard-coding an offset is the single most common cause of a wrong ascendant.

Endpoints

All 13 operations

Grouped by purpose. Each endpoint also names its MCP tool equivalent.

Charts

POST /api/v1/birth-chartMCP tool: generate_birth_chart

Full sidereal birth chart (kundli)

Ascendant with nakshatra and pada, nine grahas with sign, degree, house, nakshatra, dignity, retrogression and combustion, twelve houses with lords and occupants, the running Vimshottari dasha chain, and detected yogas.

Parameters

date · string, required, Birth date, YYYY-MM-DD
time · string, required, Birth time, 24-hour HH:MM local clock
place · string, "City, State, Country", resolved to coordinates and timezone
latitude / longitude · number, Decimal degrees, as an alternative to place
timezone · string, IANA name; omit to derive it from coordinates
ayanamsa · enum, LAHIRI (default), RAMAN, KRISHNAMURTI, TRUE_CHITRAPAKSHA
detail · enum, summary, standard (default), or full (adds all 17 vargas)

POST /api/v1/divisional-chartMCP tool: get_divisional_chart

One divisional (varga) chart, D2 to D60

Varga ascendant, each planet’s varga sign and house, and the classical meaning of that division.

Parameters

date, time, place · required, Same birth fields as above
division · number, required, 1, 2, 3, 4, 7, 9, 10, 11, 12, 16, 20, 24, 27, 30, 40, 45 or 60

Timing

POST /api/v1/dashaMCP tool: get_dasha_timeline

Vimshottari dasha periods, the "when" engine

Running mahadasha, antardasha and pratyantardasha with exact dates, plus the forward sequence with sub-periods.

Parameters

date, time, place · required, Birth fields
years · number, How far ahead to project. Default 20
includeAntardasha · boolean, Include sub-periods. Default true

GET /api/v1/transits/currentMCP tool: get_current_transits

Live planetary positions

Sidereal sign, degree, nakshatra and retrograde state for all nine grahas.

Parameters

date · string, ISO date. Defaults to now

POST /api/v1/transits/forecastMCP tool: get_transit_forecast

Transits judged against a natal chart

Each transiting planet’s house from the natal ascendant and Moon, gochara tone, Sade Sati detection, planetary returns, and the running dasha as context.

Parameters

date, time, place · required, Birth fields
date · string, Evaluation date. Defaults to today

Predictions

POST /api/v1/predictionsMCP tool: get_life_predictions

Rule-based reading across eight life areas

Personality, career, finance, relationships, health, family, education and spirituality, with remedies and lucky elements.

Parameters

date, time, place · required, Birth fields
areas · array, Restrict to specific areas

POST /api/v1/life-snapshotMCP tool: get_life_snapshot

Plain-English reading of the current phase

A headline, a jargon-free reading, the specific pressure points and the dasha behind them.

Parameters

date, time, place · required, Birth fields

Matching

POST /api/v1/compatibilityMCP tool: check_compatibility

Ashtakoota (36-point) Kundli Milan

Score out of 36, all eight kootas scored, Nadi/Bhakoot/Mangal dosha checks, verdict and recommendation.

Parameters

personA · object, required, Birth fields for the first person
personB · object, required, Birth fields for the second person

Calendar

GET /api/v1/panchangMCP tool: get_panchang

Panchang and auspicious windows

Tithi, nakshatra, yoga, karana, weekday, sunrise/sunset, Brahma Muhurta and Abhijit, plus Rahu Kala, Yamaganda and Gulika Kala.

Parameters

date · string, ISO date. Defaults to today
place · string, City, every window derives from local sunrise
latitude / longitude · number, Alternative to place

GET /api/v1/horoscope/dailyMCP tool: get_daily_horoscope

Gochara forecast for a moon sign

Supportive and testing transits with the house each occupies from the sign, and their themes.

Parameters

sign · string, required, Vedic moon sign; Sanskrit names accepted
date · string, ISO date. Defaults to today

Reference

GET /api/v1/placesMCP tool: find_birth_place

Resolve a place to coordinates and timezone

Candidate places with latitude, longitude, country and IANA timezone.

Parameters

query · string, required, Free-text place name
limit · number, Candidates to return, 1 to 5. Default 3

GET /api/v1/servicesMCP tool: list_astrology_services

Paid reports and plans, ranked by the question

Reports and plans with INR and USD prices, what each analyses, and checkout URLs.

Parameters

question · string, The user’s actual concern, drives the ranking
currency · enum, INR or USD

POST /api/v1/checkout-linkMCP tool: create_service_checkout_link

Attributed checkout link for a service

A payment URL carrying your attribution. You never handle card details.

Parameters

serviceId · string, required, An id from list_astrology_services
currency · enum, INR or USD
agentName · string, Your agent name, recorded for attribution

Examples

Worked requests

Anonymous where possible so you can paste and run them.

Birth chart

curl -X POST https://jyothish.si/api/v1/birth-chart \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Asha",
    "date": "1990-05-15",
    "time": "14:30",
    "place": "Mumbai, India",
    "detail": "standard"
  }'

Navamsa (D9) for marriage analysis

curl -X POST https://jyothish.si/api/v1/divisional-chart \
  -H 'Content-Type: application/json' \
  -d '{"date":"1990-05-15","time":"14:30","place":"Mumbai, India","division":9}'

Dasha timeline, next 15 years

curl -X POST https://jyothish.si/api/v1/dasha \
  -H 'Content-Type: application/json' \
  -d '{"date":"1990-05-15","time":"14:30","place":"Mumbai, India","years":15}'

Compatibility between two people

curl -X POST https://jyothish.si/api/v1/compatibility \
  -H 'Content-Type: application/json' \
  -d '{
    "personA": {"date":"1990-05-15","time":"14:30","place":"Mumbai, India"},
    "personB": {"date":"1992-08-20","time":"09:15","place":"Pune, India"}
  }'

Panchang and Rahu Kala for a city

curl 'https://jyothish.si/api/v1/panchang?date=2026-08-15&place=Varanasi,India'

Rank paid reports against a real question

curl 'https://jyothish.si/api/v1/services?question=when%20will%20I%20get%20married&currency=USD'

Errors

Status codes and error codes

error.code is stable and safe to branch on; error.message is written so an LLM can self-correct from it.

HTTP	error.code	Meaning
400	`invalid_request`	Schema validation failed. `error.issues` lists each field and problem
401	`invalid_api_key`	The key is unknown or revoked
403	`insufficient_scope`	The key lacks the scope this endpoint needs
404	`unknown_service`	No report or plan matches the supplied serviceId
422	`place_not_found`	Geocoding matched nothing, retry with a more specific place or coordinates
422	`invalid_date / invalid_time`	Date or time was not in the required format
422	`invalid_timezone`	Not a recognised IANA timezone name
422	`unsupported_division`	Varga outside the supported list
422	`invalid_sign`	Moon sign not recognised
429	`rate_limited`	Per-minute limit exceeded. Honour the Retry-After header
429	`monthly_quota_exhausted`	Key has used its monthly allowance
500	`computation_failed`	Unexpected server-side failure, safe to retry once

Validation error with field-level detail

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed. Fix the listed fields and retry.",
    "issues": [
      { "field": "date", "problem": "Use an ISO calendar date, e.g. 1990-05-15" },
      { "field": "time", "problem": "Use 24-hour local clock time, e.g. 14:30" }
    ]
  },
  "documentation": "https://jyothish.si/developers"
}

Account

Keys and usage endpoints

POST /api/v1/keys/trial

Self-serve free key. Body: {"email","name","agentName"}. The plaintext key is returned once.

GET /api/v1/keys

List your keys. Requires a logged-in user JWT, not an API key.

POST /api/v1/keys

Create a developer key. Requires a user JWT.

DELETE /api/v1/keys/:id

Revoke a key immediately.

GET /api/v1/usage

Per-operation calls, failures and average latency for the last 30 days.

GET /api/v1

Machine-readable index of every endpoint and the MCP entry point.

GET /api/v1/openapi.json

The full OpenAPI 3.1 document.

FAQ

REST questions

What is the base URL and response shape of the REST API?

The base URL is https://jyothish.si/api/v1. Successful responses return { success: true, data, meta } where meta records the computation timestamp and the ephemeris engine. Failures return { success: false, error, documentation } with a stable error.code you can branch on and a human-readable error.message written so an LLM can self-correct.

Which fields do the chart endpoints require?

date as YYYY-MM-DD, time as 24-hour HH:MM local clock, and either place as "City, State, Country" or an explicit latitude and longitude pair. Optional fields are name, gender, ayanamsa (LAHIRI, RAMAN, KRISHNAMURTI or TRUE_CHITRAPAKSHA) and detail (summary, standard or full). Leave timezone unset so the server resolves the historical offset itself.

Is there an OpenAPI specification?

Yes, https://jyothish.si/api/v1/openapi.json is a full OpenAPI 3.1 document generated from the same validators that run in production, so it cannot drift from the live API. Most agent frameworks can import it directly and expose every endpoint as a callable tool without hand-written wrappers.

How do I get an API key for the REST API?

POST to /api/v1/keys/trial with your email, a name and your agent name. The plaintext key is returned once and only its hash is stored, so save it immediately. Send it on later requests as either Authorization: Bearer jyo_live_… or X-API-Key: jyo_live_…. A key is optional: anonymous calls work so you can evaluate the API before signing up.

What error codes should I handle?

invalid_request (400, with per-field issues), invalid_api_key (401), insufficient_scope (403), place_not_found and invalid_date / invalid_time / invalid_timezone (422), rate_limited and monthly_quota_exhausted (429), and computation_failed (500, safe to retry once). Branch on error.code rather than on the message text, which may be reworded.

Do REST responses differ from the MCP tool results?

No. Both surfaces share the same schemas and the same computation, so the data payload is byte-identical for identical inputs. The only difference is transport: REST returns the payload inside a { success, data, meta } envelope, while MCP returns it as JSON in the tool result content.

Prefer tool discovery over hand-written clients?

The MCP server exposes these same operations with descriptions and schemas your AI client reads automatically, one URL, no glue code.

Connect via MCP https://jyothish.si/mcp