{"openapi":"3.1.0","info":{"title":"Insights by Omkar — Kriya","version":"9.29.5","description":"Kriya — astrology API by Insights by Omkar. Covers Western modern, Vedic classical + Tajika + Jaimini, Hellenistic, KP, Horary, Uranian, ACG, parans, Gauquelin. Ephemeris from first principles — VSOP87D Mercury–Neptune, ELP/MPP02 lunar theory (sub-arcsec apparent), home-grown DOPRI8 8(7) n-body integrator for Pluto + 11 Centaurs/TNOs/asteroids, Meeus algorithms throughout. No third-party astronomy libraries. Rate-limit headers (X-RateLimit-*) and Retry-After on 429 follow Stripe conventions. Expensive POSTs accept an Idempotency-Key header; replays within 24h return the cached response. List endpoints support { limit, offset } pagination with a `pagination` block in the response.","contact":{"email":"admin@insightsbyomkar.com"}},"servers":[{"url":"/api/v1"}],"components":{"headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"},"description":"Max requests allowed per minute for the current key."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"},"description":"Max requests allowed per day for the current key."},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"},"description":"Requests remaining in the current minute window."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"},"description":"Requests remaining in the current day window."},"X-RateLimit-Reset-Minute":{"schema":{"type":"integer"},"description":"Unix seconds when the minute window resets."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer"},"description":"Unix seconds when the day window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the client may retry (on 429/503)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Correlation id for this request; echoed back in logs."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional per-request idempotency key (8-128 chars of [A-Za-z0-9_-]). Replays with the same key and body within 24h return the cached response.","schema":{"type":"string"}}},"schemas":{"ZodiacPoint":{"type":"object","properties":{"longitudeDeg":{"type":"number","description":"Ecliptic longitude, 0–360°"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degreeInSign":{"type":"number"}},"required":["longitudeDeg","sign","degreeInSign"]},"Body":{"allOf":[{"$ref":"#/components/schemas/ZodiacPoint"},{"type":"object","properties":{"key":{"type":"string","description":"Body identifier — sun, moon, mercury, …, eris, true-node, mean-bml, etc."},"latitudeDeg":{"type":"number","description":"Geocentric ecliptic latitude, degrees."},"distanceAU":{"type":"number","description":"Geocentric distance from Earth, AU."},"retrograde":{"type":"boolean","description":"True if the body is retrograde at the moment. Nodes are flagged retrograde by long-standing astrological convention; speedDeg reports the real instantaneous rate."},"speedDeg":{"type":"number","description":"Geocentric ecliptic longitude rate, signed deg/day. Negative = retrograde. Central finite difference at h=0.1d."},"rightAscensionDeg":{"type":"number","description":"Equatorial right ascension, degrees [0, 360). Computed via ecliptic→equatorial rotation using the true obliquity of date."},"declinationDeg":{"type":"number","description":"Equatorial declination, signed degrees. |declinationDeg| > obliquity (~23.4°) flags out-of-bounds (Moon only)."},"helioLongitudeDeg":{"type":"number","nullable":true,"description":"Heliocentric ecliptic longitude (J2000-ecliptic-of-date frame). Sun is the origin (0°). Undefined for ecliptic POINTS (mean-node / true-node / mean-bml)."},"helioLatitudeDeg":{"type":"number","nullable":true,"description":"Heliocentric ecliptic latitude. Sun returns 0. Undefined for ecliptic points."},"helioDistanceAU":{"type":"number","nullable":true,"description":"Heliocentric distance from the Sun, AU. Sun returns 0. Undefined for ecliptic points."},"phaseAngleDeg":{"type":"number","nullable":true,"description":"Sun-body-Earth phase angle, [0, 180°]. Sun returns 0. Undefined for ecliptic points."},"illuminatedFraction":{"type":"number","nullable":true,"description":"Lambert-phase-function illuminated fraction [0, 1]. (1 + cos α) / 2. Sun returns 1. Undefined for ecliptic points."},"house":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"House the body falls in (only present on chart routes that compute houses)."}},"required":["key","latitudeDeg","distanceAU","retrograde","speedDeg","rightAscensionDeg","declinationDeg"]}]},"Person":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"}},"required":["datetime","latitude","longitude"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items before paging."},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"},"nextOffset":{"type":"integer","nullable":true}},"required":["total","limit","offset","hasMore","nextOffset"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}}},"security":[{"ApiKey":[]}],"tags":[{"name":"Chart","description":"Natal chart computation and rendering"},{"name":"Relational","description":"Transits, synastry, composite, progressions, returns"},{"name":"Vedic","description":"Sidereal, nakshatras, vargas, dashas, panchanga, yogas"},{"name":"Hellenistic","description":"Profections, zodiacal releasing, dignities"},{"name":"Electional","description":"Planetary hours, VOC Moon, muhurta, sunrise/sunset"},{"name":"Points","description":"Asteroids, fixed stars, planetary nodes, special points"},{"name":"KP","description":"Krishnamurti Paddhati sub-lords and significators"},{"name":"Jaimini","description":"Arudha padas, rashi drishti, chara dasha"},{"name":"Reading","description":"Structured natal/transit readings, daily report, compatibility"},{"name":"Utility","description":"Geocoding, degree analysis, harmonic charts"},{"name":"Critic","description":"Critic-in-Loop — evaluate generated output against authoritative references. Separate SemVer track; beta stability."},{"name":"Account","description":"Customer self-serve — usage, keys, rotation. Bearer-auth, per-calling-key."},{"name":"Webhooks","description":"Subscribe to engine-generated events (dasha transitions, returns, transits, eclipses). Bearer-auth, per-user."},{"name":"Jobs","description":"Async jobs for long-running compute (rectification, research, batch). Poll or receive via callback."}],"paths":{"/chart/natal":{"post":{"tags":["Chart"],"summary":"Full natal chart (bodies, houses, aspects). Optional `fixedStars` block adds the bright stars conjunct any body in a single round-trip.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false},"fixedStars":{"description":"Include a top-level fixedStars[] block of bright stars conjunct any chart body or angle within orb. `true` uses defaults (orb 1°, magnitude ≤ 3). An object can override orbDeg (0, 5] and/or magLimit [-2, 6] (lower = brighter), and opt into Brady parans (`parans: true`) which adds a top-level parans[] block of star/body horizon-angle coincidences at the native's latitude. `paransLatitudeBandDeg` widens the band (default ±0.5°).","oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"orbDeg":{"type":"number","exclusiveMinimum":0,"maximum":5,"default":1},"magLimit":{"type":"number","minimum":-2,"maximum":6,"default":3},"parans":{"type":"boolean","default":false},"paransLatitudeBandDeg":{"type":"number","exclusiveMinimum":0,"maximum":5,"default":1}}}]}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Engine identification + computedAt + the inputs echoed back."},"bodies":{"type":"array","items":{"$ref":"#/components/schemas/Body"}},"houses":{"type":"object"},"aspects":{"type":"array","items":{"type":"object"}},"parallels":{"type":"array","items":{"type":"object"}},"patterns":{"type":"array","items":{"type":"object"}},"shape":{"type":"object"}},"required":["bodies","houses","aspects"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/positions":{"post":{"tags":["Chart"],"summary":"Geocentric ecliptic positions for one or more bodies.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"bodies":{"type":"array","items":{"type":"string"},"description":"Body keys (sun, moon, mercury, …). Omit for all."}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"bodies":{"type":"array","items":{"$ref":"#/components/schemas/Body"}}},"required":["bodies"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/houses":{"post":{"tags":["Chart"],"summary":"House cusps + angles for a moment and location.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"system":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/aspects":{"post":{"tags":["Chart"],"summary":"Detect aspects between arbitrary ecliptic longitudes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"points":{"type":"array","minItems":2,"items":{"type":"object","properties":{"key":{"type":"string"},"longitude":{"type":"number"}},"required":["key","longitude"]}}},"required":["points"]},"example":{"points":[{"key":"sun","longitude":84.52},{"key":"moon","longitude":305.17},{"key":"mars","longitude":12.03}]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chart/extended":{"post":{"tags":["Chart"],"summary":"Extended natal chart with nodes, Lilith, Arabic Lots, Vertex, midpoints.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Engine identification + computedAt + the inputs echoed back."},"bodies":{"type":"array","items":{"$ref":"#/components/schemas/Body"}},"houses":{"type":"object"},"aspects":{"type":"array","items":{"type":"object"}},"parallels":{"type":"array","items":{"type":"object"}},"patterns":{"type":"array","items":{"type":"object"}},"shape":{"type":"object"}},"required":["bodies","houses","aspects"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chart/mean-node":{"post":{"tags":["Chart"],"summary":"Mean lunar node position.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/true-node":{"post":{"tags":["Chart"],"summary":"True lunar node position (osculating).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chart/wheel":{"post":{"tags":["Chart"],"summary":"SVG or JSON rendering of a Western round wheel.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"},"size":{"type":"integer","default":600},"theme":{"type":"string","enum":["light","dark","premium"]},"format":{"type":"string","enum":["svg","json"],"default":"svg"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chart/vedic-wheel":{"post":{"tags":["Chart"],"summary":"SVG or JSON rendering of a North/South Indian kundli.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"style":{"type":"string","enum":["north","south"],"default":"north"},"size":{"type":"integer","default":600},"format":{"type":"string","enum":["svg","json"],"default":"svg"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dignities":{"post":{"tags":["Chart"],"summary":"Essential dignities + Lilly scores for all traditional planets.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/degrees/analyze":{"post":{"tags":["Chart"],"summary":"Degree-theory analysis: critical degrees, Via Combusta, Gandanta, exaltation/fall degrees.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"bodies":{"type":"array","items":{"type":"string"}}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/harmonic":{"post":{"tags":["Chart"],"summary":"Harmonic chart (Nth harmonic — multiply longitudes by N, mod 360).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"harmonic":{"type":"integer","minimum":1,"description":"Harmonic number (e.g., 5, 7, 9)"}},"required":["datetime","harmonic"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/transits":{"post":{"tags":["Relational"],"summary":"Current or future transit aspects to a natal chart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"transitDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["natal","transitDatetime"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"transitDatetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/synastry":{"post":{"tags":["Relational"],"summary":"Synastry aspects between two people's natal charts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["personA","personB"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/composite":{"post":{"tags":["Relational"],"summary":"Composite chart (midpoint method) for two people.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["personA","personB"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/composite/davison":{"post":{"tags":["Relational"],"summary":"Davison relationship chart (midpoint in time and space).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"}},"required":["personA","personB"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/progressions":{"post":{"tags":["Relational"],"summary":"Secondary progressions (day-for-a-year) for a natal chart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"targetDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"method":{"type":"string","enum":["secondary","solar-arc","minor","converse"],"default":"secondary"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["natal","targetDatetime"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"targetDatetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/progressions/tertiary":{"post":{"tags":["Relational"],"summary":"Tertiary progressions (day-for-a-month).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"targetDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["natal","targetDatetime"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"targetDatetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/directions/primary":{"post":{"tags":["Relational"],"summary":"Primary directions — classical Placidian semi-arc method (default) with the legacy Naibod-ecliptic approximation available via `method`. Returns mundane conjunctions + zodiacal Ptolemaic aspects (60/90/120/180), direct + converse, with arc-of-direction in degrees of right ascension and age via the chosen time key (Naibod / Ptolemy / Placidus). Significators include ASC, MC, DSC, IC, and every natal body; promissors are bodies.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"]},"method":{"type":"string","enum":["placidus-semi-arc","naibod-ecliptic"],"description":"Default: placidus-semi-arc."},"key":{"type":"string","enum":["naibod","ptolemy","placidus"],"description":"Time key. Default: naibod."},"maxYears":{"type":"number","minimum":1,"maximum":120,"description":"Default 90."},"includeMundane":{"type":"boolean","description":"Default true."},"includeZodiacal":{"type":"boolean","description":"Default true."},"includeConverse":{"type":"boolean","description":"Default true."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns":{"post":{"tags":["Relational"],"summary":"Unified-returns composite (v9.29.0). For each requested body, returns the NEXT return chart after `queryDatetime` (default 'now'). Saves a roundtrip per body vs the per-body `/returns/{solar,lunar,{body}}` endpoints (those still exist for explicit nth-return control).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"queryDatetime":{"type":"string","description":"ISO datetime or 'now' (default). All returns are computed forward from this moment."},"bodies":{"type":"array","items":{"type":"string"},"description":"Subset of: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune. Default = the traditional 7."},"location":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"description":"Override location for all return charts (default natal)."},"chartBodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["natal"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"queryDatetime":"2026-01-01T00:00:00Z","bodies":["sun","saturn"]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns/solar":{"post":{"tags":["Relational"],"summary":"Solar return chart — exact moment Sun returns to natal longitude.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"year":{"type":"integer","description":"Return year (e.g., 2026)"},"location":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"description":"Override location for the return chart"},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["natal","year"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"year":2026}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns/lunar":{"post":{"tags":["Relational"],"summary":"Lunar return chart — exact moment Moon returns to natal longitude.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"month":{"type":"integer","description":"Month offset from birth (1 = first return)"},"location":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}}},"bodies":{"type":"array","items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","mean-node","true-node","eris","mean-bml"]},"minItems":1,"description":"Restrict the returned chart (and the aspect search) to these bodies. Omit for the default set (the 10 classical bodies). The extended set (chiron, mean-node, true-node, eris, mean-bml) is accepted but only included when explicitly named — backward-compatible default. Duplicates are deduplicated."},"aspectOrbs":{"type":"object","description":"Per-aspect-kind orb override in degrees. Defaults: conjunction 8, opposition 8, trine 7, square 7, sextile 5. Each override must satisfy 0 ≤ orb ≤ 15. Missing kinds keep their default.","properties":{"conjunction":{"type":"number","minimum":0,"maximum":15},"opposition":{"type":"number","minimum":0,"maximum":15},"trine":{"type":"number","minimum":0,"maximum":15},"square":{"type":"number","minimum":0,"maximum":15},"sextile":{"type":"number","minimum":0,"maximum":15}},"additionalProperties":false}},"required":["natal","month"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"month":1}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/relocation":{"post":{"tags":["Relational"],"summary":"Relocated chart — same birth moment, different location.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"relocationLatitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"relocationLongitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"}},"required":["datetime","latitude","longitude","relocationLatitude","relocationLongitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/compatibility":{"post":{"tags":["Reading"],"summary":"Compatibility report — synastry + composite + scored summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"}},"required":["personA","personB"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/chart":{"post":{"tags":["Vedic"],"summary":"Full Vedic natal chart with sidereal positions, nakshatras, and vargas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/panchanga":{"post":{"tags":["Vedic"],"summary":"Panchanga (five limbs): tithi, karana, yoga, nakshatra, vara.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/sade-sati":{"post":{"tags":["Vedic"],"summary":"Sade Sati (Saturn's 7.5-year transit over natal Moon).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dashas":{"post":{"tags":["Vedic"],"summary":"Vimshottari, Yogini, or Ashtottari dasha periods.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"system":{"type":"string","enum":["vimshottari","yogini","ashtottari"],"default":"vimshottari"},"depth":{"type":"integer","minimum":1,"maximum":5,"default":3}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/yogas":{"post":{"tags":["Vedic"],"summary":"Detect classical yogas (Gaja Kesari, Pancha Mahapurusha, etc.).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ashtakavarga":{"post":{"tags":["Vedic"],"summary":"Parashara prastara + sarvashtakavarga bindus.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/shadbala":{"post":{"tags":["Vedic"],"summary":"Six-fold planetary strength analysis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chara-karakas":{"post":{"tags":["Vedic"],"summary":"Jaimini chara (movable) karakas — Atmakaraka through Gnatikaraka.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/muhurta":{"post":{"tags":["Vedic","Electional"],"summary":"Muhurta scoring — 5-component auspiciousness for a chosen moment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jaimini/arudhas":{"post":{"tags":["Jaimini"],"summary":"Arudha padas A1–A12 including Upapada (marriage indicator).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jaimini/aspects":{"post":{"tags":["Jaimini"],"summary":"Rashi Drishti — Jaimini sign-based aspects.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jaimini/chara-dasha":{"post":{"tags":["Jaimini"],"summary":"Chara Dasha — Jaimini sign-based life-period system.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kp-sublords":{"post":{"tags":["KP"],"summary":"KP sub-lord table — each cusp's sign lord, star lord, and sub lord.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kp/significators":{"post":{"tags":["KP"],"summary":"4-rank significator chain per house.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kp/ruling-planets":{"post":{"tags":["KP"],"summary":"7-source ruling planets for horary analysis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kp/cuspal-interlinks":{"post":{"tags":["KP"],"summary":"Cuspal interlinks — promises / neutral / denies judgement per cusp.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/profections":{"post":{"tags":["Hellenistic"],"summary":"Annual and monthly profections with time-lord.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"targetDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime","latitude","longitude","targetDatetime"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/zodiacal-releasing":{"post":{"tags":["Hellenistic"],"summary":"Zodiacal Releasing — L1→L4 fractal periods from any Lot.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"lot":{"type":"string","default":"fortune","description":"Arabic lot to release from"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/planetary-hours":{"post":{"tags":["Electional"],"summary":"Chaldean 24-hour planetary day — which planet rules each hour.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/voc-moon":{"post":{"tags":["Electional"],"summary":"Void-of-course Moon — period when the Moon makes no major aspect before sign change.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sun-rise-set":{"post":{"tags":["Electional"],"summary":"Sunrise, sunset, and solar transit for a location.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/eclipses":{"post":{"tags":["Electional"],"summary":"Solar + lunar eclipses in a date range.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/eclipses/prenatal":{"post":{"tags":["Electional"],"summary":"Prenatal eclipses — the solar + lunar eclipses immediately before birth.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/events":{"post":{"tags":["Electional"],"summary":"Events stream — dasha transitions, returns, eclipses, stations in a range.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["natal","startDatetime","endDatetime"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"startDatetime":"1990-06-15T12:00:00Z","endDatetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/asteroids":{"post":{"tags":["Points"],"summary":"Geocentric ecliptic positions for Ceres, Pallas, Juno, Vesta, Chiron, Pholus, Nessus, Eris, Haumea, Makemake, Sedna, Quaoar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"keys":{"type":"array","items":{"type":"string","enum":["ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]}}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"asteroids":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Body"},{"type":"object","properties":{"category":{"type":"string","enum":["asteroid"]}}}]}}},"required":["asteroids"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/fixed-stars":{"post":{"tags":["Points"],"summary":"Fixed star positions at a given epoch, with precession drift.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"stars":{"type":"array","items":{"type":"string"},"description":"Star names (omit for all 158)."}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stars/list":{"post":{"tags":["Points"],"summary":"Enumerate the fixed-star catalog (159 stars) with J2000 positions and interpretations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/returns/{body}":{"post":{"tags":["Returns"],"summary":"Planetary return chart for one of: mercury, venus, mars, jupiter, saturn, uranus, neptune. The Sun + Moon returns live at /returns/solar and /returns/lunar respectively. `nthReturn` selects which return to compute (0 = first after birth). Saturn return-1 fires at age ~29.5; Jupiter at ~12; Mars at ~2 years; Mercury / Venus several times per year because of synodic cadence + retrograde.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"type":"object","description":"Natal datetime + location."},"nthReturn":{"type":"integer","minimum":0,"maximum":200,"description":"0 = first return after birth."},"location":{"type":"object","description":"Optional return-chart location."},"bodies":{"type":"array","items":{"type":"string"},"description":"Optional body filter."},"aspectOrbs":{"type":"object","description":"Optional per-aspect orb overrides."}},"required":["natal","nthReturn"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"nthReturn":0}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/nation/{key}":{"post":{"tags":["Mundane"],"summary":"Saved national chart store. `key` is one of: us / uk / india / china / russia / germany / france / japan / israel / pakistan / brazil / mexico / canada / australia / south-africa / european-union. Returns datetime + lat + lon + source citation + alternate-chart notes. Pass through to /v1/chart/natal for the full mundane chart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/aries-ingress":{"post":{"tags":["Mundane"],"summary":"Aries ingress chart for any year + location. The Sun's entry into 0° Aries casts the 'year chart' read mundanely per Ptolemy / Abu Ma'shar / Lilly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1800,"maximum":2200},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"bodies":{"type":"array","items":{"type":"string"}},"aspectOrbs":{"type":"object"}},"required":["year","latitude","longitude"]},"example":{"year":2026,"latitude":38.8951,"longitude":-77.0364}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/cancer-ingress":{"post":{"tags":["Mundane"],"summary":"Cancer ingress chart for any year + location. The Sun's entry into 0° Cancer (~June 21) casts the summer-quarter chart read mundanely per Ptolemy / Abu Ma'shar / Lilly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1800,"maximum":2200},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"bodies":{"type":"array","items":{"type":"string"}},"aspectOrbs":{"type":"object"}},"required":["year","latitude","longitude"]},"example":{"year":2026,"latitude":38.8951,"longitude":-77.0364}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/libra-ingress":{"post":{"tags":["Mundane"],"summary":"Libra ingress chart for any year + location. The Sun's entry into 0° Libra (~September 22) casts the autumn-quarter chart read mundanely per Ptolemy / Abu Ma'shar / Lilly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1800,"maximum":2200},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"bodies":{"type":"array","items":{"type":"string"}},"aspectOrbs":{"type":"object"}},"required":["year","latitude","longitude"]},"example":{"year":2026,"latitude":38.8951,"longitude":-77.0364}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/capricorn-ingress":{"post":{"tags":["Mundane"],"summary":"Capricorn ingress chart for any year + location. The Sun's entry into 0° Capricorn (~December 21) casts the winter-quarter chart read mundanely per Ptolemy / Abu Ma'shar / Lilly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1800,"maximum":2200},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"bodies":{"type":"array","items":{"type":"string"}},"aspectOrbs":{"type":"object"}},"required":["year","latitude","longitude"]},"example":{"year":2026,"latitude":38.8951,"longitude":-77.0364}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mundane/great-mutations":{"post":{"tags":["Mundane"],"summary":"Saturn-Jupiter conjunctions (the Great Mutations) across a date range. `isGreatMutation: true` flags conjunctions where the element changed from the prior — civilizational-pivot markers per medieval mundane practice. The December 21, 2020 conjunction in Aquarius marked the start of the current Air period.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startYear":{"type":"integer","minimum":1500,"maximum":2300},"endYear":{"type":"integer","minimum":1500,"maximum":2300}},"required":["startYear","endYear"]},"example":{"startYear":1900,"endYear":2100}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/time-lord-stack":{"post":{"tags":["Predictive"],"summary":"**The audit's single biggest unlock.** Composes every active time-lord layer at the query datetime into a unified response: profection (Hellenistic) + Vimshottari maha/antar/pratyantar (Vedic) + ZR Fortune L1+L2 (Hellenistic) + ZR Spirit L1+L2 (Hellenistic) + Firdaria L1+L2 (Persian). All five layers run simultaneously over a life; this endpoint collapses them into 'right now, what's active' — the unified view no other astrology API ships. Plus cross-lens correlations (e.g. 'ZR-Fortune and ZR-Spirit both in peak periods → major life chapter').","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"type":"object","description":"Natal datetime + location."},"queryDatetime":{"type":"string","format":"date-time","description":"Defaults to 'now' if omitted."},"ayanamsa":{"type":"string","description":"Default: lahiri."}},"required":["natal"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"queryDatetime":"2026-05-02T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/firdaria":{"post":{"tags":["Hellenistic"],"summary":"Firdaria — Persian time-lord cycle (Abu Ma'shar / Al-Kindi). 75-year lifecycle of major + sub-periods. Day-birth sequence: Sun 10y, Venus 8y, Mercury 13y, Moon 9y, Saturn 11y, Jupiter 12y, Mars 7y, North Node 3y, South Node 2y. Night-birth starts at Moon. Sub-periods within each L1 cycle the same 9 lords proportionally.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"type":"object","description":"Natal datetime + location."},"yearsAhead":{"type":"number","minimum":1,"maximum":150,"description":"Default 75."},"queryJdUT":{"type":"number","description":"Optional query JD for active-trail."}},"required":["natal"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"yearsAhead":75}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/bhrigu-bindu":{"post":{"tags":["Vedic"],"summary":"Bhrigu Bindu — the Moon-Rahu midpoint. A sensitive trigger point in modern Vedic practice (Bhrigu Maharishi school): when major-planet transits cross it, the native experiences destiny-marker events. Returns Bhrigu Bindu + Tripa Lagna (the Asc reflected through the BB).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"ayanamsa":{"type":"string","description":"Default: lahiri."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jaimini/argala":{"post":{"tags":["Jaimini"],"summary":"Jaimini Argala — intervention reading from any reference house. Per the Upadesha Sutras: from any reference house, planets in 2nd / 4th / 5th / 11th provide argala (positive intervention); the 12th / 10th / 9th / 3rd are virodha-argala (counter-intervention) that cancels argala. Output verdict: promised / denied / contested / neutral per house. Pass `referenceHouses: [7]` to focus only on marriage-house argala, e.g.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"ayanamsa":{"type":"string","description":"Default: lahiri."},"referenceHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"description":"Default: all 12 houses."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"referenceHouses":[7,10]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/midpoints/trees":{"post":{"tags":["Points"],"summary":"Ebertin midpoint trees (Mittelpunkts-Bilder). For each chart point, list every midpoint axis A/B that the point sits on within orb on the 90° dial. The classical Cosmobiology reading device. `personalOnly: true` returns only Sun/Moon/ASC/MC/Node trees — Ebertin's canonical biographical set. `dialOrbDeg` defaults to 1° (Ebertin standard).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"dialOrbDeg":{"type":"number","minimum":0.1,"maximum":5,"description":"Default 1°."},"personalOnly":{"type":"boolean","description":"Default false. true returns only Sun/Moon/ASC/MC/Node trees."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"dialOrbDeg":1,"personalOnly":true}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kp/horary":{"post":{"tags":["KP"],"summary":"KP horary — 1-to-249 number method. Querent picks an integer in [1, 249]; the number maps to the centre of its arc (360°/249 ≈ 1.4458° per arc) in the sidereal zodiac, which becomes the artificial horary ascendant. The KP nakshatra-lord / sub-lord / sub-sub-lord chain at that longitude is the 4-lord signature. Optional chart context (datetime + lat + long + ayanamsa) appends the cuspal interlinks for the question moment so the full horary judgement is one round-trip.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":249,"description":"Querent's number."},"datetime":{"type":"string","format":"date-time","description":"Optional question moment for cuspal-interlink judgement."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Optional question location latitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Optional question location longitude."},"ayanamsa":{"type":"string","description":"Optional ayanamsa (default lahiri)."}},"required":["number"]},"example":{"number":47,"datetime":"2026-05-02T14:30:00+05:30","latitude":12.97,"longitude":77.59}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/avastha":{"post":{"tags":["Vedic"],"summary":"Avastha — five planetary states (Bala / Kumara / Yuva / Vriddha / Mrita) based on degree-in-sign per Phaladeepika & BPHS. Even/odd sign parity reverses the sequence. Returns each natal planet's stage + a strength factor (0.0–1.0) usable as a downstream Shadbala-adjacent weight. Also flags vargottama (D1 sign = D9 sign — extra-strong placement).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"ayanamsa":{"type":"string","description":"Default: lahiri."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/upagrahas":{"post":{"tags":["Vedic"],"summary":"Upagrahas — visible Sun-derived sub-planets (Dhuma, Vyatipata, Parivesha, Indrachapa, Upaketu) plus optional invisibles (Gulika / Kala / Mrityu / ArthaPrahara / Yamakantaka). Pass `withInvisibles: true` to opt in — invisibles use the 8-part division of the day's diurnal arc per BPHS (sunrise → sunset for day-birth, sunset → next sunrise for night-birth). Polar latitudes reject the invisibles request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"ayanamsa":{"type":"string","description":"Default: lahiri."},"withInvisibles":{"type":"boolean","description":"Include the 5 invisible upagrahas. Default: false."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/zodiacal-releasing/{lot}":{"post":{"tags":["Hellenistic"],"summary":"Preset-Lot Zodiacal Releasing — wraps the generic /zodiacal-releasing engine with internal Lot resolution. Pass `lot` as one of: fortune, spirit, eros, necessity, courage, victory, nemesis, basis, exaltation. Body provides `natal` (datetime + lat + lon); the Lot's longitude is derived from the chart automatically. Returns the period tree with v9.17.0 flags (peak / loosing-of-bond / trine-anchor / square-anchor / sextile-anchor / opposition-anchor) computed against the requested anchor (default: fortune for body/health Lots, spirit for career/action Lots, self for Basis/Exaltation; override with `anchor`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"type":"object","description":"Natal datetime + location."},"depth":{"type":"integer","minimum":1,"maximum":4,"description":"Default 2."},"yearsAhead":{"type":"number","minimum":1,"maximum":422,"description":"Default 84."},"queryJdUT":{"type":"number","description":"Optional query JD for active-trail."},"anchor":{"type":"string","enum":["fortune","spirit","self"],"description":"Override the default anchor for the period flags."}},"required":["natal"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"depth":2,"yearsAhead":84}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/solar-arc/yearly":{"post":{"tags":["Predictive"],"summary":"Solar Arc yearly aspect scanner. Returns every directed-to-natal contact across the requested age range with applying / separating windows in years, plus a year-by-year bucket structure for consumer 'this year' cards and lifetime timelines. `method` defaults to 'naibod-via-sun' (the standard); other options: 'naibod' (0.9856473°/yr), 'ptolemy' (1°/yr), 'kepler' (natal Sun daily motion × 365.25), 'asc-arc' (approximation pending v9.21 primary-direction work). `converse: true` flips the arc sign for symbolic shadow-time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"type":"object","description":"Natal datetime + location."},"fromAgeYears":{"type":"number","minimum":0,"maximum":150},"toAgeYears":{"type":"number","minimum":0,"maximum":150},"method":{"type":"string","enum":["naibod-via-sun","naibod","ptolemy","kepler","asc-arc"],"description":"Default: naibod-via-sun."},"converse":{"type":"boolean","description":"Default: false. true flips arc sign."}},"required":["natal","fromAgeYears","toAgeYears"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"fromAgeYears":25,"toAgeYears":35,"method":"naibod-via-sun"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/galactic-points":{"post":{"tags":["Points"],"summary":"Galactic anchor points — Galactic Center, Super-Galactic Center, Great Attractor, the four Royal Stars (Aldebaran, Regulus, Antares, Fomalhaut), and three navigation references (Sirius, Vega, Polaris). Returns precessed ecliptic positions (sign, degreeInSign) at the chart epoch + optional conjunctions to caller-supplied chart bodies. Distinct from /fixed-stars in that it surfaces just the foundational anchors as positionable points, not as conjunction-targets across the full 159-star catalog.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"orbDeg":{"type":"number","minimum":0.1,"maximum":5,"description":"Conjunction orb for the optional `points` array. Default 1.5°."},"points":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"longitudeDeg":{"type":"number"}},"required":["key","longitudeDeg"]},"description":"Optional chart bodies to test for conjunction with each anchor. Pass the natal-chart bodies array directly."}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z","orbDeg":1.5,"points":[{"key":"sun","longitudeDeg":84.42},{"key":"moon","longitudeDeg":196.21}]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/planetary-nodes":{"post":{"tags":["Points"],"summary":"Mean heliocentric ascending nodes for all 8 planets.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bodies/extended":{"post":{"tags":["Points"],"summary":"Extended body catalog — TNO dwarfs (Eris, Sedna, Haumea, Makemake, Quaoar), centaurs (Pholus, Nessus), Lilith trio.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reading/natal":{"post":{"tags":["Reading"],"summary":"Structured natal reading — 6 topics with original interpretive content.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0"},"reading":{"topics":[{"topic":"self","paragraphs":["Gemini Sun in the 7th house makes your sense of self a mirror held up to others — you know yourself most clearly in conversation..."]},{"topic":"relationships","paragraphs":["..."]}]}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reading/transit":{"post":{"tags":["Reading"],"summary":"Structured transit reading for a given moment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natalDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"windowStart":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"windowEnd":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["natalDatetime","latitude","longitude","windowStart","windowEnd"]},"example":{"natalDatetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"windowStart":"2026-04-18T00:00:00Z","windowEnd":"2026-04-25T00:00:00Z"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0"},"transits":{"window":{"start":"2026-04-18T00:00:00Z","end":"2026-04-25T00:00:00Z"},"highlights":["Jupiter trine natal Sun exact 2026-04-22 — expansion available through collaboration."]}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/daily":{"post":{"tags":["Reading"],"summary":"Daily report — Moon phase, panchanga, muhurta, top transits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"date":{"type":"string","description":"YYYY-MM-DD"}},"required":["natal"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ask":{"post":{"tags":["Reading"],"summary":"Ask a question through the lens of the best-matched astrological method.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"question":{"type":"string"}},"required":["natal","question"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"question":"Which years in the next decade are strongest for a career move?"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/calibrate":{"post":{"tags":["Reading"],"summary":"Calibration — score astrological methods against real life events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"description":{"type":"string"}},"required":["date","description"]}}},"required":["natal","events"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"events":[{"date":"2010-05-12","description":"Started first job"},{"date":"2018-09-01","description":"Moved abroad"}]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/geocode":{"post":{"tags":["Utility"],"summary":"Location autocomplete with timezone inference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"City name or partial address"}},"required":["query"]},"example":{"query":"Mumbai"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/health":{"get":{"tags":["Utility"],"summary":"Liveness + self-check. Returns 200 when the ephemeris drift check passes, 503 when it fails. Unauthenticated — safe for uptime monitors and load balancers.","responses":{"200":{"description":"Healthy"},"503":{"description":"Degraded"}}}},"/accuracy":{"get":{"tags":["Utility"],"summary":"Live ephemeris-accuracy report. For each of ~20 reference dates spanning 1900–2050, recomputes the body's ecliptic longitude now and diffs against the published Meeus / Horizons value. Returns per-body summary + per-anchor deltas + the ephemeris-claims snapshot. Unauthenticated. Cached 15 min.","responses":{"200":{"description":"Accuracy report","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"8.11.1","computedAt":"2026-04-20T12:00:00.000Z","ephemeris":{"sun":"VSOP87D full …","moon":"Meeus ch. 47 truncated ELP2000 …","planets":"VSOP87D full Mercury–Neptune …"}},"summary":{"sun":{"worstDeltaArcsec":0.6,"anchors":4},"moon":{"worstDeltaArcsec":7.9,"anchors":1}},"diffs":[{"label":"J2000 Sun","body":"sun","jdTT":2451545,"computedLongitudeDeg":280.36815,"expectedLongitudeDeg":280.3681,"deltaArcsec":0.18,"toleranceDeg":0.002,"withinTolerance":true,"source":"Meeus ch. 26 pipeline @ v8.7.0"}]}}}}}}},"/usage/me":{"get":{"tags":["Account"],"summary":"Consumption for the calling API key. Bearer-authed. JWT keys only — static and open-mode return 403.","parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["today","month","lifetime"],"default":"month"},"description":"Rolling window for the totals field."}],"responses":{"200":{"description":"Usage snapshot","content":{"application/json":{"example":{"keyId":"key_abc12345","owner":"acme@example.com","window":"month","totals":{"requests":40000},"topRoutes":[{"route":"/api/v1/chart/natal","count":20000},{"route":"/api/v1/transits","count":15000}],"lastSeenAt":"2026-04-19T10:00:00.000Z"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires a JWT-minted API key"},"429":{"description":"Rate limit exceeded"}}}},"/keys/me":{"get":{"tags":["Account"],"summary":"Metadata for the calling key plus sibling keys owned by the same user.","parameters":[{"name":"includeRevoked","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Include revoked sibling keys in the `others` list."}],"responses":{"200":{"description":"Key metadata","content":{"application/json":{"example":{"self":{"keyId":"key_abc12345","owner":"acme@example.com","plan":"pro","quotaPerMin":300,"quotaPerDay":50000,"createdAt":"2026-04-18T10:00:00.000Z","expiresAt":"2027-04-18T10:00:00.000Z","revokedAt":null,"ownedBy":"usr_abc123"},"others":[]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires a JWT-minted API key"}}}},"/jobs":{"get":{"tags":["Jobs"],"summary":"List recent async jobs owned by the caller (newest first).","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Job list","content":{"application/json":{"example":{"jobs":[{"jobId":"job_AbCdEf123","kind":"echo","status":"completed","progress":100,"createdAt":"2026-04-19T12:00:00.000Z","startedAt":"2026-04-19T12:00:00.020Z","completedAt":"2026-04-19T12:00:00.050Z"}]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"}}},"post":{"tags":["Jobs"],"summary":"Create an async job. Returns 202 + jobId immediately; poll GET /jobs/{jobId} for status.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["echo","rectification","research"],"description":"Job kind. 'echo' is a framework smoke-test; 'rectification' (v8.9.0) takes { approxDatetime, latitude, longitude, events[{datetime, category, weight?}], windowMinutes?, stepMinutes?, houseSystem?, topK? } and returns a top-N birth-time candidate list; 'research' (v8.10.0) takes { within: { charts: [...] }, find: <filter>, return: { shape, sampleSize? } } and returns { total, matched, hits?, query } — filter primitives are aspect / sign / house with and / or / not composition."},"input":{"description":"Kind-specific payload."},"callbackUrl":{"type":"string","description":"Reserved for webhook-on-complete (v8.5.1+). http(s) only."}}},"example":{"kind":"echo","input":{"hello":"world"}}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"example":{"jobId":"job_AbCdEf123","status":"pending","kind":"echo","createdAt":"2026-04-19T12:00:00.000Z","pollUrl":"/api/v1/jobs/job_AbCdEf123"}}}},"400":{"description":"Unknown kind, invalid input, or bad callbackUrl"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"501":{"description":"Reserved kind not yet implemented"}}}},"/jobs/{jobId}":{"get":{"tags":["Jobs"],"summary":"Poll a job. Returns status + progress; the `result` field appears only once status=completed.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"example":{"job":{"jobId":"job_AbCdEf123","kind":"echo","status":"completed","progress":100,"createdAt":"2026-04-19T12:00:00.000Z","startedAt":"2026-04-19T12:00:00.020Z","completedAt":"2026-04-19T12:00:00.050Z","result":{"echoed":{"hello":"world"},"at":"2026-04-19T12:00:00.030Z"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"404":{"description":"Not found (or owned by someone else)"}}},"delete":{"tags":["Jobs"],"summary":"Cancel a pending job. 409 if the job has already started or finished.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"404":{"description":"Not found"},"409":{"description":"Job is not in 'pending' state"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List all webhook subscriptions owned by the caller. Bearer-authed. JWT keys with ownedBy required.","responses":{"200":{"description":"Subscription list","content":{"application/json":{"example":{"webhooks":[{"subId":"whk_AbCdEf123","ownedBy":"usr_abc123","url":"https://example.com/hooks/transits","secretPreview":"whsec_AB34…","events":["dasha.transition","transit.exact"],"createdAt":1713494000000,"disabledAt":null,"lastDeliveryAt":null,"lastDeliveryStatus":null,"consecutiveFailures":0}]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription. Plaintext secret returned ONCE — save it before closing the response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","description":"http(s) URL the engine POSTs to on event"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["dasha.transition","return.solar","return.lunar","transit.exact","eclipse.near"]}}}},"example":{"url":"https://example.com/hooks/transits","events":["dasha.transition","transit.exact"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"webhook":{"subId":"whk_AbCdEf123","ownedBy":"usr_abc123","url":"https://example.com/hooks/transits","secret":"whsec_ABcd1234…","secretPreview":"whsec_AB34…","events":["dasha.transition","transit.exact"],"createdAt":1713494000000,"disabledAt":null,"lastDeliveryAt":null,"lastDeliveryStatus":null,"consecutiveFailures":0},"note":"Save the `secret` now — it cannot be retrieved again."}}}},"400":{"description":"Bad request (invalid url / events)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"}}}},"/webhooks/{subId}":{"get":{"tags":["Webhooks"],"summary":"Fetch a single subscription (secret not returned).","parameters":[{"name":"subId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"404":{"description":"Not found (or owned by someone else)"}}},"patch":{"tags":["Webhooks"],"summary":"Update a subscription: url, events, or enabled/disabled state.","parameters":[{"name":"subId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["dasha.transition","return.solar","return.lunar","transit.exact","eclipse.near"]}},"disabled":{"type":"boolean","description":"true pauses delivery, false resumes"}}},"example":{"disabled":true}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Bad request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"404":{"description":"Not found"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a subscription.","parameters":[{"name":"subId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Requires JWT-minted key with ownedBy"},"404":{"description":"Not found"}}}},"/keys/rotate":{"post":{"tags":["Account"],"summary":"Rotate the calling key. Mints a new token with identical owner/plan/scopes and revokes the current one. The new token is shown exactly once.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttlDays":{"type":"integer","minimum":1,"maximum":3650,"description":"Lifetime of the new key in days. Defaults to the remaining TTL of the current key."}}},"example":{"ttlDays":365}}}},"responses":{"200":{"description":"Rotated","content":{"application/json":{"example":{"keyId":"key_newabcde","token":"eyJhbGciOi...","owner":"acme@example.com","plan":"pro","quotaPerMin":300,"quotaPerDay":50000,"expiresAt":"2027-04-19T12:00:00.000Z","rotatedFrom":"key_abc12345","rotatedAt":"2026-04-19T12:00:00.000Z"}}}},"400":{"description":"Invalid ttlDays"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key is already revoked, or static/open-mode caller"},"404":{"description":"Current key not in the registry"}}}},"/vedic/vargas":{"post":{"tags":["Vedic"],"summary":"All 16 divisional charts (Shodashavarga) — D1, D2, D3, D4, D7, D9, D10, D12, D16, D20, D24, D27, D30, D40, D45, D60 — with per-planet placements.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sensitive-points":{"post":{"tags":["Points"],"summary":"Vertex, Anti-Vertex, and East Point (Equatorial Ascendant).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/declinations":{"post":{"tags":["Chart"],"summary":"Declinations of all bodies plus parallel / contraparallel aspects.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"orbDeg":{"type":"number","minimum":0.1,"maximum":3,"default":1}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/heliocentric":{"post":{"tags":["Chart"],"summary":"Heliocentric ecliptic positions for Mercury through Pluto.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/draconic":{"post":{"tags":["Chart"],"summary":"Draconic zodiac — every longitude shifted so the Moon's North Node sits at 0° Aries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"node":{"type":"string","enum":["mean","true"],"default":"mean"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/bhava-chalit":{"post":{"tags":["Vedic"],"summary":"Bhava chalit chart — Vedic house placements using real cusps (Placidus/Porphyry) instead of whole-sign, with rashi-vs-bhava shift detection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"system":{"type":"string","enum":["placidus","porphyry"],"default":"placidus"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/antiscia":{"post":{"tags":["Chart"],"summary":"Solstitial mirror points (antiscia) and equinoctial mirror points (contra-antiscia), plus contacts between natal positions and antiscia within orb.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"orbDeg":{"type":"number","minimum":0.1,"maximum":5,"default":1}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/midpoints":{"post":{"tags":["Chart"],"summary":"Every 2-body midpoint plus 22.5°-dial activations (Ebertin cosmobiology).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"orbDeg":{"type":"number","minimum":0.1,"maximum":3,"default":1.5}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/lunar-mansions":{"post":{"tags":["Points"],"summary":"Arabic 28 Manzil lunar mansions — current Moon and Sun mansion, full catalog.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/lunation":{"post":{"tags":["Chart"],"summary":"Current lunar phase + elongation, nearest prior/next New Moon and Full Moon, and prior-New-Moon chart positions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/lots":{"post":{"tags":["Hellenistic"],"summary":"All Hellenistic Lots + Arabic Parts (Fortune, Spirit, Eros, Necessity, Courage, Victory, Nemesis, Marriage, Children, Father, Mother, Siblings, Fame, Commerce, Sickness, Captivity). Sect-aware.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jaimini/narayana-dasha":{"post":{"tags":["Jaimini"],"summary":"Narayana (Padakrama) Dasha — Jaimini sign-based dasha for major life events. Starting sign by ASC modality, direction by start-sign parity, period = count to lord minus 1 (or 12 if lord co-located).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"cyclesAhead":{"type":"integer","minimum":1,"maximum":3,"default":1},"now":{"type":"string","description":"ISO datetime to query active period; defaults to now."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/varshaphala":{"post":{"tags":["Vedic"],"summary":"Vedic annual return (Varshaphala / Tajika): sidereal solar return chart + Muntha + Year Lord (Varshesha) + Mudda dasha + Patyayini dasha + Tajika aspects & yogas + 30 Sahams.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"ageYears":{"type":"number","minimum":0,"maximum":150},"now":{"type":"string","description":"ISO datetime to query active dasha period; defaults to now."}},"required":["natal","ageYears"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"ageYears":35,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/horary":{"post":{"tags":["Chart"],"summary":"Horary astrology (William Lilly tradition) with Vedic Prashna companion. Returns question chart (Regiomontanus houses), considerations against judgment (Lilly's 7+ strictures), significators for querent + quesited, perfection analysis (applying aspect, translation/collection of light, prohibition), and a verdict. Prashna section returns Prashna Lagna, Moon nakshatra, and planetary hour ruler.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"quesitedHouse":{"type":"integer","minimum":1,"maximum":12},"topic":{"type":"string","description":"Alternative to quesitedHouse — keyword like 'marriage', 'career', 'money', 'hidden-enemy', 'lawsuit'."}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/uranian":{"post":{"tags":["Points"],"summary":"Uranian / Hamburg School — 8 hypothetical trans-Neptunian bodies (Cupido, Hades, Zeus, Kronos, Apollon, Admetos, Vulkanus, Poseidon) from Witte-Sieggruen orbital elements, plus all classical anchors mapped onto the 90° dial with midpoint-activation detection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"orbDeg":{"type":"number","minimum":0.1,"maximum":3,"default":1.5}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/astrocartography":{"post":{"tags":["Chart"],"summary":"Astro*Carto*Graphy (Jim Lewis). For each classical body, returns the geographic longitude where it is on the MC and IC, plus polyline samples of the ASC and DSC horizon curves — ready to render directly on a world map.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitudeStepDeg":{"type":"number","minimum":0.5,"maximum":5,"default":1},"latitudeRangeDeg":{"type":"number","minimum":10,"maximum":89,"default":85}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/parans":{"post":{"tags":["Points"],"summary":"Bernadette Brady fixed-star parans. Finds latitudes where a star and a planet are simultaneously on their respective angles (rise/MC/set/IC) within an LST tolerance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitudeStepDeg":{"type":"number","minimum":0.5,"maximum":5,"default":1},"lstToleranceDeg":{"type":"number","minimum":0.1,"maximum":5,"default":1},"magnitudeCutoff":{"type":"number","minimum":-2,"maximum":6,"default":2.5}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/gauquelin":{"post":{"tags":["Chart"],"summary":"Gauquelin 36 equal-time diurnal sectors with G1–G4 power-zone classification (cadent-after-angle slots Michel Gauquelin found statistically significant for professional eminence).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/graha-drishti":{"post":{"tags":["Vedic"],"summary":"Parashari Vedic planetary aspects (Graha Drishti). Every planet aspects the 7th house from itself; Mars also 4th/8th, Jupiter 5th/9th, Saturn 3rd/10th, Rahu/Ketu 5th/9th. Returns per-planet aspect list + planet-to-planet matrix.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/navatara":{"post":{"tags":["Vedic"],"summary":"Navatara — 9-star classification of nakshatras relative to the Janma (birth Moon) nakshatra. Returns the full 27-row table plus, if `now` is provided, the transit Moon's current classification.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"now":{"type":"string","description":"ISO datetime to classify transit Moon; optional."}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/heliacal":{"post":{"tags":["Chart"],"summary":"Heliacal rising/setting event scan. Returns every date in [startDatetime, endDatetime] where the Sun-body elongation crosses ±thresholdDeg for Moon, Mercury, Venus, Mars, Jupiter, Saturn. Default threshold 10° (classical arcus visionis).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"thresholdDeg":{"type":"number","minimum":3,"maximum":30,"default":10}},"required":["startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/transits/scan":{"post":{"tags":["Relational"],"summary":"Scan a date range for exact transits. Returns every moment when the selected transiting bodies form the selected aspects to natal planets, ASC, or MC. Defaults to outer planets (Jupiter→Pluto) and all five Ptolemaic aspects. Pass `?stream=true` to receive results as an SSE stream — one frame per transiting body (`{type:\"body\",body,hits}`), bracketed by `{type:\"start\",...}` and `{type:\"done\",totalHits}`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"bodies":{"type":"array","items":{"type":"string"}},"aspects":{"type":"array","items":{"type":"string"}}},"required":["natal","startDatetime","endDatetime"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"startDatetime":"1990-06-15T12:00:00Z","endDatetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chart/batch":{"post":{"tags":["Chart"],"summary":"Compute up to 25 natal charts in a single request. Lite shape (bodies, houses, aspects — no pattern/shape enrichment). Per-item failure is contained: `results[]` carries `{ index, status: 'ok'|'error' }` aligned to input order. One rate-limit hit for the whole call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"charts":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"houseSystem":{"type":"string","enum":["placidus","porphyry","equal","whole-sign","koch"],"default":"placidus"}},"required":["datetime","latitude","longitude"]}}},"required":["charts"]},"example":{"charts":[{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/transits/batch":{"post":{"tags":["Relational"],"summary":"Compute up to 25 transit charts (each one natal × transit moment) in a single request. Same per-item failure semantics as /chart/batch. One rate-limit hit for the whole call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"transitDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["natal","transitDatetime"]}}},"required":["requests"]},"example":{"requests":[{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"transitDatetime":"2026-04-19T00:00:00Z"},{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"transitDatetime":"2026-10-19T00:00:00Z"}]}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ingress":{"post":{"tags":["Chart"],"summary":"The four cardinal solar ingresses (Aries / Cancer / Libra / Capricorn) for a year, each cast as a full natal-style chart for the given location. Classical mundane astrology — Aries is the year chart; the others mark each quarter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1800,"maximum":2200},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"}},"required":["year","latitude","longitude"]},"example":{"year":2026,"latitude":19.076,"longitude":72.8777}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sign-ingresses":{"post":{"tags":["Events"],"summary":"All tropical-sign-boundary crossings for a body in a date range. Each ingress carries fromSign, toSign, boundaryDeg, and direction (prograde/retrograde — Mercury Rx in particular often back-crosses a boundary). Body parameter accepts the full integrated catalog. Range cap 20 years.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["body","startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stations":{"post":{"tags":["Events"],"summary":"All retrograde-station moments for a body in a date range — the moments longitude rate crosses zero. `direction` is the motion direction immediately AFTER the station (`retrograde` = body just stationed retrograde, `direct` = body just stationed direct). Range cap 50 years. Sun and Moon return empty arrays (they don't retrograde geocentrically).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["body","startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/aspect-events":{"post":{"tags":["Events"],"summary":"All exact aspect moments (conjunction / sextile / square / trine / opposition) between two bodies in a date range. Each event carries the exact JD/datetime, the aspect kind, the signed separation at exact aspect, both longitudes, the relative angular speed at exact (lonA' − lonB' in deg/day, signed), and an `applying` flag (true when bodyA is gaining on bodyB at exact — natural-forward formation; false on retrograde reversals). Range cap: 50 years for outer pairs, 10 years if Moon is involved.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bodyA":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]},"bodyB":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"aspects":{"type":"array","items":{"type":"string","enum":["conjunction","sextile","square","trine","opposition"]}}},"required":["bodyA","bodyB","startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pattern-events":{"post":{"tags":["Events"],"summary":"Find moments when ≥3 bodies form a multi-aspect configuration in a date range. Patterns: grand-trine (3 mutual trines), t-square (opposition + 2 squares to apex), yod (sextile + 2 quincunxes to apex), grand-cross (2 oppositions + 4 squares). Exhaustive over the supplied bodies — every triple (or quad) is scanned. Each event reports the moment of tightest configuration with `kind`, `bodies` (ordered: opposition pair + apex for t-square / yod), `maxOrbDeg` (widest contributing aspect orb at exact), and ISO datetime. Body cap 10. Range cap: 50 years outer-only, 5 years if Moon is involved. `maxOrbDeg` filter (default 1°) controls how strict 'exact' must be.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bodies":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","ceres","pallas","juno","vesta","chiron","pholus","nessus","eris","haumea","makemake","sedna","quaoar"]}},"startDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"endDatetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"patterns":{"type":"array","items":{"type":"string","enum":["grand-trine","t-square","yod","grand-cross"]}},"maxOrbDeg":{"type":"number","exclusiveMinimum":0,"maximum":5,"default":1}},"required":["bodies","startDatetime","endDatetime"]},"example":{"startDatetime":"2026-01-01T00:00:00Z","endDatetime":"2026-03-31T00:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reading/vedic":{"post":{"tags":["Reading"],"summary":"Vedic natal reading centered on the Moon. Returns flowing interpretive paragraphs: nakshatra voice (27 original nakshatra entries with deity, symbol, shakti, and lived meaning) + current Vimshottari Mahadasha + Antardasha narrative. Lahiri ayanamsa by default.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0"},"moon":{"nakshatra":{"name":"Purva Bhadrapada","pada":1,"lord":"jupiter"}},"reading":{"nakshatra":"Purva Bhadrapada is the nakshatra of the two-faced sage — wisdom that has already met its shadow. Your Moon here carries a restless intelligence...","mahadasha":"You are in a Mercury Mahadasha (began 1993-05), which keeps negotiation, writing, and tactical alliance-building at the center of your life...","full":"(full composed narrative)"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ask-chart":{"post":{"tags":["Reading"],"summary":"Claude-grounded natural-language Q&A over a natal chart. The LLM is constrained to reason only from a structured facts block derived from the ephemeris and to cite each placement its answer relies on — no hallucinated signs. Accepts `locale` (en/hi/es/pt) to localise the narrative while keeping technical terms (sign/nakshatra/planet names) in canonical English so citations stay verifiable. Multi-turn: pass `priorMessages: [{role, content}]` from previous turns (max 20 entries, 4000 chars each) — the engine is STATELESS, clients keep their own history. When ANTHROPIC_API_KEY is unset, a deterministic stub answer is returned so integrations work without the model. Tradition defaults to Vedic.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"natal":{"$ref":"#/components/schemas/Person"},"question":{"type":"string","maxLength":500,"description":"Natural-language question (≤ 500 chars)."},"tradition":{"type":"string","enum":["western","vedic"],"default":"vedic"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"locale":{"type":"string","enum":["en","hi","es","pt"],"default":"en","description":"Narrative language. Technical terms stay English."}},"required":["natal","question"]},"example":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"question":"What is the dominant theme of this chart, and what is the current life-chapter?","tradition":"vedic","locale":"hi"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0","computedAt":"2026-04-18T12:00:00Z","inputs":{"natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"tradition":"vedic","ayanamsa":"lahiri"}},"question":"What is the dominant theme of this chart, and what is the current life-chapter?","answer":"The dominant theme is curious communication anchored in emotional depth: Sun in Gemini (h.7) makes relationship-through-ideas central, while Moon in Pisces (h.4) keeps the inner life permeable and intuitive... (truncated)","model":"claude-haiku-4-5-20251001","stubbed":false,"facts":{"lines":["Birth: 1990-06-15T12:00:00Z @ (19.0760, 72.8777)","Ascendant (tropical): Sagittarius 12.34°","PLANET PLACEMENTS (tropical):","  sun: Gemini 24.13° · house 7","  moon: Pisces 8.50° · house 4"],"structured":{"bodies":[{"key":"sun","sign":"Gemini","degreeInSign":24.13,"house":7}],"vedic":{"moonNakshatra":{"name":"Purva Bhadrapada","pada":1,"lord":"jupiter"},"mahadashaNow":{"lord":"mercury"}}}},"note":"Claude-grounded Q&A. The LLM is constrained to reason only from the `facts` block..."}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reading/summary":{"post":{"tags":["Reading"],"summary":"Whole-chart-in-one-paragraph composer — Sun sign + Moon sign + Ascendant archetypal triad, sidereal Moon nakshatra with pada/lord, and active Vimshottari Mahadasha with birth-to-now transition narrative. Ideal for notifications, widgets, or quick-look social sharing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"}},"required":["datetime","latitude","longitude"]},"example":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0","computedAt":"2026-04-18T12:00:00Z","inputs":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777,"ayanamsa":"lahiri"}},"headline":"Gemini Sun · Pisces Moon · Sagittarius rising · Purva Bhadrapada nakshatra · mercury Mahadasha","summary":"Sun in Gemini (curious wit), Moon in Pisces (permeable soul), rising in Sagittarius (expansive seeker). Sidereal Moon sits in Aquarius, Purva Bhadrapada pada 1 (ruled by jupiter). Currently in a Mercury Mahadasha — moved past jupiter at birth into this chapter.","details":{"western":{"sunSign":"Gemini","moonSign":"Pisces","ascSign":"Sagittarius"},"vedic":{"moonSignSidereal":"Aquarius","nakshatra":{"name":"Purva Bhadrapada","lord":"jupiter","pada":1}},"dasha":{"atBirth":{"lord":"jupiter"},"current":{"lord":"mercury"}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/daily-forecast":{"post":{"tags":["Reading"],"summary":"Daily forecast — sky paragraph (Sun sign, Moon sign, Moon nakshatra, Arabic Manzil) plus, when natal is supplied, Navatara classification vs birth Moon, active Vimshottari Mahadasha, and transit events within ±36 hours. Returns a flowing narrative + raw data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"},"natal":{"$ref":"#/components/schemas/Person"}},"required":[]},"example":{"datetime":"2026-04-18T12:00:00Z","natal":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0"},"sky":{"date":"Saturday, April 18, 2026","sun":{"sign":"Aries"},"moon":{"sign":"Leo","nakshatra":{"name":"Purva Phalguni","lord":"venus","pada":2},"manzil":{"name":"Al-Zubrah"}}},"personal":{"navatara":{"navatara":"Mitra","quality":"auspicious","meaning":"a supportive friend-day"},"activeDasha":{"lord":"mercury"},"transits":[{"body":"moon","aspect":"trine","natalTarget":"sun","exactDatetime":"2026-04-18T18:00:00Z","orb":0}]},"reading":{"sky":"Today (Saturday, April 18, 2026), the Sun is in Aries and the Moon is in Leo...","personal":"Relative to your birth Moon, today is a Mitra (friend) day — supportive currents.","transits":"Key transits in the ±36-hour window: moon trine natal sun (2026-04-18)","closing":"Move with the day rather than against it...","full":"(full composed narrative)"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/compatibility/narrative":{"post":{"tags":["Relational"],"summary":"Unified relationship reading composing composite chart (midpoint method) + synastry cross-aspects between two natal charts into a 3-paragraph narrative focused on Sun/Moon/Mars/Venus/ASC/MC contacts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"}},"required":["personA","personB"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"meta":{"engine":"insights-by-omkar-kriya","version":"7.5.0"},"reading":{"opening":"The composite chart — the midpoint of your two natal charts — centers on Virgo Sun, Libra Moon, and Leo Venus. Read this as the 'third entity' the relationship creates.","synastry":"The most charged cross-contacts: A.sun trine B.moon (1.2°); A.venus conjunction B.mars (0.8°); A.mercury square B.saturn (2.1°)...","closing":"Composite tells you what this relationship IS; synastry tells you what you two DO to each other."},"composite":[{"key":"sun","sign":"Virgo","degreeInSign":8.4}],"topAspects":[{"personAKey":"sun","personBKey":"moon","kind":"trine","orbDeg":1.2}],"totalAspects":37}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vedic/tajika-synastry":{"post":{"tags":["Vedic"],"summary":"Tajika aspects between two persons' Varshaphala (annual return) charts. Useful for relationship assessment at a specific shared year (career, marriage, joint ventures). Supports different ages per person via `ageYearsB`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/Person"},"personB":{"$ref":"#/components/schemas/Person"},"ayanamsa":{"type":"string","enum":["lahiri","raman","kp","fagan-bradley","yukteswar"],"default":"lahiri"},"ageYears":{"type":"number","minimum":0,"maximum":150},"ageYearsB":{"type":"number","minimum":0,"maximum":150,"description":"Person B's age if different from Person A's; defaults to ageYears."}},"required":["personA","personB","ageYears"]},"example":{"personA":{"datetime":"1990-06-15T12:00:00Z","latitude":19.076,"longitude":72.8777},"personB":{"datetime":"1992-09-22T06:30:00Z","latitude":12.9716,"longitude":77.5946}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/asteroids/extended":{"post":{"tags":["Points"],"summary":"Extended minor-planet catalog — 10 astrologically-popular asteroids beyond the core 5: Lilith (#1181), Psyche, Eros, Sappho, Hygiea, Astraea, Hebe, Iris, Flora, Metis. Approximate (~1° over ±200y of J2000).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"ISO 8601 datetime with explicit timezone (Z or ±HH:mm).","example":"1990-06-15T12:00:00Z"}},"required":["datetime"]},"example":{"datetime":"1990-06-15T12:00:00Z"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/critic/rubrics":{"get":{"tags":["Critic"],"summary":"List available critic rubrics (character-figure, ambient-effect).","description":"Returns summaries for every rubric the critic ships. Full detail at /rubrics/:id. Scope: critic:v1:read.","responses":{"200":{"description":"Success"}}}},"/critic/rubrics/{id}":{"get":{"tags":["Critic"],"summary":"Fetch a rubric's full definition (axes, weights, anchors, framing).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Rubric not found"}}}},"/critic/references":{"get":{"tags":["Critic"],"summary":"List reference sets (great-dane, etc.) and their compatible rubrics.","responses":{"200":{"description":"Success"}}}},"/critic/references/{id}":{"get":{"tags":["Critic"],"summary":"Fetch a reference set's full metadata, licenses, and landmark specs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Reference set not found"}}}},"/critic/critique":{"post":{"tags":["Critic"],"summary":"Evaluate a rendered image against a rubric + reference set. Returns per-axis scores (0-10), weighted total, ordered failings, narrative. Scope: critic:v1:use (metered / billable).","description":"Independent LLM-based craft critique. The response carries `critique` (scores + failings + narrative), `cache` (hit + key), `usage` (costUsd + tokens), and `provider` (anonymised id of the LLM that produced the critique).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"output":{"type":"object","description":"Either { kind: \"image-url\", url } or { kind: \"image-data\", dataUri }."},"rubricId":{"type":"string","description":"See GET /critic/rubrics."},"referenceSetId":{"type":"string","description":"See GET /critic/references."},"subjectHint":{"type":"string","description":"Optional, ≤ 500 chars."},"providerId":{"type":"string","description":"Optional. Default: openai/gpt-4o."},"timeoutMs":{"type":"number","minimum":10000,"maximum":120000},"useCache":{"type":"boolean","description":"Default: true. Set false to force a fresh critique."}},"required":["output","rubricId","referenceSetId"]},"example":{"output":{"kind":"image-url","url":"https://example.com/renders/dane-001.png"},"rubricId":"character-figure","referenceSetId":"great-dane","subjectHint":"adult male great dane, full-body profile"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}