Vedic astrology for AI agents: kundli, daśā, guna milan, life, venture and gem readings, ephemeris.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <your AstroNest API key>. Free sandbox keys at https://www.astronest.ai/developer
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Use this when the user 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. Cost: 5 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"gem":"blue sapphire","alsoWearing":["ruby"]}
One stone, in English or by its Indian name: "yellow sapphire", "pukhraj", "emerald", "moonstone".
The person's birth data. The time is required: every period depends on the rising sign.
Optional: stones already worn. When the chart puts the planet in scope, a pairing the sources hold apart is reported as a conflict.
Use this when the user 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. Cost: 5 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"gem":"blue sapphire","alsoWearing":["ruby"]}
| Argument | Type | Description |
|---|---|---|
| gem* | string | One stone, in English or by its Indian name: "yellow sapphire", "pukhraj", "emerald", "moonstone". |
| birthData* | object | The person's birth data. The time is required: every period depends on the rising sign. |
| alsoWearing | array | Optional: stones already worn. When the chart puts the planet in scope, a pairing the sources hold apart is reported as a conflict. |
{
"type": "object",
"required": [
"birthData",
"gem"
],
"properties": {
"gem": {
"type": "string",
"maxLength": 60,
"minLength": 2,
"description": "One stone, in English or by its Indian name: \"yellow sapphire\", \"pukhraj\", \"emerald\", \"moonstone\"."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data. The time is required: every period depends on the rising sign."
},
"alsoWearing": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 9,
"description": "Optional: stones already worn. When the chart puts the planet in scope, a pairing the sources hold apart is reported as a conflict."
}
}
}Use this when the user 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. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}
| Argument | Type | Description |
|---|---|---|
| topN | integer | How many ranked windows to return. Default 5. |
| eventId | string | Event type identifier, if known. |
| subject* | object | Birth data of the person the event is for; windows are ranked against their chart. |
| freeText | string | The event described in words, when there is no eventId. |
| rangeEnd* | string | Last date to search, YYYY-MM-DD. |
| timeOfDay | string | Local time (HH:MM) at which each day is evaluated. Default: local sunrise. |
Use this when the user wants their birth chart (kundli): ascendant, planets in signs and houses, yogas, the current planetary periods, or a divisional chart such as the navāṁśa (D9). Sidereal (Lahiri) chart: ascendant, the nine grahas, twelve houses, yogas and the Vimśottarī daśā. 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 the D9 and D10 divisional charts by default; ask for any of the sixteen ṣoḍaśavarga with `divisionals`. Cost: 1 credit per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}
| Argument | Type | Description |
|---|---|---|
| western | boolean | Set false to omit the modern Western block. |
| location | object | Both coordinates or neither: a half-filled location is refused, never defaulted. |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
| divisionals | array | Divisional charts (vargas) to include: any of the sixteen ṣoḍaśavarga. Default d9 (navāṁśa) and d10 (daśāṁśa); send [] for none. Each returns its ascendant and every graha's sign, degree and house within the varga, by the Parāśari formulas. |
| includeDasha |
Use this when the user 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`. Cost: 12 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}}
| Argument | Type | Description |
|---|---|---|
| a* | any | First partner: birth data plus optional name and gender. |
| b* | any | Second partner: birth data plus optional name and gender. |
| referenceDateIso | string | ISO date the reading is anchored to. Defaults to now. |
{
"type": "object",
"required": [
"a",
"b"
],
"properties": {
"a": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "First partner: birth data plus optional name and gender."
},
"b": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "Second partner: birth data plus optional name and gender."
},
"referenceDateIso": {
"type": "string",
"description": "ISO date the reading is anchored to. Defaults to now."
}
}
}Use this when the user 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. Cost: 1 credit per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}
| Argument | Type | Description |
|---|---|---|
| depth | string | Timeline depth. 'pratyantardasha' nests the pratyantardaśās under each antardaśā (about ten times larger). The current periods always include the running pratyantardaśā. |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
{
"type": "object",
"required": [
"birthData"
],
"properties": {
"depth": {
"enum": [
"antardasha",
"pratyantardasha"
],
"type": "string",
"default": "antardasha",
"description": "Timeline depth. 'pratyantardasha' nests the pratyantardaśās under each antardaśā (about ten times larger). The current periods always include the running pratyantardaśā."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
}
}
}Use this when the user 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. Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}}
| Argument | Type | Description |
|---|---|---|
| area* | string | The life area. |
| window | object | Optional: only periods overlapping this date range (YYYY-MM-DD). Default: the whole life. |
| birthData* | object | The person's birth data. The time is required: every period depends on the rising sign. |
{
"type": "object",
"required": [
"birthData",
"area"
],
"properties": {
"area": {
"enum": [
"relationship",
"children",
"education",
"career",
"business",
"money",
"property",
"family",
"travel",
"spirituality",
"health"
],
"type": "string",
"description": "The life area."
},
"window": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"format": "date"
},
"from": {
"type": "string",
"format": "date"
}
},
"description": "Optional: only periods overlapping this date range (YYYY-MM-DD). Default: the whole life."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data. The time is required: every period depends on the rising sign."
}
}
}Use this 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. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"1990-05-12T14:35:00+05:30","latitude":28.6139,"longitude":77.209,"houseSystem":"placidus"}
| Argument | Type | Description |
|---|---|---|
| zodiac | string | sidereal (default) or tropical. |
| ayanamsa | string | Sidereal only. |
| datetime* | string | ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime). |
| latitude* | number | Geographic latitude in decimal degrees, north positive. |
| longitude* | number | East positive. |
| houseSystem | string | House system for the cusps: whole_sign (default), equal or placidus. |
Use this when you need an ayanamsa value (Lahiri, Raman, Krishnamurti, Fagan–Bradley) at a moment. Lahiri, Raman, Krishnamurti and Fagan–Bradley (mean, without nutation) at a moment. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"2026-10-06T00:00:00Z"}
| Argument | Type | Description |
|---|---|---|
| datetime* | string | ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime). |
{
"type": "object",
"required": [
"datetime"
],
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
}
}
}Use this 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 pada when sidereal. `equatorial: true` adds apparent right ascension and declination. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"datetime":"2026-10-06T06:00:00Z","bodies":["Sun","Moon","Mars","Jupiter","Saturn","TrueNode"],"zodiac":"sidereal","ayanamsa":"lahiri"}
| Argument | Type | Description |
|---|---|---|
| bodies | array | Default: all twelve. |
| zodiac | string | sidereal (default) or tropical. |
| ayanamsa | string | Sidereal only. |
| datetime* | string | ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime). |
| equatorial | boolean | Also return apparent right ascension and declination. Default false. |
{
"type": "object",
"required": [
"datetime"
],
"properties": {
"bodies": {
"type": "array",
"items": {
"enum": [
"Sun",
"Moon",
"Mercury",
"Venus",
"Mars",
"Jupiter",
"Saturn",
"Uranus",
"Neptune",
"Pluto",
"MeanNode",
"TrueNode"
],
"type": "string",
"description": "MeanNode and TrueNode are Rāhu (mean or true); Ketu is the node + 180°. Every AstroNest chart, reading and timing endpoint uses the mean node."
},
"description": "Default: all twelve."
},
"zodiac": {
"enum": [
"sidereal",
"tropical"
],
"type": "string",
"default": "sidereal",
"description": "sidereal (default) or tropical."
},
"ayanamsa": {
"enum": [
"lahiri",
"raman",
"krishnamurti",
"fagan_bradley"
],
"type": "string",
"default": "lahiri",
"description": "Sidereal only."
},
"datetime": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
},
"equatorial": {
"type": "boolean",
"default": false,
"description": "Also return apparent right ascension and declination. Default false."
}
}
}Use this 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. Cost: 1 credit per started 100 points (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"start":"2026-10-01T00:00:00Z","end":"2026-10-10T00:00:00Z","stepMinutes":1440,"bodies":["Mercury","Venus"]}
| Argument | Type | Description |
|---|---|---|
| end* | string | ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime). |
| start* | string | ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime). |
| bodies | array | Default: all twelve. |
| zodiac | string | sidereal (default) or tropical. |
| ayanamsa | string | Sidereal only. |
| stepMinutes* | integer | Minutes between points (1 to 525,600). At most 1,000 points per call. |
Use this 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. Cost: 0.1 credit per call, billed as 1 credit per started block of 10 Ephemeris calls (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"date":"2026-10-06","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}
| Argument | Type | Description |
|---|---|---|
| date* | string | Local calendar date, YYYY-MM-DD. |
| latitude* | number | Geographic latitude in decimal degrees, north positive. |
| timezone* | string | IANA name, e.g. Asia/Kolkata. Defines the local day. |
| longitude* | number | East positive. |
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Local calendar date, YYYY-MM-DD."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Geographic latitude in decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA name, e.g. Asia/Kolkata. Defines the local day."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "East positive."
}
}
}Use this when the user 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. Cost: 8 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Voiced by a language model: allow up to 90 seconds. Example arguments: {"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?"}
| Argument | Type | Description |
|---|---|---|
| domain* | string | Life area the question is about, e.g. career, marriage, finance or health. |
| question* | string | The question in plain language, e.g. "What does the next year hold for my career?" |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
{
"type": "object",
"required": [
"birthData",
"domain",
"question"
],
"properties": {
"domain": {
"enum": [
"career",
"business",
"finance",
"children",
"property",
"education",
"travel",
"spirituality",
"lineage",
"reputation",
"partnerships",
"legal",
"family",
"marriage",
"health"
],
"type": "string",
"description": "Life area the question is about, e.g. career, marriage, finance or health."
},
"question": {
"type": "string",
"minLength": 1,
"description": "The question in plain language, e.g. \"What does the next year hold for my career?\""
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
}
}
}Use this when the user 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). Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209}}
| Argument | Type | Description |
|---|---|---|
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
| referenceDate | string | ISO date or datetime. Defaults to now. |
{
"type": "object",
"required": [
"birthData"
],
"properties": {
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
},
"referenceDate": {
"type": "string",
"description": "ISO date or datetime. Defaults to now."
}
}
}Use this when the user 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. Cost: 2 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}}
| Argument | Type | Description |
|---|---|---|
| a* | any | First partner: birth data plus optional name and gender. |
| b* | any | Second partner: birth data plus optional name and gender. |
{
"type": "object",
"required": [
"a",
"b"
],
"properties": {
"a": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "First partner: birth data plus optional name and gender."
},
"b": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "Second partner: birth data plus optional name and gender."
}
}
}Use this when the user 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. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}]}
| Argument | Type | Description |
|---|---|---|
| areas | array | Optional: only these life areas (default all eleven). The full reading is large, so an AI agent answering about one area should pass it here. |
| recorded | array | Optional dated life events to place on the timeline. |
| birthData* | object | The person's birth data. The time is required: every period depends on the rising sign. |
Use this when the user 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 a KP 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 the classical praśna rules, no model. Always: the praśna lagna and its lord, the Moon, the house of the matter asked about, the hand-encoded classical dicta that apply (recovery from illness for a health question; recovery of a lost article when the question names one), and the rules from the praśna books in the corpus that held on this chart, each with its book 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 Tājika 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 KP horary table — Placidus cusps in the Krishnamurti ayanāṁśa for the moment that sub rises, planets at the moment of judgment, sign/star/sub/sub-sub lords, and the ruling planets; no KP judgment is asserted. Rules about caste, prenatal sex or death timing are withheld and counted. Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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}
| Argument | Type | Description |
|---|---|---|
| deal | object |
Use this when the user 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. Cost: 8 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}}
| Argument | Type | Description |
|---|---|---|
| a* | any | First person: birth data (time required) plus optional name. |
| b* | any | Second person: birth data (time required) plus optional name. |
| type* | string | The bond. For marriage, call /v1/compatibility. |
{
"type": "object",
"required": [
"type",
"a",
"b"
],
"properties": {
"a": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "First person: birth data (time required) plus optional name."
},
"b": {
"allOf": [
{
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"gender": {
"enum": [
"male",
"female"
],
"type": "string"
}
}
}
],
"description": "Second person: birth data (time required) plus optional name."
},
"type": {
"enum": [
"business",
"sibling",
"parent_child",
"friend"
],
"type": "string",
"description": "The bond. For marriage, call /v1/compatibility."
}
}
}Use this when the user or an astrologer asks for a specific classical computation — Ṣaḍbala, Aṣṭakavarga, Yoginī/Chara/Nārāyaṇa daśā, Varṣaphal, KP cusps, a named yoga, the birth pañcāṅga, Kuja doṣa, 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: Ṣaḍbala and bhāva bala (BPHS 27), Aṣṭakavarga with trikoṇa/ekādhipatya reduction and piṇḍas, the Aṣṭottarī, Kālacakra, Nārāyaṇa, Yoginī and Chara daśās with the periods running at `referenceDate`, the full Vimśottarī ladder, the Varṣaphal (Tājika annual chart) for the year running at `referenceDate`, KP cusps with sub-lords and ruling planets (labelled KP only when the KP frame was computed), classical and Nābhasa yogas, kārakāṁśa, argala, special lagnas, bhāva chalit, the natal pañcāṅga, house lords with graha dṛṣṭi, Kuja doṣa with its exceptions, and what would change under the Raman or KP 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. Cost: 3 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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"}
| Argument | Type | Description |
|---|---|---|
| sections | array | Return only these sections. Default: all. |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
| residence |
Use this when the user 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. Cost: 10 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"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}
| Argument | Type | Description |
|---|---|---|
| months | integer | How far ahead the calendar runs, and the horizon each venture's period support is averaged over. |
| ventures | array | Optional: the businesses being weighed, each described by what it does ("software for accountants", "a café with a leased storefront"). A brand name alone cannot be placed and is returned as unclassified. Omit to rank the whole catalogue. |
| birthData* | object |
Use this when the user 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, whether the engine's own methods agree, and the classical books the reading draws on. 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. Cost: 5 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Deterministic: the same input always gives the same answer. Example arguments: {"birthData":{"date":"1990-05-12","time":"14:35","timezone":"Asia/Kolkata","latitude":28.6139,"longitude":77.209},"domain":"career"}
| Argument | Type | Description |
|---|---|---|
| domain* | string | Life area to read, e.g. career, marriage, finance or health. |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
{
"type": "object",
"required": [
"birthData",
"domain"
],
"properties": {
"domain": {
"enum": [
"career",
"business",
"finance",
"children",
"property",
"education",
"travel",
"spirituality",
"lineage",
"reputation",
"partnerships",
"legal",
"family",
"marriage",
"health"
],
"type": "string",
"description": "Life area to read, e.g. career, marriage, finance or health."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
}
}
}Use this when the user 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. Cost: 7 credits per call (only successful calls are charged; a sandbox key is free and returns a fixed sample). Voiced by a language model: allow up to 90 seconds. Example arguments: {"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"}
| Argument | Type | Description |
|---|---|---|
| domain* | string | Life area the decision is about, e.g. career, marriage, finance or health. |
| question* | string | The decision question in plain language, e.g. "Is this a good time to change jobs?" |
| birthData* | object | The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude. |
| dateRange | object | Optional period the decision is about: start and end dates, YYYY-MM-DD. The verdict is read at `start`; `end` must not precede it. |
| eventPlace* | object | Where the event will happen: latitude, longitude and IANA timezone. The pañcāṅga is computed here, never at the birthplace. |
| rangeStart* | string | First date to search, YYYY-MM-DD. |
| subjectName | string | Optional name of the subject, used only in the response text. |
{
"type": "object",
"required": [
"subject",
"eventPlace",
"rangeStart",
"rangeEnd"
],
"properties": {
"topN": {
"type": "integer",
"minimum": 1,
"description": "How many ranked windows to return. Default 5."
},
"eventId": {
"type": "string",
"description": "Event type identifier, if known."
},
"subject": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "Birth data of the person the event is for; windows are ranked against their chart."
},
"freeText": {
"type": "string",
"description": "The event described in words, when there is no eventId."
},
"rangeEnd": {
"type": "string",
"format": "date",
"description": "Last date to search, YYYY-MM-DD."
},
"timeOfDay": {
"type": "string",
"description": "Local time (HH:MM) at which each day is evaluated. Default: local sunrise."
},
"eventPlace": {
"type": "object",
"required": [
"latitude",
"longitude",
"timezone"
],
"properties": {
"label": {
"type": "string"
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone"
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "Where the event will happen: latitude, longitude and IANA timezone. The pañcāṅga is computed here, never at the birthplace."
},
"rangeStart": {
"type": "string",
"format": "date",
"description": "First date to search, YYYY-MM-DD."
},
"subjectName": {
"type": "string",
"description": "Optional name of the subject, used only in the response text."
}
}
}| boolean |
| Include the Vimśottarī daśā periods in the chart response. Default true. |
{
"type": "object",
"required": [
"birthData"
],
"properties": {
"western": {
"type": "boolean",
"default": true,
"description": "Set false to omit the modern Western block."
},
"location": {
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
},
"orbDegrees": {
"type": "number",
"default": 3,
"maximum": 15,
"description": "Orb as a ground distance in degrees of great-circle arc (1 degree = about 111 km at any latitude). Widened for an approximate birth time; no lines for an unknown one."
}
},
"description": "Both coordinates or neither: a half-filled location is refused, never defaulted."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
},
"divisionals": {
"type": "array",
"items": {
"enum": [
"d1",
"d2",
"d3",
"d4",
"d7",
"d9",
"d10",
"d12",
"d16",
"d20",
"d24",
"d27",
"d30",
"d40",
"d45",
"d60"
],
"type": "string"
},
"default": [
"d9",
"d10"
],
"description": "Divisional charts (vargas) to include: any of the sixteen ṣoḍaśavarga. Default d9 (navāṁśa) and d10 (daśāṁśa); send [] for none. Each returns its ascendant and every graha's sign, degree and house within the varga, by the Parāśari formulas."
},
"includeDasha": {
"type": "boolean",
"default": true,
"description": "Include the Vimśottarī daśā periods in the chart response. Default true."
}
}
}{
"type": "object",
"required": [
"datetime",
"latitude",
"longitude"
],
"properties": {
"zodiac": {
"enum": [
"sidereal",
"tropical"
],
"type": "string",
"default": "sidereal",
"description": "sidereal (default) or tropical."
},
"ayanamsa": {
"enum": [
"lahiri",
"raman",
"krishnamurti",
"fagan_bradley"
],
"type": "string",
"default": "lahiri",
"description": "Sidereal only."
},
"datetime": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Geographic latitude in decimal degrees, north positive."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "East positive."
},
"houseSystem": {
"enum": [
"whole_sign",
"equal",
"placidus"
],
"type": "string",
"default": "whole_sign",
"description": "House system for the cusps: whole_sign (default), equal or placidus."
}
}
}{
"type": "object",
"required": [
"start",
"end",
"stepMinutes"
],
"properties": {
"end": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
},
"start": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with Z or an explicit offset, between 1800-01-02 and 2149-12-31 UTC. A time without a zone is refused (invalid_datetime)."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"Sun",
"Moon",
"Mercury",
"Venus",
"Mars",
"Jupiter",
"Saturn",
"Uranus",
"Neptune",
"Pluto",
"MeanNode",
"TrueNode"
],
"type": "string",
"description": "MeanNode and TrueNode are Rāhu (mean or true); Ketu is the node + 180°. Every AstroNest chart, reading and timing endpoint uses the mean node."
},
"description": "Default: all twelve."
},
"zodiac": {
"enum": [
"sidereal",
"tropical"
],
"type": "string",
"default": "sidereal",
"description": "sidereal (default) or tropical."
},
"ayanamsa": {
"enum": [
"lahiri",
"raman",
"krishnamurti",
"fagan_bradley"
],
"type": "string",
"default": "lahiri",
"description": "Sidereal only."
},
"stepMinutes": {
"type": "integer",
"maximum": 525600,
"minimum": 1,
"description": "Minutes between points (1 to 525,600). At most 1,000 points per call."
}
}
}{
"type": "object",
"required": [
"birthData"
],
"properties": {
"areas": {
"type": "array",
"items": {
"enum": [
"relationship",
"children",
"education",
"career",
"business",
"money",
"property",
"family",
"travel",
"spirituality",
"health"
],
"type": "string"
},
"description": "Optional: only these life areas (default all eleven). The full reading is large, so an AI agent answering about one area should pass it here."
},
"recorded": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"date"
],
"properties": {
"date": {
"type": "string",
"format": "date"
},
"type": {
"enum": [
"marriage",
"relationship_end",
"loss_or_separation",
"child_birth",
"child_loss",
"job_start",
"job_loss",
"business_start",
"education_start",
"education_end",
"property_event",
"relocation",
"legal_event",
"health_period",
"other"
],
"type": "string"
},
"certainty": {
"enum": [
"exact",
"approximate",
"year"
],
"type": "string",
"default": "approximate"
}
}
},
"maxItems": 100,
"description": "Optional dated life events to place on the timeline."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data. The time is required: every period depends on the rising sign."
}
}
}| Read the question as one deal (the deal praśna). |
| place* | object | Where the question is asked. Required: a praśna cast at the wrong longitude is a different chart. |
| domain | string | What the question is about: picks the house of the matter and scopes the book rules. With a deal and no domain, the deal's own. |
| askedAt | string | The instant the question was asked, ISO 8601 with Z or an offset. Default: now. Send this or askedAtLocal, not both. |
| question | string | The question in the user's words. Gates the lost-article dictum; it does not choose the domain. |
| birthData | object | Only with `deal`, and with a birth time: the querent's natal commitment calendar is set beside the praśna for the signing date. |
| askedAtLocal | string | The wall clock at the place when the question was asked, YYYY-MM-DDTHH:mm, read in place.timezone. |
| horaryNumber | integer | A KP horary number: adds the KP horary table. |
{
"type": "object",
"required": [
"place"
],
"properties": {
"deal": {
"type": "object",
"required": [
"label",
"kind"
],
"properties": {
"kind": {
"enum": [
"contract",
"pitch",
"partnership",
"sale",
"hire",
"loan",
"lease",
"investment"
],
"type": "string"
},
"label": {
"type": "string",
"maxLength": 120
},
"signingDate": {
"type": "string",
"description": "YYYY-MM-DD, when it is to be signed, if not now. The natal cross-check reads this date."
}
},
"description": "Read the question as one deal (the deal praśna)."
},
"place": {
"type": "object",
"required": [
"latitude",
"longitude",
"timezone"
],
"properties": {
"label": {
"type": "string"
},
"latitude": {
"type": "number"
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. Asia/Kolkata"
},
"longitude": {
"type": "number"
}
},
"description": "Where the question is asked. Required: a praśna cast at the wrong longitude is a different chart."
},
"domain": {
"enum": [
"health",
"money",
"family",
"business",
"property",
"children",
"education",
"legal",
"partnerships",
"relationship",
"marriage",
"lineage",
"spirituality",
"career",
"reputation",
"travel"
],
"type": "string",
"description": "What the question is about: picks the house of the matter and scopes the book rules. With a deal and no domain, the deal's own."
},
"askedAt": {
"type": "string",
"description": "The instant the question was asked, ISO 8601 with Z or an offset. Default: now. Send this or askedAtLocal, not both."
},
"question": {
"type": "string",
"maxLength": 500,
"description": "The question in the user's words. Gates the lost-article dictum; it does not choose the domain."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "Only with `deal`, and with a birth time: the querent's natal commitment calendar is set beside the praśna for the signing date."
},
"askedAtLocal": {
"type": "string",
"description": "The wall clock at the place when the question was asked, YYYY-MM-DDTHH:mm, read in place.timezone."
},
"horaryNumber": {
"type": "integer",
"maximum": 249,
"minimum": 1,
"description": "A KP horary number: adds the KP horary table."
}
}
}| object |
| Where the person lives; the Varṣaphal is cast for this place. Defaults to the birthplace. |
| referenceDate | string | ISO date or datetime for the running periods and the Varṣaphal year. Defaults to now. |
{
"type": "object",
"required": [
"birthData"
],
"properties": {
"sections": {
"type": "array",
"items": {
"enum": [
"shadbala",
"ashtakavarga",
"dashas",
"vimshottari",
"karakamsa",
"argala",
"yogas",
"nabhasa",
"specialLagnas",
"bhavaChalit",
"panchanga",
"kp",
"houseLords",
"kuja",
"ayanamsha",
"varshaphal"
],
"type": "string"
},
"description": "Return only these sections. Default: all."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
},
"residence": {
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"label": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
},
"description": "Where the person lives; the Varṣaphal is cast for this place. Defaults to the birthplace."
},
"referenceDate": {
"type": "string",
"description": "ISO date or datetime for the running periods and the Varṣaphal year. Defaults to now."
}
}
}| The person's birth data. The time is required: every period depends on the rising sign. |
{
"type": "object",
"required": [
"birthData"
],
"properties": {
"months": {
"type": "integer",
"default": 36,
"maximum": 72,
"minimum": 6,
"description": "How far ahead the calendar runs, and the horizon each venture's period support is averaged over."
},
"ventures": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200,
"minLength": 3
},
"maxItems": 10,
"minItems": 1,
"description": "Optional: the businesses being weighed, each described by what it does (\"software for accountants\", \"a café with a leased storefront\"). A brand name alone cannot be placed and is returned as unclassified. Omit to rank the whole catalogue."
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data. The time is required: every period depends on the rising sign."
}
}
}| targetDate | string | Optional date the decision is about, YYYY-MM-DD. The verdict is read at this day. Takes precedence over `dateRange`. |
{
"type": "object",
"required": [
"birthData",
"domain",
"question"
],
"properties": {
"domain": {
"enum": [
"career",
"business",
"finance",
"children",
"property",
"education",
"travel",
"spirituality",
"lineage",
"reputation",
"partnerships",
"legal",
"family",
"marriage",
"health"
],
"type": "string",
"description": "Life area the decision is about, e.g. career, marriage, finance or health."
},
"question": {
"type": "string",
"minLength": 1,
"description": "The decision question in plain language, e.g. \"Is this a good time to change jobs?\""
},
"birthData": {
"type": "object",
"required": [
"date",
"timezone",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "YYYY-MM-DD"
},
"time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}(:\\d{2})?$",
"description": "24-hour HH:MM or HH:MM:SS, local to `timezone`. Omit if unknown: house-dependent detail is then reduced."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"timezone": {
"type": "string",
"description": "IANA timezone of the birthplace, e.g. Asia/Kolkata."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "The person's birth data: date, local time (omit if unknown), IANA timezone, latitude and longitude."
},
"dateRange": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"end": {
"type": "string",
"format": "date"
},
"start": {
"type": "string",
"format": "date"
}
},
"description": "Optional period the decision is about: start and end dates, YYYY-MM-DD. The verdict is read at `start`; `end` must not precede it."
},
"targetDate": {
"type": "string",
"format": "date",
"description": "Optional date the decision is about, YYYY-MM-DD. The verdict is read at this day. Takes precedence over `dateRange`."
}
}
}