Why AstroNest
What you get here and not elsewhere
Each of these is something you can check yourself with a free sandbox key.
Compatibility beyond the guna score
The 36-point Aṣṭakūṭa is one input. The verdict weighs each chart's marital promise and doṣas, names the governing factor, and says when it overrides the score.
/v1/compatibility
Manglik from the lagna, the Moon and Venus
All three classical reckonings, with mutual cancellation. A chart clean from the lagna can carry the doṣa from the Moon or Venus, and the response shows which.
/v1/guna-milan, /v1/compatibility
Joint marriage timing
Compatibility finds when both charts' periods open together, not only whether the two match.
/v1/compatibility
Deterministic interpretation
Interpret, guidance, compatibility and guna milan call no language model: the same chart always gets the same reading. Only forecast and timing are voiced by a model, and they are marked as such.
/v1/interpret, /v1/guidance, /v1/compatibility, /v1/guna-milan
Readings grounded in classical Vedic methodology
Interpretation applies classical rules, and each reading names the classical texts it is grounded in.
/v1/interpret
Nothing silently missing
Every reading declares each of its layers as present, computed_empty, not_covered or failed, so an absent field is never left to guesswork.
/v1/interpret and the other readings
Birth-time sensitivity, stated
Where an uncertain birth time would change the reading, the compatibility response says so.
/v1/compatibility
Muhūrta at the event's place
The pañcāṅga for a muhūrta is computed where the event happens, never defaulted to the birthplace.
/v1/muhurta
Guidance for the running periods
What the current daśā chapter, period and stretch ask of the person: conduct to keep, with the classical reason for each.
/v1/guidance
Jyotiṣa, Western and relocation in one call
One chart call returns the sidereal chart with yogas and daśā, tropical positions and aspects, astrocartography lines, and the house frame relocated to any place.
/v1/chart
Our own engine, on NASA JPL's DE440 ephemeris
Positions come from AstroNest's own engine, which reads NASA JPL's DE440 ephemeris directly, not a wrapper around Swiss Ephemeris, and raw positions, cusps, ayanamsa and sunrise are sold on the same key.
/v1/ephemeris/*
Built for AI agents
A Model Context Protocol server with typed inputs and outputs, listed in the official MCP Registry and on Smithery.
/api/developer/mcp
A sandbox that returns real responses
Sandbox keys are free with no time limit and return captured production responses, never mock data, so you build against the real shape.
every endpoint
Quickstart
Your first call in three steps
- Sign in at /developer and create a sandbox key. Sandbox calls are free, with no time limit, and return fixed sample responses.
- Call any endpoint. A sandbox key validates your request exactly as live does, then returns a fixed sample response.
- 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
| Key | What it returns | Cost |
|---|---|---|
astro_sandbox_… | Validates your request with the same error codes as live, then returns a fixed sample (the example on each endpoint below), marked sandbox: true and with an X-AstroNest-Sandbox: true header. Your inputs are checked, not used. | Free, no time limit |
astro_live_… | A real computation for the birth data you send. | Credits per call |
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.
Free terms
Free to start: sandbox keys, plus 100 free live credits once
Sandbox key — free, no time limit
- Every endpoint and MCP tool answers with a fixed sample response; your input is validated exactly as live, never used.
- Never charged and never expires. Limits: 120 requests a minute, 2 at a time.
- It does not compute real readings: for that you need a live key.
100 free live credits — once, valid 60 days
- Granted once per account, for live keys. A live key needs the beta terms accepted and a verified email.
- Valid for 60 days from when you create your first live key; any left after that expire. They do not renew.
- Spent before any paid credits, on successful calls only (a chart costs 1, a domain reading 5).
When the free credits are used up or expire
- After 100 credits or 60 days, whichever comes first, live calls return 402 credits_exhausted. Nothing is charged automatically: sandbox keys keep working, and your keys and settings stay.
What to do next
- Buy a credit pack in the portal: Starter $49 for 1,000 credits, Builder $199 for 5,000, Growth $499 for 15,000. One-time purchases, no subscription; paid credits never expire.
- High volume or a platform? Talk to us about Platform (custom pricing).
starter
$49
1,000 credits · 4.9¢ each
builder
$199
5,000 credits · 4.0¢ each
growth
$499
15,000 credits · 3.3¢ each
Platform
Custom pricing
Volume pricing · Higher concurrency · Dedicated support · Commercial SLA
Talk to us →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.
| Endpoint | What it does | Credits |
|---|---|---|
| /v1/chart | Natal chart (kundli) Calculation | 1 |
| /v1/dasha | Life-period timeline (planetary periods) Calculation | 1 |
| /v1/techniques | Classical techniques for a chart Calculation | 3 |
| /v1/guna-milan | Guna Milan (36-point Aṣṭakūṭa) and Manglik Calculation | 2 |
| /v1/guidance | Guidance for the running daśā periods Interpretation | 3 |
| /v1/prashna | Praśna (horary): a question, a deal, or a horary number Interpretation | 3 |
| /v1/interpret | Reading of one life area Interpretation | 5 |
| /v1/life-reading | Whole-life reading Interpretation | 10 |
| /v1/domain-timeline | Life-area timeline Interpretation | 3 |
| /v1/relationship | Relationship reading (non-marital) Interpretation | 8 |
| /v1/venture-timing | Venture timing: when to commit, which business Interpretation | 10 |
| /v1/gem-assessment | Gemstone assessment Interpretation | 5 |
| /v1/compatibility | Marriage compatibility: the full reading Interpretation | 12 |
| /v1/muhurta | Auspicious windows (muhūrta) in a date range Interpretation | 10 |
| /v1/forecast | Written answer about what lies ahead Narrated | 8 |
| /v1/timing/resolve | Is this a good time? (decision timing) Narrated | 7 |
| /v1/ephemeris/positions | Positions at a moment Ephemeris | 0.1 |
| /v1/ephemeris/angles | Ascendant, MC and house cusps Ephemeris | 0.1 |
| /v1/ephemeris/ayanamsa | Ayanamsa values Ephemeris | 0.1 |
| /v1/ephemeris/sunrise | Sunrise and sunset Ephemeris | 0.1 |
| /v1/ephemeris/series | Positions over a range Ephemeris | 1 |
Calculation
Deterministic computation. No language model is called.
POST/v1/chart
1 creditNatal chart (kundli).
Use it when someone wants their birth chart (kundli): ascendant, planets in signs and houses, yogas, the current planetary periods, or one of the classical sub-charts.
Sidereal chart: ascendant, the nine grahas, twelve houses, yogas and the life-period (daśā) timeline. A modern Western block is added unless `western` is false. With `location`, also astrocartography lines at that place and the chart's own frame relocated there. Includes two classical sub-charts by default; ask for any of the others with `divisionals`.
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
}
}POST/v1/dasha
1 creditLife-period timeline (planetary periods).
Use it when someone asks which planetary period (daśā) they are in, when it ends, or which periods are coming.
The current periods include the running pratyantardaśā; send depth 'pratyantardasha' for the full timeline at that level.
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
}
}POST/v1/techniques
3 creditsClassical techniques for a chart.
Use it when someone or an astrologer asks for a specific classical computation — planetary strength, transit point tables, another life-period timeline, the annual chart, house cusps, a named yoga, the birth pañcāṅga, Manglik, house lords and aspects — rather than for a reading. Pass `sections` to fetch only what is needed.
The computed classical working for a chart, no model: strength scores for each planet and house, point tables for transit support, further life-period timelines with the periods running at `referenceDate`, the full planetary-period ladder, the annual chart for the year running at `referenceDate`, house-cusp and ruling-planet tables, classical yogas, special ascendants and aspects, the natal pañcāṅga, house lords with planetary aspects, Manglik (Kuja doṣa) with its exceptions, and what would change under another ayanāṁśa. Each section is `{computed: true, data}` or `{computed: false, reason}` — a technique that cannot be computed for this chart (for example without a birth time) says why and the rest still return. No verdicts, scores or lifespan figures.
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"sections": [
"shadbala",
"dashas",
"panchanga"
],
"referenceDate": "2026-10-14T00:00:00Z"
}POST/v1/guna-milan
2 creditsGuna Milan (36-point Aṣṭakūṭa) and Manglik.
Use it when someone asks for the guna milan / kundli matching score (out of 36), or whether either person is Manglik.
The classical Aṣṭakūṭa match for a pair (all eight kūṭas, with the Bhakoot and Nāḍī doṣas) and Manglik for both charts reckoned from the lagna, the Moon and Venus, with mutual cancellation. The same engine as /v1/compatibility, without the full reading: the score is one input, and /v1/compatibility reads each chart's marital promise, timing and doṣas on top of it. Deterministic, no language model.
Required: a, b
{
"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"
}
}Interpretation
Deterministic readings in classical Vedic methodology. No language model is called.
POST/v1/guidance
3 creditsGuidance for the running daśā periods.
Use it when someone asks how to conduct themselves in the period they are in: what to do and what to take care with, each with its classical reason. Guidance, not prediction.
Plain-language guidance cards for each running daśā level (mahādaśā, antardaśā, …) at `referenceDate` (default: now).
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
}
}POST/v1/prashna
3 creditsPraśna (horary): a question, a deal, or a horary number.
Use it when someone asks a specific question and wants it answered from the moment of asking rather than from a birth chart — "will this deal close?", "will I recover?", "will I find what I lost?" — or when an astrologer gives a horary number 1–249. Send where the user is as `place`; it is never defaulted.
The chart of the moment and place a question is asked, read on classical praśna rules, no model. Always: the praśna lagna and its lord, the Moon, the house of the matter asked about, the classical rules that apply (recovery from illness for a health question; recovery of a lost article when the question names one), and the further classical rules that held on this chart, each with its reference and the chart facts that made it hold. With `deal`: the deal praśna — significators (lagna lord = you, 7th = the other side, 10th = the undertaking, 11th = gain), their planetary contacts, the grounds for and against, and an ordered verdict (perfects, perfects after obstacles, contested, delayed, delayed and contested, not perfected); add `birthData` for the natal commitment calendar beside it, never blended with it. With `horaryNumber` (1–249): the horary table — house cusps for the moment that number rises, planets at the moment of judgment, their ruling lords, and the ruling planets; no judgment is asserted from it. Rules about caste, prenatal sex or death timing are withheld and counted.
Required: place
{
"place": {
"latitude": 28.6139,
"longitude": 77.209,
"timezone": "Asia/Kolkata",
"label": "New Delhi"
},
"askedAt": "2026-10-14T10:30:00+05:30",
"question": "Will the supply contract with Northwind be signed?",
"deal": {
"label": "Northwind supply contract",
"kind": "contract",
"signingDate": "2026-11-02"
},
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"horaryNumber": 108
}POST/v1/interpret
5 creditsReading of one life area.
Use it when someone asks what their chart says about one area of life (career, marriage, finance, health, property, children, education, travel, legal and others) and a reproducible verdict with its reasons and sources is wanted. Prefer it to get_forecast when no written narrative is needed.
Deterministic reading of one life area: the verdict, the factors for and against it, timing windows, a cross-check of the verdict, and the classical texts it is grounded in. Every layer is declared as present, computed_empty, not_covered or failed, so nothing is silently missing. No language model is called: the same chart always gets the same reading.
Required: birthData, domain
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"domain": "career"
}POST/v1/life-reading
10 creditsWhole-life reading.
Use it when someone wants their life as a whole: which life areas (marriage, children, career, business, money, property, family, travel, education, spirituality, health) are in focus when, across past and future, and where life stands now.
The life's chapters (each mahādaśā in plain words, with dates and ages) and eleven life areas, each with the planets that govern it on this chart, every governing period past and future with why that planet governs it — each marked `primary` (the area is in focus) or `also` (the period only touches it) — and what is in focus now and next. Past periods are included, so the reading can be tested against a life already lived; send `recorded` events to place them on the timeline. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required. The full reading is large; pass `areas` to return only the life areas you need.
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"areas": [
"career",
"relationship"
],
"recorded": [
{
"type": "job_start",
"date": "2012-07-01",
"certainty": "exact"
},
{
"type": "marriage",
"date": "2018-11-25",
"certainty": "exact"
}
]
}POST/v1/domain-timeline
3 creditsLife-area timeline.
Use it when someone asks about one area of life — when marriage, children, career, money, property or another area is in focus, or what a given stretch of years holds for it.
One life area across the whole life: the planets that govern it on this chart, every period that bears on it (past and future, with dates, ages and why that planet governs it), each marked `primary` when the area is in focus or `also` when the period only touches it, and what is in focus now and next, in plain words. Pass `window` to get only the periods that overlap a date range. It is the same reading as the whole-life reading, cut to one area, so the two never disagree. Health is read only as periods to give extra care, never as illness or lifespan. Deterministic: no language model is called. The birth time is required.
Required: birthData, area
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"area": "relationship",
"window": {
"from": "2026-01-01",
"to": "2031-12-31"
}
}POST/v1/relationship
8 creditsRelationship reading (non-marital).
Use it when someone asks how two people get on in a bond other than marriage — business partners, siblings, a parent and child, or friends.
Reads the bond the way the classical method reads it: the houses that govern this kind of bond and their lords in each chart, the natural significators, whose planets fall in whose governing houses, and whether that reach runs both ways, plus the running periods in each chart that engage the bond. A bond meter (strong tie, workable or strained) is computed by a stated convention and returned with every point it is built from; it is not a classical score, since the texts give no arithmetic for a business or sibling match. Deterministic: no language model is called. Both birth times are required. For marriage, use the compatibility tool.
Required: type, a, b
{
"type": "business",
"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"
}
}POST/v1/venture-timing
10 creditsVenture timing: when to commit, which business.
Use it when someone asks when to start, launch, sign, borrow or expand a business, or which line of business their chart supports.
A calendar of the coming months in four labels — commit (sign, open, launch), build (keep building; commit only what can be undone), guarded (low fixed cost; no lease, no borrowing) and hold (no new fixed commitments) — each window with the daśā period running and the slow transits of Saturn and Jupiter over it, and the reasons. Describe the businesses being weighed in `ventures` and each is ranked on how strongly the chart supports it and whether the coming periods carry it, with the grounds, its best coming period, and a caution when it needs premises during a hold; name none and the full catalogue of business types is ranked. A ranking of chart support, never a probability of success. Deterministic: no language model is called. The birth time is required.
Required: birthData
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"ventures": [
"software and data platform for businesses",
"a restaurant in a leased storefront",
"OneDot"
],
"months": 36
}POST/v1/gem-assessment
5 creditsGemstone assessment.
Use it when someone asks whether they should wear a particular gemstone (blue sapphire, emerald, pukhraj, a crystal), or whether a stone they wear suits their chart.
Answers the prescription, not the future: which planet the stone strengthens, what that planet owns from this ascendant, whether a classical rule (a dusthāna or kendrādhipati lordship, a māraka) argues against strengthening it, and whether the reason is permanent or lasts only as long as the running period. Returns a verdict — well_founded, period_bound, no_ground, contraindicated or unrecognised — with every ground for and against, the planet's capacity at its degree, when the chart puts the planet in scope, the stones the sources hold apart from it (checked against `alsoWearing`), and wearing detail (finger, metal, day, weight, with the book it comes from) only when the chart gives a reason to wear it. When the source states a caution about the stone, the response says so and names the book. A word that covers several stones ("sapphire") is answered with the candidates. Nothing here predicts what a stone does. Deterministic: no language model is called. The birth time is required.
Required: birthData, gem
{
"birthData": {
"date": "1990-05-12",
"time": "14:35",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
},
"gem": "blue sapphire",
"alsoWearing": [
"ruby"
]
}POST/v1/compatibility
12 creditsMarriage compatibility: the full reading.
Use it when someone asks whether two people are a good match for marriage and wants the full reading, not only a score. For the fast 36-point score with Manglik alone, use get_guna_milan.
Both charts read together for marriage. The 36-point Aṣṭakūṭa (guna milan) is one input: the verdict names the governing factor and says when it outweighs the score. Also returned: each chart's marital promise, sustainability and happiness, progeny, Manglik reckoned from the lagna, the Moon and Venus with mutual cancellation, a joint marriage-timing window, synastry, and caveats where an uncertain birth time would change the reading. Deterministic: no language model is called. Each partner is a BirthData object plus optional `name` and `gender`.
Required: a, b
{
"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"
}
}POST/v1/muhurta
10 creditsAuspicious windows (muhūrta) in a date range.
Use it when someone asks for an auspicious date or time (muhūrta) to do something, such as a wedding, launch, move or purchase, within a date range at a given place.
Scans each day in the range and ranks windows for the subject. The pañcāṅga is computed for `eventPlace`, never defaulted to the birthplace.
Required: subject, eventPlace, rangeStart, rangeEnd
{
"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"
}Narrated
Readings voiced by a language model, grounded in the deterministic verdict. Slower (tens of seconds).
POST/v1/forecast
8 creditsWritten answer about what lies ahead.
Use it when someone asks an open question about what lies ahead in one area of life and wants a written answer. It takes tens of seconds; for a fast, structured verdict use interpret_domain.
The interpret verdict for `domain`, voiced as a narrative answer to `question` by a language model grounded in the classical statements for the domain. Expect tens of seconds; set a client timeout of at least 90 s.
Required: birthData, domain, question
{
"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?"
}POST/v1/timing/resolve
7 creditsIs this a good time? (decision timing).
Use it when someone asks whether now, or a particular date or range, is a good time for a decision such as changing jobs, marrying or investing. It takes tens of seconds.
The interpret verdict for `domain`, voiced by a language model as an answer to a decision `question`, read at `targetDate` (or the start of `dateRange`, or today when neither is sent): the verdict, the running daśā and eventTiming are taken at that day. A malformed or pre-birth date is refused with 400 (`invalid_target_date`, `invalid_date_range`). Expect tens of seconds; set a client timeout of at least 90 s.
Required: birthData, domain, question
{
"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"
}Ephemeris
Raw astronomical positions from AstroNest’s own engine, built on NASA JPL’s DE440 ephemeris: no Swiss Ephemeris licence or other astrology API needed. Deterministic, about a millisecond per position, no language model. One key scope (`ephemeris`) covers all five operations.
POST/v1/ephemeris/positions
0.1 creditPositions at a moment.
Use it when you need where the Sun, Moon and planets are at a moment (sidereal or tropical), not a reading.
Sun, Moon, planets and lunar nodes at one moment: longitude, latitude, distance, speed and retrograde flag, with sign, and nakṣatra and its quarter when sidereal. `equatorial: true` adds apparent right ascension and declination.
Required: datetime
{
"datetime": "2026-10-06T06:00:00Z",
"bodies": [
"Sun",
"Moon",
"Mars",
"Jupiter",
"Saturn",
"TrueNode"
],
"zodiac": "sidereal",
"ayanamsa": "lahiri"
}POST/v1/ephemeris/angles
0.1 creditAscendant, MC and house cusps.
Use it when you need the ascendant, midheaven or house cusps for a moment and place.
Ascendant, midheaven and twelve cusps for a moment and place. Placidus is undefined beyond the polar circles at some moments; the call then returns 422 houses_undefined_at_latitude.
Required: datetime, latitude, longitude
{
"datetime": "1990-05-12T14:35:00+05:30",
"latitude": 28.6139,
"longitude": 77.209,
"houseSystem": "placidus"
}POST/v1/ephemeris/ayanamsa
0.1 creditAyanamsa values.
Use it when you need an ayanamsa value at a moment.
The ayanāṁśa (the sidereal offset) at a moment, for each supported ayanāṁśa (mean, without nutation).
Required: datetime
{
"datetime": "2026-10-06T00:00:00Z"
}POST/v1/ephemeris/sunrise
0.1 creditSunrise and sunset.
Use it when you need sunrise and sunset for a date and place, or where the Vedic day begins.
Sunrise, sunset and the next sunrise for a local date and place: upper limb at the sea-level horizon with 36.6′ refraction. The Vedic day runs from sunrise to the next sunrise.
Required: date, timezone, latitude, longitude
{
"date": "2026-10-06",
"timezone": "Asia/Kolkata",
"latitude": 28.6139,
"longitude": 77.209
}POST/v1/ephemeris/series
1 creditPositions over a range.
Use it when you need planetary positions across a range of dates, for a transit table or to find when a planet changes sign or stations.
Positions from start to end (inclusive) every stepMinutes, for transit tables and station finding. At most 1,000 points (too_many_points beyond). A 365-point daily table costs 4 credits.
Required: start, end, stepMinutes
{
"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:
careerbusinessfinancechildrenpropertyeducationtravelspiritualitylineagereputationpartnershipslegalfamilymarriagehealthCoverage
Reading the coverage object
Every reading response carries coverage, and every layer in it is always named. You never have to infer that a layer was skipped from a missing key, which is what the object exists to prevent. A layer being empty or unavailable does not mean the call failed; the verdict and its timing stand on their own.
| State | Meaning |
|---|---|
present | The layer ran and returned something. The matching top-level key is populated. |
computed_empty | The layer ran and found nothing for this chart. A RESULT, not an error: a domain with no classical title behind it is a real and reportable state. |
not_covered | This endpoint does not carry that layer for this request. Nothing went wrong; ask a different endpoint. |
failed | The layer errored or timed out. Every layer is computed fail-open, so the rest of the response is unaffected, but do not read its absence as agreement or as emptiness. |
The one to handle deliberately is methodAgreement. When present it tells you whether the engine’s own routes reached the opposite reading from the verdict in the same response. Treating a failed there as “the methods agreed” is the single most costly misreading of this response.
Responses also echo readingWindow: the referenceDate and timezone actually used. If you sent neither, this is how you find out what the server chose, so a response can be reproduced exactly.
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.
| Status | Meaning |
|---|---|
| 400 | Invalid request. Codes: invalid_json, missing_birthdata, invalid_birthdata, invalid_timezone, invalid_coordinates, missing_required_field, invalid_domain, invalid_reference_date, invalid_range, no_days_evaluable. Not charged. |
| 401 | missing_api_key, invalid_api_key, revoked_key or expired_key. Not charged. |
| 402 | credits_exhausted: the one-time free credits are used or have expired (60 days from the first live key) and the paid balance is too low for this call; buy a credit pack in the developer portal. key_credit_limit_reached: this key has reached the monthly credit limit set on it in the portal (resets on the 1st, UTC). Never charged. |
| 403 | insufficient_scope: the key is not scoped for this endpoint. Not charged. |
| 422 | chart_integrity_failed, dasha_failed or guidance_failed: the birth data could not produce a valid result. Not charged. |
| 429 | rate_limited (over 120 requests a minute for this account) or concurrency_limit (too many requests at once). Retry-After says when to retry. Not charged. |
| 500 | Our error. Not charged. |
| 502 | narration_failed: the language model did not return a reading. Not 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.
- 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.
- Readings are symbolic interpretation only — not medical, legal, financial or psychological advice. You show the response's
disclaimerto your users and do not present a reading as a diagnosis or a guarantee. - 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.
- You keep your keys secret and call the API from your server. You are responsible for calls made with your keys.
- 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.
- 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.
- 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.
- 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.
Drafts of the full documents, under review: the Developer API terms of service and the Developer API privacy policy, which also cover the MCP server and connections from AI assistants. Questions: astronest@onedotlinks.com.
Use responsibly
Symbolic interpretation only — not medical, legal, financial or psychological advice. Show the disclaimer field to your users. The API is in beta: there is no SLA yet, and the terms of service are being finalised.