POST /v1/rectification/ai-suggest
Runs the same engine as /event-score internally, pre-filtered to the top 3 candidates with a plain-text rank/confidence summary in each language. Note: this does NOT call the Astro Shivanii AI module — no LLM/AI logic is involved, it's the identical dasha+transit scoring math as /event-score (see that endpoint's docstring), just reformatted to the 3 best candidates. Use /event-score directly if you want the full candidate list and per-event dasha/transit score breakdown.
curl -X POST https://api.grahaapi.com/v1/rectification/ai-suggest -H "Authorization: Bearer sk-test-your-key" -H "Content-Type: application/json" -d '{"approx_tob":"22:00","day_unknown":false,"dob":"1990-06-15","events":[{"date":"2015-11-23","note":"","type":"marriage"},{"date":"2010-07-01","note":"First tech job","type":"job_start"}],"lat":28.6139,"lon":77.209,"step_minutes":4,"time_range_minutes":60,"tz":5.5}'Test keys (sk-test-…) are free and unlimited, and return the exact production response structure computed from a fixed sample chart. The response is JSON: {"success": true, "data": {…}, "meta": {…}} with Hindi + English strings, computed on the Lahiri ayanamsa.
| Field | Type | Required | Description |
|---|---|---|---|
dob | string | ✅ | Date of birth. YYYY-MM-DD if day is known; YYYY-MM (day omitted) when day_unknown=True. |
day_unknown | boolean | — | True if only year+month of birth are known, not the exact day. When True, dob must be YYYY-MM and every day of that month is scanned in addition to every candidate time — at least 5 events are required (vs. 1 normally) for a confident result. |
approx_tob | string | ✅ | A GUESS at birth time HH:MM, not a confirmed value — this is what the endpoint solves for. Centre of the search window; a wider uncertainty just means a larger time_range_minutes, not a blocker. |
time_range_minutes | integer | — | Search window ± minutes around approx_tob — how uncertain the guess is. Wider window = more candidate times tested (slower), not less accurate. |
step_minutes | integer | — | Step size in minutes between tested candidates (2–10 recommended; floored at 8 automatically when day_unknown=True, to keep a full-month scan bounded) |
lat | number | ✅ | Latitude |
lon | number | ✅ | Longitude |
tz | number | — | UTC offset (IST = 5.5) |
events | RectEvent[] | ✅ | Life events the person is CERTAIN about (exact dates — they already happened). 2+ recommended for a confident ranking (5+ REQUIRED when day_unknown=True); each needs a fixed `type` from the closed EventType vocabulary, not free text. |
use_transit | boolean | — | Also score each event against transiting Jupiter/Saturn/Rahu/Ketu/Mars on that event's date (Gochar), gated onto the dasha score rather than averaged with it — dasha sets multi-year eligibility, transit is the trigger within it. Set False to fall back to pure dasha-only scoring (the previous behaviour) for comparison. |
use_kp | boolean | — | Also gate the score by the real KP (Krishnamurti Paddhati) significator method — reuses this API's own /v1/kp house-significator logic (occupant's star lord / occupant / house-lord's star lord / house lord, computed under self-consistent KP-ayanamsa planets and Placidus cusps), checking whether the active dasha lord on the event date is a genuine significator of that event's relevant houses. Defaults OFF: tested against a real known-birth-time case and found genuinely NEUTRAL — small, mixed changes in both directions (raw rank very slightly worse, smoothing-stability very slightly better, confidence up on every candidate roughly equally), not a clear win or loss either way, plus real added computation cost (a full extra KP-ayanamsa planet+house pass per candidate). Kept off by default given no demonstrated benefit; set True to enable if you want this extra corroborating signal anyway. |
use_primary_directions | boolean | — | Also gate the score by classical Western Primary Directions — a genuinely different technique from dasha/transit/KP (all Vedic period/house-based methods): as the celestial sphere rotates, the Ascendant symbolically 'directs' to each natal planet's Oblique Ascension; the resulting arc, converted to age via the Naibod key (1 degree = 1 year), is compared to the customer's real age at each event. Computed in TROPICAL coordinates (Right Ascension is inherently tied to the true equinox, not the sidereal zodiac); every formula independently cross-checked against a real chart before use (RAMC via two methods, Oblique Ascension against the classical identity OA(Ascendant)=RAMC+90, both matching to full float precision). Defaults OFF: tested against a real known-birth-time case and found essentially NO discriminating effect at the current 1-year orb — rank shifted by at most 1 place out of 361 candidates, smoothing-stability barely moved, and the algorithm's top pick never changed, in both a 5-event and 8-event version of the case. Confidence numbers shift down uniformly (most candidate/significator pairings miss the 1-year orb) without changing relative ranking. Kept off by default given no demonstrated benefit; set True to enable if you want this extra corroborating signal, or if you want to experiment with a different orb. |
predispositions | object | — | Optional. Self-reported answers to static, date-independent life-pattern questions (e.g. 'were you married early') — a third signal alongside dated events, checked against each candidate chart's overall structure rather than a specific date. Keys are one of the fixed PredispositionType categories; values are 'yes_strong' (uniquely characteristic), 'yes' (typical, not definitive), 'unsure' (skip — no info, not a penalty), 'no' (not typical but possible), or 'no_strong' (definitely not typical). The customer answers plain questions about their own life — never astrology terms, never their own Ascendant; this endpoint does the chart-matching automatically per candidate. Leave empty (default) to fall back to pure event-based scoring (previous behaviour) — this signal only activates when at least one non-'unsure' answer is supplied. |
{
"approx_tob": "22:00",
"day_unknown": false,
"dob": "1990-06-15",
"events": [
{
"date": "2015-11-23",
"note": "",
"type": "marriage"
},
{
"date": "2010-07-01",
"note": "First tech job",
"type": "job_start"
}
],
"lat": 28.6139,
"lon": 77.209,
"step_minutes": 4,
"time_range_minutes": 60,
"tz": 5.5
}Get a free API key Try it in the playground
/v1/rectification/ascendant-options · /v1/rectification/event-score · /v1/rectification/kp-ruling-planets