{"openapi":"3.1.0","security":[{"bearerAuth":[]}],"info":{"title":"Almuten Astrology API","version":"1.0.0","description":"\nA comprehensive astrology API providing astronomical calculations and horoscope interpretations.\n\n## Features\n\n- **Planetary Positions**: Get precise tropical zodiac positions for all major celestial bodies\n- **Aspects**: Calculate planetary aspects with customizable orbs\n- **Moon Phases**: Track lunar cycles and find upcoming phases\n- **Horoscopes**: Daily and weekly horoscope interpretations for all 12 signs\n- **Ephemeris**: Multi-day position data for astrological research\n\n## Data Sources\n\nPlanetary positions are calculated using VSOP87 theory for inner planets and simplified\nKeplerian elements for outer bodies. Accuracy is approximately 1 arcminute, suitable\nfor daily horoscope applications.\n\n## Zodiac System\n\nAll positions are given in the **tropical zodiac** (Western astrology standard).\n\n## Rate Limiting\n\nAll API endpoints are rate-limited to **100 requests per minute** per API key using a sliding-window algorithm.\n\nRate limit status is returned in response headers:\n- `X-RateLimit-Limit`: Maximum requests per window (100)\n- `X-RateLimit-Remaining`: Remaining requests in the current window\n- `X-RateLimit-Reset`: Unix epoch timestamp when the window resets\n\nWhen the limit is exceeded, a `429 Too Many Requests` response is returned with a `Retry-After` header indicating how many seconds to wait.\n\n## Response Caching\n\nResponses are cached server-side with per-route TTLs. The `X-Cache` header indicates whether the response was served from cache (`HIT`) or computed fresh (`MISS`).\n\n| Route pattern | TTL |\n|---|---|\n| `/positions/today`, `/moon/today`, `/aspects/today`, `/almanac` | 5 minutes |\n| `/horoscope/daily`, `/horoscope/all` | 15 minutes |\n| All other endpoints | 1 hour |\n\n## Timeout\n\nAll API requests have a **30-second timeout**. Requests exceeding this limit are terminated with a `408 Request Timeout` response. Long date ranges on computationally intensive endpoints (eclipses, retrogrades) may approach this limit.\n    ","license":{"name":"Proprietary"}},"servers":[{"url":"https://almuten-api.fly.dev","description":"Production"}],"tags":[{"name":"Positions","description":"Planetary position endpoints"},{"name":"Aspects","description":"Planetary aspect calculations"},{"name":"Moon","description":"Lunar phase information"},{"name":"Horoscope","description":"Horoscope interpretations"},{"name":"Seasons","description":"Equinoxes and solstices"},{"name":"Eclipses","description":"Solar and lunar eclipses"},{"name":"Ingress","description":"Planetary sign ingresses"},{"name":"Planetary Hours","description":"Traditional planetary hour calculations"},{"name":"Chinese Calendar","description":"Chinese lunar calendar with zodiac animals, elements, and compatibility"},{"name":"Fixed Stars","description":"Fixed star positions with precession and planet-star conjunctions"},{"name":"Natal Chart","description":"Natal birth chart calculations"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key: Authorization: Bearer alm_live_...","x-ratelimit-limit":100,"x-ratelimit-window":"60s","x-ratelimit-policy":"sliding-window per API key"}},"schemas":{"ZodiacPosition":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"maximum":360,"description":"Ecliptic longitude in degrees (0-360)","example":245.5},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Sagittarius"},"degree":{"type":"number","minimum":0,"maximum":30,"description":"Degree within the sign (0-30)","example":5},"minute":{"type":"number","minimum":0,"maximum":60,"description":"Arc minutes within the degree","example":30},"isRetrograde":{"type":"boolean","description":"Whether the body appears to be moving backward","example":false}},"required":["longitude","sign","degree","minute","isRetrograde"]},"PlanetaryPosition":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The celestial body","example":"Mars"},"position":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["body","position"]},"Aspect":{"type":"object","properties":{"body1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Sun"},"body2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Moon"},"type":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"],"example":"trine"},"orb":{"type":"number","description":"The difference from exact aspect in degrees","example":2.5},"isApplying":{"type":"boolean","description":"Whether the aspect is applying (getting closer) or separating","example":true}},"required":["body1","body2","type","orb","isApplying"]},"HouseIngressEvent":{"type":"object","properties":{"body":{"type":"string","example":"Moon"},"date":{"type":"string","example":"2025-06-15T13:27:18.999Z"},"enteringHouse":{"type":"number","minimum":1,"maximum":12,"description":"House number being entered (1-12)","example":1},"longitude":{"type":"number","minimum":0,"maximum":360,"description":"Body longitude at crossing","example":314.2558},"cuspLongitude":{"type":"number","minimum":0,"maximum":360,"description":"Cusp longitude at crossing","example":314.2578},"isAngle":{"type":"boolean","description":"Whether this crossing is at a major angle (ASC, MC, DESC, IC)","example":true},"angleName":{"type":"string","enum":["ASC","MC","DESC","IC"],"description":"Name of the angle, if applicable","example":"ASC"}},"required":["body","date","enteringHouse","longitude","cuspLongitude","isAngle"]},"MoonPhaseInfo":{"type":"object","properties":{"phase":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"]},"illumination":{"type":"number","minimum":0,"maximum":100,"description":"Percentage of Moon illuminated","example":75.5},"date":{"type":"string","description":"ISO date string","example":"2025-11-26"}},"required":["phase","illumination","date"]},"Horoscope":{"type":"object","properties":{"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"date":{"type":"string","example":"2025-11-26"},"perspective":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective used (sun, moon, or rising)","example":"sun"},"signContext":{"$ref":"#/components/schemas/SignContext"},"rulerCondition":{"$ref":"#/components/schemas/RulerCondition"},"moonContext":{"$ref":"#/components/schemas/MoonContext"},"voidOfCourseStatus":{"$ref":"#/components/schemas/VoidOfCourseStatus"},"transits":{"type":"array","items":{"$ref":"#/components/schemas/TransitToSign"},"description":"Key transits affecting this sign (up to 3)"},"retrogrades":{"type":"array","items":{"$ref":"#/components/schemas/RetrogradeStatus"},"description":"Currently retrograde planets"}},"required":["sign","date","signContext","rulerCondition","moonContext","voidOfCourseStatus","transits","retrogrades"]},"SignContext":{"type":"object","properties":{"element":{"type":"string","enum":["Fire","Earth","Air","Water"]},"modality":{"type":"string","enum":["Cardinal","Fixed","Mutable"]},"keywords":{"type":"array","items":{"type":"string"}}},"required":["element","modality","keywords"]},"RulerCondition":{"type":"object","properties":{"ruler":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["ruler","sign"]},"MoonContext":{"type":"object","properties":{"phase":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"]},"illumination":{"type":"number","minimum":0,"maximum":100}},"required":["phase","illumination"]},"VoidOfCourseStatus":{"type":"object","properties":{"isVoidOfCourse":{"type":"boolean"},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"endsAt":{"type":"string"}},"required":["isVoidOfCourse","moonSign"]},"TransitToSign":{"type":"object","properties":{"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"planetSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"aspectType":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"]},"aspectNature":{"type":"string","enum":["harmonious","challenging","neutral"]},"orb":{"type":"number"},"isApplying":{"type":"boolean"}},"required":["planet","planetSign","aspectType","aspectNature","orb","isApplying"]},"RetrogradeStatus":{"type":"object","properties":{"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"isTransitingSign":{"type":"boolean"}},"required":["planet","sign","isTransitingSign"]},"WeeklyHoroscope":{"type":"object","properties":{"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"weekStart":{"type":"string"},"weekEnd":{"type":"string"},"perspective":{"type":"string","enum":["sun","moon","rising"]},"signContext":{"$ref":"#/components/schemas/SignContext"},"rulerCondition":{"type":"object","properties":{"ruler":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"startSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"endSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"signChanged":{"type":"boolean"}},"required":["ruler","startSign","endSign","signChanged"]},"moonPhaseAtStart":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"]},"moonPhaseAtEnd":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"]},"dailySnapshots":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyDailySnapshot"}}},"required":["sign","weekStart","weekEnd","signContext","rulerCondition","moonPhaseAtStart","moonPhaseAtEnd","dailySnapshots"]},"WeeklyDailySnapshot":{"type":"object","properties":{"date":{"type":"string"},"transits":{"type":"array","items":{"$ref":"#/components/schemas/TransitToSign"}},"moonPhase":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"]},"voidOfCourse":{"type":"boolean"}},"required":["date","transits","moonPhase","voidOfCourse"]},"HouseCusp":{"type":"object","properties":{"house":{"type":"number","minimum":1,"maximum":12,"description":"House number (1-12)","example":1},"cusp":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["house","cusp"]},"AspectPattern":{"type":"object","properties":{"type":{"type":"string","enum":["grandTrine","tSquare","grandCross","yod","kite","mysticRectangle","stellium"]},"bodies":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["type","bodies","description"]},"ChartShape":{"type":"object","properties":{"shape":{"type":"string","enum":["bowl","bucket","bundle","locomotive","seesaw","splash","splay"]},"description":{"type":"string"},"leadingPlanet":{"type":"string"}},"required":["shape","description"]},"HemisphericEmphasis":{"type":"object","properties":{"north":{"type":"number"},"south":{"type":"number"},"east":{"type":"number"},"west":{"type":"number"},"dominant":{"type":"string"}},"required":["north","south","east","west","dominant"]},"QuadrantEmphasis":{"type":"object","properties":{"northeast":{"type":"number"},"northwest":{"type":"number"},"southeast":{"type":"number"},"southwest":{"type":"number"},"dominant":{"type":"string"}},"required":["northeast","northwest","southeast","southwest","dominant"]},"PlanetaryJoy":{"type":"object","properties":{"planet":{"type":"string"},"joyHouse":{"type":"number","minimum":1,"maximum":12},"description":{"type":"string"}},"required":["planet","joyHouse","description"]},"PlanetInSignInterpretation":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string"},"summary":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"strengths":{"type":"array","items":{"type":"string"}},"challenges":{"type":"array","items":{"type":"string"}}},"required":["body","sign","summary","keywords","description","strengths","challenges"]},"PlanetInHouseInterpretation":{"type":"object","properties":{"body":{"type":"string"},"house":{"type":"number","minimum":1,"maximum":12},"summary":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"strengths":{"type":"array","items":{"type":"string"}},"challenges":{"type":"array","items":{"type":"string"}}},"required":["body","house","summary","keywords","description","strengths","challenges"]},"AspectInterpretationDetailed":{"type":"object","properties":{"body1":{"type":"string"},"body2":{"type":"string"},"aspect":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}},"required":["body1","body2","aspect","summary","description","keywords"]},"HouseMeaning":{"type":"object","properties":{"house":{"type":"number","minimum":1,"maximum":12},"name":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"rulingSign":{"type":"string"},"rulingPlanet":{"type":"string"}},"required":["house","name","keywords","description","rulingSign","rulingPlanet"]},"SabianSymbol":{"type":"object","properties":{"sign":{"type":"string"},"degree":{"type":"number","minimum":1,"maximum":30},"symbol":{"type":"string"},"keynote":{"type":"string"}},"required":["sign","degree","symbol","keynote"]},"DecanInfo":{"type":"object","properties":{"sign":{"type":"string"},"decan":{"type":"number","minimum":1,"maximum":3},"startDegree":{"type":"number"},"endDegree":{"type":"number"},"chaldeanRuler":{"type":"string"},"triplicityRuler":{"type":"string"},"description":{"type":"string"}},"required":["sign","decan","startDegree","endDegree","chaldeanRuler","triplicityRuler","description"]},"NatalChartResponse":{"type":"object","properties":{"birthDate":{"type":"string"},"birthTime":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"houseSystem":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"]},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"position":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["body","position"]}},"houses":{"type":"array","items":{"$ref":"#/components/schemas/HouseCusp"}},"housesAvailable":{"type":"boolean"},"ascendant":{"type":"number"},"ascendantSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"midheaven":{"type":"number"},"midheavenSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}},"elementBalance":{"$ref":"#/components/schemas/ElementBalance"},"modalityBalance":{"$ref":"#/components/schemas/ModalityBalance"},"chartRuler":{"$ref":"#/components/schemas/ChartRuler"},"partOfFortune":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string"},"degree":{"type":"number"}},"required":["longitude","sign","degree"]},"dignities":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string"},"dignity":{"type":"string"},"score":{"type":"number"}},"required":["body","sign","dignity","score"]}},"combustionStatuses":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"status":{"type":"string","enum":["cazimi","combust","underTheBeams","free"]}},"required":["body","status"]}},"mutualReceptions":{"type":"array","items":{"type":"object","properties":{"body1":{"type":"string"},"body2":{"type":"string"},"sign1":{"type":"string"},"sign2":{"type":"string"},"type":{"type":"string","enum":["domicile","exaltation","mixed"]}},"required":["body1","body2","sign1","sign2","type"]}},"outOfBoundsPlanets":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"declination":{"type":"number"}},"required":["body","declination"]}},"decanInfo":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"decan":{"type":"number","minimum":1,"maximum":3},"faceRuler":{"type":"string"}},"required":["body","decan","faceRuler"]}},"speedClassifications":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"dailyMotion":{"type":"number"},"classification":{"type":"string","enum":["fast","average","slow","retrograde"]}},"required":["body","dailyMotion","classification"]}},"besiegedPlanets":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"isBesieged":{"type":"boolean"},"besiegingMalefics":{"type":"array","items":{"type":"string"}}},"required":["body","isBesieged"]}}},"required":["birthDate","latitude","longitude","houseSystem","positions","housesAvailable","aspects","elementBalance","modalityBalance"]},"ElementBalance":{"type":"object","properties":{"fire":{"type":"number"},"earth":{"type":"number"},"air":{"type":"number"},"water":{"type":"number"},"dominant":{"type":"string"}},"required":["fire","earth","air","water","dominant"]},"ModalityBalance":{"type":"object","properties":{"cardinal":{"type":"number"},"fixed":{"type":"number"},"mutable":{"type":"number"},"dominant":{"type":"string"}},"required":["cardinal","fixed","mutable","dominant"]},"ChartRuler":{"type":"object","properties":{"planet":{"type":"string"},"sign":{"type":"string"},"longitude":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["planet","sign","longitude","isRetrograde"]},"NatalChartRequest":{"type":"object","properties":{"birthDate":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"1990-06-15"},"birthTime":{"type":"string","description":"Birth time in HH:MM format (24h). If omitted, houses are unavailable.","example":"14:30"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Birth location latitude","example":40.7128},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Birth location longitude","example":-74.006},"houseSystem":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus","description":"House system","example":"Placidus"},"orbProfile":{"type":"string","enum":["modern-western","traditional","vedic","tight"],"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","example":"modern-western"}},"required":["birthDate","latitude","longitude"]},"Nakshatra":{"type":"object","properties":{"index":{"type":"number","minimum":0,"maximum":26},"name":{"type":"string"},"ruler":{"type":"string"},"deity":{"type":"string"},"symbol":{"type":"string"},"quality":{"type":"string","enum":["Deva","Manushya","Rakshasa"]},"yoni":{"type":"object","properties":{"animal":{"type":"string"},"gender":{"type":"string","enum":["male","female"]}},"required":["animal","gender"]},"pada":{"type":"number","minimum":1,"maximum":4},"startDegree":{"type":"number"},"endDegree":{"type":"number"}},"required":["index","name","ruler","deity","symbol","quality","yoni","pada","startDegree","endDegree"]},"AshtakootScore":{"type":"object","properties":{"varna":{"type":"number","minimum":0,"maximum":1},"vashya":{"type":"number","minimum":0,"maximum":2},"tara":{"type":"number","minimum":0,"maximum":3},"yoni":{"type":"number","minimum":0,"maximum":4},"grahamaitri":{"type":"number","minimum":0,"maximum":5},"gana":{"type":"number","minimum":0,"maximum":6},"bhakoot":{"type":"number","minimum":0,"maximum":7},"nadi":{"type":"number","minimum":0,"maximum":8},"total":{"type":"number","minimum":0,"maximum":36}},"required":["varna","vashya","tara","yoni","grahamaitri","gana","bhakoot","nadi","total"]},"DashaPeriod":{"type":"object","properties":{"planet":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"durationYears":{"type":"number"},"subPeriods":{"type":"array","items":{"$ref":"#/components/schemas/DashaPeriod"}}},"required":["planet","startDate","endDate"]},"VedicAspectResult":{"type":"object","properties":{"date":{"type":"string","description":"Date of calculation","example":"2025-06-15"},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"],"description":"Ayanamsa system used and its value"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/VedicPlanetPosition"},"description":"Sidereal positions of all classical planets"},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/VedicAspect"},"description":"All Vedic aspects found between planets"}},"required":["date","ayanamsa","positions","aspects"]},"VedicPlanetPosition":{"type":"object","properties":{"planet":{"type":"string","description":"Planet name","example":"Mars"},"tropicalLongitude":{"type":"number","description":"Tropical ecliptic longitude in degrees","example":120.5},"siderealLongitude":{"type":"number","description":"Sidereal ecliptic longitude in degrees","example":96.7},"sign":{"type":"string","description":"Sidereal zodiac sign","example":"Cancer"},"signIndex":{"type":"number","description":"Sign index (0 = Aries, 11 = Pisces)","example":3},"nakshatra":{"type":"string","description":"Nakshatra name","example":"Pushya"}},"required":["planet","tropicalLongitude","siderealLongitude","sign","signIndex","nakshatra"]},"VedicAspect":{"type":"object","properties":{"aspectingPlanet":{"type":"string","description":"The planet casting the aspect","example":"Mars"},"aspectedPlanet":{"type":"string","description":"The planet receiving the aspect","example":"Jupiter"},"aspectType":{"type":"string","description":"Type of aspect (e.g., 7th, 4th, 8th)","example":"4th"},"aspectOffset":{"type":"number","description":"Sign offset of the aspect","example":4},"strength":{"type":"number","description":"Aspect strength score (0-5 scale)","example":3.5},"friendshipLevel":{"type":"string","description":"Planetary friendship between the two planets","example":"friend"}},"required":["aspectingPlanet","aspectedPlanet","aspectType","aspectOffset","strength","friendshipLevel"]},"ArabicPart":{"type":"object","properties":{"name":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string"},"degree":{"type":"number"},"formula":{"type":"string"}},"required":["name","longitude","sign","degree","formula"]},"Profection":{"type":"object","properties":{"age":{"type":"number"},"activatedHouse":{"type":"number","minimum":1,"maximum":12},"activatedSign":{"type":"string"},"lordOfTheYear":{"type":"string"}},"required":["age","activatedHouse","activatedSign","lordOfTheYear"]},"ZodiacalReleasingPeriod":{"type":"object","properties":{"sign":{"type":"string"},"lord":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"durationMonths":{"type":"number"},"level":{"type":"number","minimum":1,"maximum":4},"isPeakPeriod":{"type":"boolean"},"isLoosingOfTheBond":{"type":"boolean"}},"required":["sign","lord","startDate","endDate","durationMonths","level","isPeakPeriod","isLoosingOfTheBond"]},"Antiscia":{"type":"object","properties":{"body":{"type":"string"},"originalLongitude":{"type":"number"},"antisciaLongitude":{"type":"number"},"antisciaSign":{"type":"string"},"contraAntisciaLongitude":{"type":"number"},"contraAntisciaSign":{"type":"string"}},"required":["body","originalLongitude","antisciaLongitude","antisciaSign","contraAntisciaLongitude","contraAntisciaSign"]},"AntisciaConnection":{"type":"object","properties":{"body1":{"type":"string"},"body2":{"type":"string"},"type":{"type":"string","enum":["antiscia","contraAntiscia"]},"orb":{"type":"number"}},"required":["body1","body2","type","orb"]},"Temperament":{"type":"object","properties":{"hot":{"type":"number"},"cold":{"type":"number"},"wet":{"type":"number"},"dry":{"type":"number"},"primary":{"type":"string"},"secondary":{"type":"string"}},"required":["hot","cold","wet","dry","primary","secondary"]},"PrenatalLunation":{"type":"object","properties":{"type":{"type":"string","enum":["newMoon","fullMoon"]},"date":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string"}},"required":["type","date","longitude","sign"]},"TransitAspect":{"type":"object","properties":{"transitBody":{"type":"string"},"natalBody":{"type":"string"},"aspect":{"type":"string"},"orb":{"type":"number"},"isApplying":{"type":"boolean"},"transitLongitude":{"type":"number"},"natalLongitude":{"type":"number"}},"required":["transitBody","natalBody","aspect","orb","isApplying","transitLongitude","natalLongitude"]},"ProgressedChart":{"type":"object","properties":{"birthDate":{"type":"string","description":"Original birth date in ISO format","example":"2000-01-01"},"targetDate":{"type":"string","description":"Target date for progression","example":"2030-01-01"},"progressedDate":{"type":"string","description":"Progressed date (birth date + 1 day per year of life)","example":"2000-01-31"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"position":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["body","position"]}},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}}},"required":["birthDate","targetDate","progressedDate","positions","aspects"]},"SolarReturn":{"type":"object","properties":{"natalSunLongitude":{"type":"number","description":"Natal Sun longitude in degrees","example":280.5},"targetYear":{"type":"number","description":"Year for which the solar return is calculated","example":2025},"exactDate":{"type":"string","description":"Exact date and time of the solar return","example":"2025-01-01T03:45:00.000Z"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"position":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["body","position"]}},"houses":{"type":"array","items":{"$ref":"#/components/schemas/HouseCusp"}},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}}},"required":["natalSunLongitude","targetYear","exactDate","positions","aspects"]},"LunarReturn":{"type":"object","properties":{"natalMoonLongitude":{"type":"number","description":"Natal Moon longitude in degrees","example":120.3},"exactDate":{"type":"string","description":"Exact date and time of the lunar return","example":"2025-02-15T14:22:00.000Z"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"position":{"$ref":"#/components/schemas/ZodiacPosition"}},"required":["body","position"]}},"houses":{"type":"array","items":{"$ref":"#/components/schemas/HouseCusp"}},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}}},"required":["natalMoonLongitude","exactDate","positions","aspects"]},"SolarArc":{"type":"object","properties":{"birthDate":{"type":"string","description":"Birth date in ISO format","example":"2000-01-01"},"targetDate":{"type":"string","description":"Target date for solar arc directions","example":"2030-01-01"},"arc":{"type":"number","description":"Solar arc in degrees (difference between progressed and natal Sun)","example":30.5},"directedPositions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","example":"Moon"},"natalLongitude":{"type":"number","description":"Original natal longitude","example":120.3},"directedLongitude":{"type":"number","description":"Longitude after applying solar arc","example":150.8},"sign":{"type":"string","description":"Zodiac sign of the directed position","example":"Virgo"},"degree":{"type":"number","description":"Degree within the sign","example":0}},"required":["body","natalLongitude","directedLongitude","sign","degree"]}}},"required":["birthDate","targetDate","arc","directedPositions"]},"SynastryResponse":{"type":"object","properties":{"personA":{"type":"object","properties":{"birthDate":{"type":"string"},"positions":{"type":"array","items":{"nullable":true}}},"required":["birthDate","positions"]},"personB":{"type":"object","properties":{"birthDate":{"type":"string"},"positions":{"type":"array","items":{"nullable":true}}},"required":["birthDate","positions"]},"interAspects":{"type":"array","items":{"$ref":"#/components/schemas/InterAspect"}},"houseOverlaysAtoB":{"type":"array","items":{"$ref":"#/components/schemas/HouseOverlay"}},"houseOverlaysBtoA":{"type":"array","items":{"$ref":"#/components/schemas/HouseOverlay"}},"scores":{"$ref":"#/components/schemas/CompatibilityScores"}},"required":["personA","personB","interAspects","scores"]},"InterAspect":{"type":"object","properties":{"bodyA":{"type":"string","example":"Sun"},"bodyB":{"type":"string","example":"Moon"},"aspect":{"type":"string","example":"trine"},"orb":{"type":"number","example":2.5},"isApplying":{"type":"boolean","nullable":true,"description":"Not applicable in natal-to-natal synastry (both charts are static)","example":null}},"required":["bodyA","bodyB","aspect","orb"]},"HouseOverlay":{"type":"object","properties":{"body":{"type":"string","example":"Venus"},"bodyLongitude":{"type":"number","example":120.5},"house":{"type":"number","minimum":1,"maximum":12,"example":7}},"required":["body","bodyLongitude","house"]},"CompatibilityScores":{"type":"object","properties":{"overall":{"type":"number","minimum":0,"maximum":100,"example":72},"emotional":{"type":"number","minimum":0,"maximum":100,"example":80},"communication":{"type":"number","minimum":0,"maximum":100,"example":65},"attraction":{"type":"number","minimum":0,"maximum":100,"example":78},"growth":{"type":"number","minimum":0,"maximum":100,"example":60}},"required":["overall","emotional","communication","attraction","growth"]},"SynastryRequest":{"type":"object","properties":{"personA":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-06-15"},"birthTime":{"type":"string","example":"14:30"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006}},"required":["birthDate","latitude","longitude"]},"personB":{"type":"object","properties":{"birthDate":{"type":"string","example":"1992-03-22"},"birthTime":{"type":"string","example":"09:15"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":34.0522},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-118.2437}},"required":["birthDate","latitude","longitude"]},"houseSystem":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus"},"orbProfile":{"type":"string","enum":["modern-western","traditional","vedic","tight"],"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","example":"modern-western"}},"required":["personA","personB"]},"CompositeResponse":{"type":"object","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/CompositePosition"}},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/CompositeAspect"}},"ascendant":{"type":"number"},"ascendantSign":{"type":"string"},"midheaven":{"type":"number"},"midheavenSign":{"type":"string"}},"required":["positions","aspects"]},"CompositePosition":{"type":"object","properties":{"body":{"type":"string","example":"Sun"},"longitude":{"type":"number","example":105.25},"sign":{"type":"string","example":"Cancer"},"degree":{"type":"number","example":15}},"required":["body","longitude","sign","degree"]},"CompositeAspect":{"type":"object","properties":{"body1":{"type":"string","example":"Sun"},"body2":{"type":"string","example":"Moon"},"type":{"type":"string","example":"trine"},"orb":{"type":"number","example":2.1}},"required":["body1","body2","type","orb"]},"CompositeRequest":{"type":"object","properties":{"personA":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-06-15"},"birthTime":{"type":"string","example":"14:30"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006}},"required":["birthDate","latitude","longitude"]},"personB":{"type":"object","properties":{"birthDate":{"type":"string","example":"1992-03-22"},"birthTime":{"type":"string","example":"09:15"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":34.0522},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-118.2437}},"required":["birthDate","latitude","longitude"]},"houseSystem":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus"}},"required":["personA","personB"]},"DeclinationsResponse":{"type":"object","properties":{"date":{"type":"string","description":"ISO date string","example":"2025-06-21"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/DeclinationPosition"},"description":"Declination data for each celestial body"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelAspect"},"description":"Parallel and contraparallel aspects between bodies"},"outOfBounds":{"type":"array","items":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"description":"Bodies whose declination exceeds the solar maximum (~23.43°)"},"trueLilith":{"$ref":"#/components/schemas/TrueLilithPosition"}},"required":["date","positions","parallels","outOfBounds","trueLilith"]},"DeclinationPosition":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The celestial body","example":"Sun"},"longitude":{"type":"number","description":"Ecliptic longitude in degrees (0-360)","example":90.5},"declination":{"type":"number","description":"Declination in degrees (positive = north, negative = south)","example":23.44},"isOutOfBounds":{"type":"boolean","description":"Whether the declination exceeds the maximum solar declination (~23.43°)","example":false}},"required":["body","longitude","declination","isOutOfBounds"]},"ParallelAspect":{"type":"object","properties":{"body1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Sun"},"body2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Moon"},"type":{"type":"string","enum":["parallel","contraparallel"],"description":"Parallel: same declination; contraparallel: equal but opposite declination","example":"parallel"},"orb":{"type":"number","description":"The difference from exact parallel in degrees","example":0.5},"declination1":{"type":"number","description":"Declination of the first body in degrees","example":23.2},"declination2":{"type":"number","description":"Declination of the second body in degrees","example":23}},"required":["body1","body2","type","orb","declination1","declination2"]},"TrueLilithPosition":{"type":"object","properties":{"longitude":{"type":"number","description":"Ecliptic longitude of True (osculating) Lilith in degrees (0-360)","example":120.5},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign of True Lilith","example":"Leo"},"declination":{"type":"number","description":"Declination of True Lilith in degrees","example":15.3}},"required":["longitude","sign","declination"],"description":"True (osculating) Lilith position"},"Midpoint":{"type":"object","properties":{"body1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"First celestial body","example":"Sun"},"body2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Second celestial body","example":"Moon"},"midpointLongitude":{"type":"number","minimum":0,"maximum":360,"description":"Ecliptic longitude of the midpoint in degrees (0-360)","example":125.5},"midpointSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign of the midpoint","example":"Leo"},"midpointDegree":{"type":"number","minimum":0,"maximum":30,"description":"Degree within the sign (0-30)","example":5.5}},"required":["body1","body2","midpointLongitude","midpointSign","midpointDegree"]},"MidpointActivation":{"type":"object","properties":{"midpoint":{"type":"object","properties":{"body1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Sun"},"body2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Moon"}},"required":["body1","body2"],"description":"The midpoint pair being activated"},"activatingBody":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The body activating the midpoint","example":"Mars"},"activatingLongitude":{"type":"number","minimum":0,"maximum":360,"description":"Longitude of the activating body","example":125.5},"aspectType":{"type":"string","enum":["conjunction","square","opposition"],"description":"Type of hard aspect to the midpoint","example":"conjunction"},"orb":{"type":"number","description":"Orb of the activation in degrees","example":0.75}},"required":["midpoint","activatingBody","activatingLongitude","aspectType","orb"]},"MidpointDial":{"type":"object","properties":{"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The celestial body","example":"Sun"},"originalLongitude":{"type":"number","minimum":0,"maximum":360,"description":"Original ecliptic longitude","example":245.5},"dialPosition":{"type":"number","minimum":0,"maximum":90,"description":"Position on the 90-degree dial (longitude % 90)","example":65.5}},"required":["body","originalLongitude","dialPosition"]},"HeliacalEvent":{"type":"object","properties":{"body":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn"],"description":"The celestial body","example":"Venus"},"type":{"type":"string","enum":["heliacalRising","heliacalSetting","acronychalRising","cosmicalSetting"],"description":"Type of heliacal event","example":"heliacalRising"},"date":{"type":"string","description":"ISO date of the event","example":"2025-06-15"},"longitude":{"type":"number","minimum":0,"maximum":360,"description":"Ecliptic longitude at the event","example":85.5},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign at the event","example":"Gemini"}},"required":["body","type","date","longitude","sign"]},"VenusCyclePhase":{"type":"object","properties":{"phase":{"type":"string","enum":["morningStar","eveningStar","superiorConjunction","inferiorConjunction","maximumEasternElongation","maximumWesternElongation"],"description":"Current phase of the Venus synodic cycle","example":"eveningStar"},"date":{"type":"string","description":"ISO date","example":"2025-11-26"},"elongation":{"type":"number","description":"Angular separation from the Sun in degrees","example":35.5}},"required":["phase","date","elongation"]},"EclipseNatalImpact":{"type":"object","properties":{"eclipseDate":{"type":"string"},"eclipseType":{"type":"string","enum":["solar","lunar"]},"eclipseLongitude":{"type":"number"},"eclipseSign":{"type":"string"},"impactedPlanets":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"natalLongitude":{"type":"number"},"orb":{"type":"number"},"significance":{"type":"string","enum":["high","moderate","low"]}},"required":["body","natalLongitude","orb","significance"]}}},"required":["eclipseDate","eclipseType","eclipseLongitude","eclipseSign","impactedPlanets"]},"RetrogradeCalendarResponse":{"type":"object","properties":{"year":{"type":"number","description":"The calendar year","example":2025},"retrogrades":{"type":"array","items":{"$ref":"#/components/schemas/RetrogradeCalendarEntry"},"description":"All retrograde periods for the year"}},"required":["year","retrogrades"]},"RetrogradeCalendarEntry":{"type":"object","properties":{"body":{"type":"string","description":"The celestial body","example":"Mercury"},"shadowStart":{"type":"string","description":"Start of pre-retrograde shadow","example":"2025-02-25"},"stationRetrograde":{"type":"string","description":"Date planet stations retrograde","example":"2025-03-14"},"stationDirect":{"type":"string","description":"Date planet stations direct","example":"2025-04-07"},"shadowEnd":{"type":"string","description":"End of post-retrograde shadow","example":"2025-04-24"},"retrogradeStartSign":{"type":"string","description":"Zodiac sign at station retrograde","example":"Aries"},"retrogradeEndSign":{"type":"string","description":"Zodiac sign at station direct","example":"Pisces"}},"required":["body","shadowStart","stationRetrograde","stationDirect","shadowEnd","retrogradeStartSign","retrogradeEndSign"]},"AlmanacDay":{"type":"object","properties":{"date":{"type":"string","description":"ISO date string","example":"2025-06-15"},"moonPhase":{"type":"object","properties":{"phase":{"type":"string","description":"Moon phase name"},"illumination":{"type":"number","description":"Illumination percentage"}},"required":["phase","illumination"]},"moonSign":{"type":"string","description":"Zodiac sign the Moon is in","example":"Cancer"},"moonLongitude":{"type":"number","description":"Moon ecliptic longitude in degrees","example":105.42},"isVoidOfCourse":{"type":"boolean","description":"Whether the Moon is void-of-course"},"vocDetails":{"type":"object","properties":{"ends":{"type":"string","description":"When VOC period ends"},"remainingMinutes":{"type":"number","description":"Minutes remaining in VOC period"}},"description":"Void-of-course details (present when isVoidOfCourse is true)"},"retrogradePlanets":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","description":"Retrograde planet name"},"sign":{"type":"string","description":"Zodiac sign of the retrograde planet"}},"required":["body","sign"]},"description":"Currently retrograde planets"},"dayHighlight":{"type":"string","description":"Brief summary of the day based on Moon sign","example":"Moon in Cancer: emotional sensitivity is heightened"}},"required":["date","moonPhase","moonSign","moonLongitude","isVoidOfCourse","retrogradePlanets","dayHighlight"]},"LunarGuidance":{"type":"object","properties":{"date":{"type":"string","description":"ISO date string","example":"2025-06-15"},"moonSign":{"type":"string","description":"Zodiac sign the Moon is in","example":"Cancer"},"moonPhase":{"type":"string","description":"Current Moon phase name","example":"Waxing Crescent"},"illumination":{"type":"number","description":"Moon illumination percentage","example":25.5},"isVoidOfCourse":{"type":"boolean","description":"Whether the Moon is void-of-course"},"recommendations":{"type":"object","properties":{"favorable":{"type":"array","items":{"type":"string"},"description":"Activities favored by current lunar conditions"},"unfavorable":{"type":"array","items":{"type":"string"},"description":"Activities to avoid under current lunar conditions"},"bestFor":{"type":"string","description":"Summary of what the day is best for"}},"required":["favorable","unfavorable","bestFor"]}},"required":["date","moonSign","moonPhase","illumination","isVoidOfCourse","recommendations"]},"SignCompatibility":{"type":"object","properties":{"sign1":{"type":"string"},"sign2":{"type":"string"},"overallScore":{"type":"number","minimum":0,"maximum":100},"elementHarmony":{"type":"number","minimum":0,"maximum":10},"modalityInteraction":{"type":"number","minimum":0,"maximum":10},"naturalAspect":{"type":"string"},"naturalAspectScore":{"type":"number","minimum":0,"maximum":10},"narrative":{"type":"string"},"strengths":{"type":"array","items":{"type":"string"}},"challenges":{"type":"array","items":{"type":"string"}}},"required":["sign1","sign2","overallScore","elementHarmony","modalityInteraction","naturalAspect","naturalAspectScore","narrative","strengths","challenges"]},"ElectionalResponse":{"type":"object","properties":{"activity":{"$ref":"#/components/schemas/ElectionalActivity"},"dateRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"bestWindows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"worstWindows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}}},"required":["activity","dateRange","bestWindows","worstWindows"]},"ElectionalActivity":{"type":"string","enum":["business-launch","wedding","travel","medical","contract","creative-project","financial","communication","spiritual"]},"TimeWindow":{"type":"object","properties":{"date":{"type":"string"},"startTime":{"type":"string"},"endTime":{"type":"string"},"score":{"type":"number"},"moonSign":{"type":"string"},"moonPhase":{"type":"string"},"planetaryHour":{"type":"string"},"isVoidOfCourse":{"type":"boolean"},"factors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"impact":{"type":"string","enum":["positive","negative","neutral"]},"description":{"type":"string"}},"required":["factor","impact","description"]}}},"required":["date","startTime","endTime","score","moonSign","moonPhase","planetaryHour","isVoidOfCourse","factors"]},"ElectionalRequest":{"type":"object","properties":{"activity":{"$ref":"#/components/schemas/ElectionalActivity"},"startDate":{"type":"string","example":"2025-06-01"},"endDate":{"type":"string","example":"2025-06-30"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006},"topN":{"type":"number","minimum":1,"maximum":20,"default":5}},"required":["activity","startDate","endDate","latitude","longitude"]},"MonthlyHoroscope":{"type":"object","properties":{"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"year":{"type":"number","description":"Year","example":2026},"month":{"type":"number","description":"Month (1-12)","example":3},"signContext":{"$ref":"#/components/schemas/SignContext"},"weeklyBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/WeeklyBreakdown"},"description":"Weekly breakdown of the month"},"keyDates":{"type":"array","items":{"$ref":"#/components/schemas/KeyDate"},"description":"Key dates during the month"},"moonPhases":{"type":"array","items":{"$ref":"#/components/schemas/MoonPhaseEntry"},"description":"Moon phases during the month"}},"required":["sign","year","month","signContext","weeklyBreakdown","keyDates","moonPhases"]},"WeeklyBreakdown":{"type":"object","properties":{"weekNumber":{"type":"number","description":"Week number within the month (1-4)","example":1},"startDate":{"type":"string","description":"Start date of the week","example":"2026-03-01"},"endDate":{"type":"string","description":"End date of the week","example":"2026-03-07"},"ingresses":{"type":"array","items":{"$ref":"#/components/schemas/Ingress"},"description":"Planet ingresses during this week"}},"required":["weekNumber","startDate","endDate","ingresses"]},"Ingress":{"type":"object","properties":{"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"date":{"type":"string","example":"2026-03-05"}},"required":["planet","sign","date"]},"KeyDate":{"type":"object","properties":{"date":{"type":"string","description":"ISO date of the key event","example":"2026-03-14"},"event":{"type":"string","description":"Name of the event","example":"Full Moon"},"eventType":{"type":"string","enum":["moonPhase","ingress"],"description":"Type of event","example":"moonPhase"},"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Planet involved (for ingress events)"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Sign involved (for ingress events)"}},"required":["date","event","eventType"]},"MoonPhaseEntry":{"type":"object","properties":{"phase":{"type":"string","description":"Moon phase name","example":"New Moon"},"date":{"type":"string","description":"ISO date of the moon phase","example":"2026-03-01"}},"required":["phase","date"]},"YearlyHoroscope":{"type":"object","properties":{"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"year":{"type":"number","description":"Year","example":2026},"signContext":{"$ref":"#/components/schemas/SignContext"},"quarters":{"type":"array","items":{"$ref":"#/components/schemas/Quarter"},"description":"Quarterly breakdown of the year"},"eclipses":{"type":"array","items":{"$ref":"#/components/schemas/EclipseEntry"},"description":"Eclipses during the year"},"retrogrades":{"type":"array","items":{"$ref":"#/components/schemas/RetrogradeEntry"},"description":"Retrograde periods during the year"}},"required":["sign","year","signContext","quarters","eclipses","retrogrades"]},"Quarter":{"type":"object","properties":{"quarter":{"type":"number","description":"Quarter number (1-4)","example":1},"startDate":{"type":"string","description":"Start date of the quarter","example":"2026-01-01"},"endDate":{"type":"string","description":"End date of the quarter","example":"2026-03-31"},"ingresses":{"type":"array","items":{"$ref":"#/components/schemas/QuarterIngress"},"description":"Planet ingresses during the quarter"}},"required":["quarter","startDate","endDate","ingresses"]},"QuarterIngress":{"type":"object","properties":{"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"date":{"type":"string"}},"required":["planet","sign","date"]},"EclipseEntry":{"type":"object","properties":{"date":{"type":"string","description":"ISO date of the eclipse","example":"2026-03-03"},"type":{"type":"string","description":"Type of eclipse","example":"lunar eclipse"},"sign":{"type":"string","description":"Zodiac sign of the eclipse","example":"Virgo"},"isDirectImpact":{"type":"boolean","description":"Whether the eclipse directly impacts the queried sign"}},"required":["date","type","sign","isDirectImpact"]},"RetrogradeEntry":{"type":"object","properties":{"body":{"type":"string","description":"The retrograde planet","example":"Mercury"},"startDate":{"type":"string","description":"Start date of retrograde","example":"2026-04-01"},"endDate":{"type":"string","description":"End date of retrograde","example":"2026-04-25"},"startSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Sign where retrograde begins"}},"required":["body","startDate","endDate","startSign"]},"PersonalizedHoroscope":{"type":"object","properties":{"birthDate":{"type":"string","description":"Birth date used for the chart","example":"1990-06-15"},"date":{"type":"string","description":"Date the horoscope is for","example":"2026-03-17"},"sunSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Natal Moon sign"},"ascendantSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Natal Ascendant sign"},"perspective":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective used","example":"sun"},"activeTransits":{"type":"array","items":{"$ref":"#/components/schemas/PersonalizedTransit"},"description":"Active transits affecting the natal chart"}},"required":["birthDate","date","sunSign","activeTransits"]},"PersonalizedTransit":{"type":"object","properties":{"transitBody":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The transiting planet","example":"Saturn"},"transitSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Sign of the transiting planet","example":"Pisces"},"aspectType":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"],"description":"Type of aspect formed","example":"conjunction"},"aspectNature":{"type":"string","enum":["harmonious","challenging","neutral"],"description":"Nature of the aspect","example":"neutral"},"natalBody":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The natal body being aspected","example":"Sun"},"significance":{"type":"string","enum":["major","moderate","minor"],"description":"Significance level of the transit","example":"major"},"orb":{"type":"number","description":"Orb of the aspect in degrees","example":2.5}},"required":["transitBody","transitSign","aspectType","aspectNature","natalBody","significance","orb"]},"DynamicHoroscope":{"type":"object","properties":{"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"date":{"type":"string","description":"Date the horoscope is for","example":"2026-03-17"},"signContext":{"$ref":"#/components/schemas/SignContext"},"transits":{"type":"array","items":{"$ref":"#/components/schemas/DynamicHoroscopeTransit"},"description":"Transits involving the sign ruler"},"rulerPosition":{"$ref":"#/components/schemas/RulerPosition"}},"required":["sign","date","signContext","transits","rulerPosition"]},"DynamicHoroscopeTransit":{"type":"object","properties":{"planet":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"The other planet in the aspect","example":"Jupiter"},"aspectType":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"],"description":"Type of aspect","example":"trine"},"aspectNature":{"type":"string","enum":["harmonious","challenging","neutral"],"description":"Nature of the aspect","example":"harmonious"}},"required":["planet","aspectType","aspectNature"]},"RulerPosition":{"type":"object","properties":{"ruler":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Name of the ruling planet","example":"Mars"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Current sign of the ruler","example":"Gemini"}},"required":["ruler","sign"],"description":"Current position of the sign ruler"},"KpChartResult":{"type":"object","properties":{"date":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"planets":{"type":"array","items":{"$ref":"#/components/schemas/KpPlanetPosition"}},"cusps":{"type":"array","items":{"$ref":"#/components/schemas/KpHouseCusp"}},"significators":{"type":"array","items":{"$ref":"#/components/schemas/KpSignificator"}},"rulingPlanets":{"$ref":"#/components/schemas/KpRulingPlanets"}},"required":["date","location","ayanamsa","planets","cusps","significators","rulingPlanets"]},"KpPlanetPosition":{"type":"object","properties":{"body":{"type":"string"},"tropicalLongitude":{"type":"number"},"siderealLongitude":{"type":"number"},"sign":{"type":"string"},"nakshatraName":{"type":"string"},"nakshatraLord":{"type":"string"},"subLord":{"type":"string"},"house":{"type":"number","minimum":1,"maximum":12}},"required":["body","tropicalLongitude","siderealLongitude","sign","nakshatraName","nakshatraLord","subLord","house"]},"KpHouseCusp":{"type":"object","properties":{"house":{"type":"number","minimum":1,"maximum":12},"tropicalLongitude":{"type":"number"},"siderealLongitude":{"type":"number"},"sign":{"type":"string"},"nakshatraName":{"type":"string"},"nakshatraLord":{"type":"string"},"subLord":{"type":"string"}},"required":["house","tropicalLongitude","siderealLongitude","sign","nakshatraName","nakshatraLord","subLord"]},"KpSignificator":{"type":"object","properties":{"body":{"type":"string"},"houseOccupied":{"type":"number","minimum":1,"maximum":12},"starLord":{"type":"string"},"subLord":{"type":"string"},"significatorOf":{"type":"array","items":{"type":"number","minimum":1,"maximum":12}}},"required":["body","houseOccupied","starLord","subLord","significatorOf"]},"KpRulingPlanets":{"type":"object","properties":{"dayLord":{"type":"string"},"moonSignLord":{"type":"string"},"moonStarLord":{"type":"string"},"moonSubLord":{"type":"string"},"ascendantSignLord":{"type":"string"},"ascendantStarLord":{"type":"string"},"ascendantSubLord":{"type":"string"}},"required":["dayLord","moonSignLord","moonStarLord","moonSubLord","ascendantSignLord","ascendantStarLord","ascendantSubLord"]},"KpHoraryResult":{"type":"object","properties":{"horaryNumber":{"type":"number","minimum":1,"maximum":249},"subLordEntry":{"type":"object","properties":{"index":{"type":"number"},"startDegree":{"type":"number"},"endDegree":{"type":"number"},"sign":{"type":"string"},"signLord":{"type":"string"},"nakshatraName":{"type":"string"},"nakshatraLord":{"type":"string"},"subLord":{"type":"string"}},"required":["index","startDegree","endDegree","sign","signLord","nakshatraName","nakshatraLord","subLord"]},"chart":{"$ref":"#/components/schemas/KpChartResult"}},"required":["horaryNumber","subLordEntry","chart"]}},"parameters":{}},"paths":{"/api/v1/positions":{"get":{"tags":["Positions"],"summary":"Get planetary positions","description":"Returns positions of all celestial bodies for a given date in tropical zodiac coordinates. When observer location is provided, includes altitude/azimuth for supported bodies.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","description":"Observer latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Observer latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in decimal degrees","example":"-74.006"},"required":false,"description":"Observer longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Planetary positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-11-26"},"positions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PlanetaryPosition"},{"type":"object","properties":{"altitude":{"type":"number","description":"Degrees above/below horizon"},"azimuth":{"type":"number","description":"Degrees clockwise from north"},"isAboveHorizon":{"type":"boolean","description":"Whether body is above horizon"}}}]}},"warnings":{"type":"array","items":{"type":"string"},"description":"Warnings about calculation accuracy (e.g., Chiron outside ephemeris range)"}},"required":["date","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/today":{"get":{"tags":["Positions"],"summary":"Get today's planetary positions","description":"Shorthand endpoint for current planetary positions. When observer location is provided, includes altitude/azimuth for supported bodies.","parameters":[{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","description":"Observer latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Observer latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in decimal degrees","example":"-74.006"},"required":false,"description":"Observer longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Today's planetary positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-11-26"},"positions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PlanetaryPosition"},{"type":"object","properties":{"altitude":{"type":"number","description":"Degrees above/below horizon"},"azimuth":{"type":"number","description":"Degrees clockwise from north"},"isAboveHorizon":{"type":"boolean","description":"Whether body is above horizon"}}}]}}},"required":["date","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/ephemeris":{"get":{"tags":["Positions"],"summary":"Get ephemeris for date range","description":"Returns planetary positions for each day in the specified date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"ephemeris":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/PlanetaryPosition"}}},"required":["date","positions"]}}},"required":["startDate","endDate","ephemeris"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/sidereal":{"get":{"tags":["Positions"],"summary":"Get sidereal planetary positions","description":"Returns positions of celestial bodies in sidereal zodiac coordinates.\n\nSidereal zodiac is based on the actual positions of constellations and is commonly used in Vedic/Jyotish astrology.\n\n**Available Ayanamsa Systems:**\n- `lahiri` (default): Chitrapaksha ayanamsa, most common in Indian astrology\n- `raman`: B.V. Raman's ayanamsa\n- `krishnamurti`: KP (Krishnamurti Paddhati) system\n- `faganBradley`: Western sidereal astrology","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system to use for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system to use for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"}],"responses":{"200":{"description":"Sidereal planetary positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","ayanamsa","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/sidereal/today":{"get":{"tags":["Positions"],"summary":"Get today's sidereal positions","description":"Shorthand endpoint for current sidereal planetary positions.","parameters":[{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system to use for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system to use for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"}],"responses":{"200":{"description":"Today's sidereal positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","ayanamsa","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/sidereal/ephemeris":{"get":{"tags":["Positions"],"summary":"Get sidereal ephemeris for date range","description":"Returns sidereal planetary positions for each day in the specified date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system to use for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system to use for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"}],"responses":{"200":{"description":"Sidereal ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"ayanamsaSystem":{"type":"string"},"ephemeris":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"ayanamsaValue":{"type":"number"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","ayanamsaValue","positions"]}}},"required":["startDate","endDate","ayanamsaSystem","ephemeris"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/sidereal/ayanamsa":{"get":{"tags":["Positions"],"summary":"Get ayanamsa information","description":"Returns information about available ayanamsa systems and their current values.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Ayanamsa information","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"systems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"valueAtJ2000":{"type":"number"},"currentValue":{"type":"number"}},"required":["id","name","description","valueAtJ2000","currentValue"]}}},"required":["date","systems"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/draconic":{"get":{"tags":["Positions"],"summary":"Get draconic planetary positions","description":"Returns positions of celestial bodies in draconic zodiac coordinates.\n\nThe draconic zodiac is aligned with the Moon's nodes. In this system, the North Node is always at 0° Aries.\nIt's calculated by subtracting the North Node's position from all planetary positions.\n\nThe draconic chart is used in soul-level astrology and karmic interpretation.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Draconic planetary positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"northNodeTropical":{"type":"number"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","northNodeTropical","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/draconic/today":{"get":{"tags":["Positions"],"summary":"Get today's draconic positions","description":"Shorthand endpoint for current draconic planetary positions.","parameters":[{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Today's draconic positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"northNodeTropical":{"type":"number"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","northNodeTropical","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/draconic/ephemeris":{"get":{"tags":["Positions"],"summary":"Get draconic ephemeris for date range","description":"Returns draconic planetary positions for each day in the specified date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Draconic ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"ephemeris":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"northNodeTropical":{"type":"number"},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"position":{"type":"object","properties":{"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"degree":{"type":"number"},"minute":{"type":"number"},"isRetrograde":{"type":"boolean"}},"required":["longitude","sign","degree","minute","isRetrograde"]},"tropicalLongitude":{"type":"number"}},"required":["body","position","tropicalLongitude"]}}},"required":["date","northNodeTropical","positions"]}}},"required":["startDate","endDate","ephemeris"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/aspects":{"get":{"tags":["Aspects"],"summary":"Get planetary aspects","description":"Returns all active aspects (angular relationships) between planets for a given date.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","enum":["modern-western","traditional","vedic","tight"],"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","example":"modern-western"},"required":false,"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","name":"orbProfile","in":"query"},{"schema":{"type":"string","description":"Custom uniform orb in degrees (overrides profile defaults for all aspect types)","example":"8"},"required":false,"description":"Custom uniform orb in degrees (overrides profile defaults for all aspect types)","name":"orb","in":"query"}],"responses":{"200":{"description":"List of active aspects","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-11-26"},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}},"formatted":{"type":"array","items":{"type":"string"},"description":"Human-readable aspect descriptions"}},"required":["date","aspects","formatted"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/aspects/today":{"get":{"tags":["Aspects"],"summary":"Get today's aspects","description":"Shorthand endpoint for current planetary aspects.","responses":{"200":{"description":"Today's active aspects","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/Aspect"}},"formatted":{"type":"array","items":{"type":"string"}}},"required":["date","aspects","formatted"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/ingress/houses":{"get":{"tags":["Ingress"],"summary":"Find house cusp ingresses for Sun or Moon","description":"Detect when the Moon or Sun crosses house cusps at a given location.\n\nHouse cusps are location- and time-dependent — they rotate with the Earth,\ncompleting a full rotation roughly once per sidereal day (~23.93 hours).\nBoth the Moon and Sun cross all 12 cusps approximately once per day.\n\n**Range limits:** 7 days for Moon, 90 days for Sun.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","enum":["Sun","Moon"],"default":"Moon","description":"Celestial body to track (only Sun and Moon are supported)","example":"Moon"},"required":false,"description":"Celestial body to track (only Sun and Moon are supported)","name":"body","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus","description":"House system to use for cusp calculation","example":"Placidus"},"required":false,"description":"House system to use for cusp calculation","name":"houseSystem","in":"query"}],"responses":{"200":{"description":"List of house ingress events","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"houseSystem":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"count":{"type":"number"},"ingresses":{"type":"array","items":{"$ref":"#/components/schemas/HouseIngressEvent"}}},"required":["body","startDate","endDate","houseSystem","latitude","longitude","count","ingresses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/ingress/houses/angles":{"get":{"tags":["Ingress"],"summary":"Find angle crossings (ASC, MC, DESC, IC) for Sun or Moon","description":"Detect when the Moon or Sun crosses major angles at a given location.\n\nFilters house ingresses to only show crossings at the four angles:\n- **ASC** (Ascendant, house 1 cusp)\n- **IC** (Imum Coeli, house 4 cusp)\n- **DESC** (Descendant, house 7 cusp)\n- **MC** (Midheaven, house 10 cusp)\n\n**Range limits:** 7 days for Moon, 90 days for Sun.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","enum":["Sun","Moon"],"default":"Moon","description":"Celestial body to track (only Sun and Moon are supported)","example":"Moon"},"required":false,"description":"Celestial body to track (only Sun and Moon are supported)","name":"body","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus","description":"House system to use for cusp calculation","example":"Placidus"},"required":false,"description":"House system to use for cusp calculation","name":"houseSystem","in":"query"}],"responses":{"200":{"description":"List of angle crossing events","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"houseSystem":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"count":{"type":"number"},"ingresses":{"type":"array","items":{"$ref":"#/components/schemas/HouseIngressEvent"}}},"required":["body","startDate","endDate","houseSystem","latitude","longitude","count","ingresses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/ingress":{"get":{"tags":["Ingress"],"summary":"Get planetary ingresses within a date range","description":"Returns when planets enter new zodiac signs within the specified date range.\n\nAn ingress occurs when a planet crosses a sign boundary (0°, 30°, 60°, etc.).\nRetrograde planets can re-enter signs multiple times.\n\n**Note:** Searching for Moon ingresses across large date ranges can be slow as the Moon changes signs every ~2.5 days.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"List of ingress events","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"bodies":{"type":"array","items":{"type":"string"}},"count":{"type":"number"},"ingresses":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"signBoundary":{"type":"number"},"date":{"type":"string"},"timestamp":{"type":"string"},"isRetrograde":{"type":"boolean"},"direction":{"type":"string","enum":["direct","retrograde"]}},"required":["body","sign","signBoundary","date","timestamp","isRetrograde","direction"]}}},"required":["startDate","endDate","bodies","count","ingresses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/ingress/{body}":{"get":{"tags":["Ingress"],"summary":"Get ingresses for a specific body","description":"Returns when a specific planet enters new zodiac signs within the date range.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Celestial body name","example":"Mars"},"required":true,"description":"Celestial body name","name":"body","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of ingress events for the body","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"count":{"type":"number"},"ingresses":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"signBoundary":{"type":"number"},"date":{"type":"string"},"timestamp":{"type":"string"},"isRetrograde":{"type":"boolean"},"direction":{"type":"string","enum":["direct","retrograde"]}},"required":["body","sign","signBoundary","date","timestamp","isRetrograde","direction"]}}},"required":["body","startDate","endDate","count","ingresses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/ingress/{body}/next":{"get":{"tags":["Ingress"],"summary":"Get the next ingress for a body","description":"Returns when a specific planet will next enter a new zodiac sign.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Celestial body name","example":"Venus"},"required":true,"description":"Celestial body name","name":"body","in":"path"}],"responses":{"200":{"description":"Next ingress event","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"signBoundary":{"type":"number"},"date":{"type":"string"},"timestamp":{"type":"string"},"isRetrograde":{"type":"boolean"},"direction":{"type":"string","enum":["direct","retrograde"]}},"required":["body","sign","signBoundary","date","timestamp","isRetrograde","direction"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/phase":{"get":{"tags":["Moon"],"summary":"Get Moon phase","description":"Returns the current Moon phase, illumination percentage, and date.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Moon phase information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoonPhaseInfo"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/phases":{"get":{"tags":["Moon"],"summary":"Get Moon phases for a month","description":"Returns all major Moon phases (New, First Quarter, Full, Last Quarter) for a specified month.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Year (YYYY)","example":"2025"},"required":true,"description":"Year (YYYY)","name":"year","in":"query"},{"schema":{"type":"string","pattern":"^(1[0-2]|[1-9])$","description":"Month (1-12)","example":"11"},"required":true,"description":"Month (1-12)","name":"month","in":"query"}],"responses":{"200":{"description":"Moon phases for the month","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"phases":{"type":"array","items":{"$ref":"#/components/schemas/MoonPhaseInfo"}}},"required":["year","month","phases"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/next":{"get":{"tags":["Moon"],"summary":"Get next occurrence of a Moon phase","description":"Returns the date of the next occurrence of a specified Moon phase.","parameters":[{"schema":{"type":"string","enum":["New Moon","Waxing Crescent","First Quarter","Waxing Gibbous","Full Moon","Waning Gibbous","Last Quarter","Waning Crescent"],"description":"The Moon phase to find","example":"Full Moon"},"required":true,"description":"The Moon phase to find","name":"phase","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date for search (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Start date for search (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). Defaults to today.","name":"from","in":"query"}],"responses":{"200":{"description":"Next occurrence of the specified phase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoonPhaseInfo"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/today":{"get":{"tags":["Moon"],"summary":"Get today's Moon phase","description":"Shorthand endpoint for current Moon phase.","responses":{"200":{"description":"Today's Moon phase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoonPhaseInfo"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/voc":{"get":{"tags":["Moon"],"summary":"Get current Void-of-Course Moon status","description":"Check if the Moon is currently void-of-course.\n\nThe Moon is void-of-course when it has made its last major aspect (conjunction, sextile, square, trine, opposition) before leaving its current sign.\n\n**Planet Sets:**\n- `traditional`: Sun, Mercury, Venus, Mars, Jupiter, Saturn\n- `modern`: Adds Uranus, Neptune, Pluto (more restrictive, shorter VOC periods)","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["traditional","modern"],"default":"modern","description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","example":"modern"},"required":false,"description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","name":"planets","in":"query"}],"responses":{"200":{"description":"VOC status","content":{"application/json":{"schema":{"type":"object","properties":{"isVoc":{"type":"boolean"},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"moonLongitude":{"type":"number"},"vocStarted":{"type":"string"},"vocEnds":{"type":"string"},"nextVoc":{"type":"string"},"remainingMinutes":{"type":"number"}},"required":["isVoc","moonSign","moonLongitude"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/voc/periods":{"get":{"tags":["Moon"],"summary":"Get VOC periods within a date range","description":"Returns all void-of-course Moon periods within the specified date range.\n\nEach period includes when it starts (last aspect), when it ends (sign change), duration, and which aspect was last made.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["traditional","modern"],"default":"modern","description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","example":"modern"},"required":false,"description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","name":"planets","in":"query"}],"responses":{"200":{"description":"List of VOC periods","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"planetSet":{"type":"string","enum":["traditional","modern"]},"count":{"type":"number"},"periods":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"startTimestamp":{"type":"string"},"end":{"type":"string"},"endTimestamp":{"type":"string"},"durationMinutes":{"type":"number"},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"nextSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"lastAspect":{"type":"object","nullable":true,"properties":{"planet":{"type":"string"},"type":{"type":"string"}},"required":["planet","type"]}},"required":["start","startTimestamp","end","endTimestamp","durationMinutes","moonSign","nextSign","lastAspect"]}}},"required":["startDate","endDate","planetSet","count","periods"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/voc/next":{"get":{"tags":["Moon"],"summary":"Get the next VOC period","description":"Returns the next upcoming void-of-course Moon period.","parameters":[{"schema":{"type":"string","enum":["traditional","modern"],"default":"modern","description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","example":"modern"},"required":false,"description":"Planet set for VOC calculation. Traditional: Sun through Saturn. Modern: includes Uranus, Neptune, Pluto.","name":"planets","in":"query"}],"responses":{"200":{"description":"Next VOC period","content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string"},"startTimestamp":{"type":"string"},"end":{"type":"string"},"endTimestamp":{"type":"string"},"durationMinutes":{"type":"number"},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"nextSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"lastAspect":{"type":"object","nullable":true,"properties":{"planet":{"type":"string"},"type":{"type":"string"}},"required":["planet","type"]}},"required":["start","startTimestamp","end","endTimestamp","durationMinutes","moonSign","nextSign","lastAspect"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/daily":{"get":{"tags":["Horoscope"],"summary":"Get daily horoscope","description":"Returns structured daily horoscope data for the specified zodiac sign.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Leo"},"required":true,"description":"Zodiac sign","name":"sign","in":"query"},{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective (sun, moon, or rising)","example":"sun"},"required":false,"description":"Astrological perspective (sun, moon, or rising)","name":"perspective","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Daily horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Horoscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/weekly":{"get":{"tags":["Horoscope"],"summary":"Get weekly horoscope","description":"Returns structured weekly horoscope data with daily snapshots.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Leo"},"required":true,"description":"Zodiac sign","name":"sign","in":"query"},{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective (sun, moon, or rising)","example":"sun"},"required":false,"description":"Astrological perspective (sun, moon, or rising)","name":"perspective","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Weekly horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyHoroscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/all":{"get":{"tags":["Horoscope"],"summary":"Get all daily horoscopes","description":"Returns daily horoscopes for all 12 zodiac signs.","parameters":[{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective (sun, moon, or rising)","example":"sun"},"required":false,"description":"Astrological perspective (sun, moon, or rising)","name":"perspective","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"All daily horoscopes","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"horoscopes":{"type":"array","items":{"$ref":"#/components/schemas/Horoscope"}}},"required":["date","horoscopes"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/interpretation/aspect":{"get":{"tags":["Horoscope"],"summary":"Get aspect interpretation","description":"Returns an interpretation for a specific planetary aspect.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"First planet","example":"Venus"},"required":true,"description":"First planet","name":"planet1","in":"query"},{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"description":"Second planet","example":"Mars"},"required":true,"description":"Second planet","name":"planet2","in":"query"},{"schema":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"],"description":"Aspect type","example":"conjunction"},"required":true,"description":"Aspect type","name":"aspect","in":"query"}],"responses":{"200":{"description":"Aspect interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"aspect":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"]},"interpretation":{"type":"string"}},"required":["planet1","planet2","aspect","interpretation"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/events/retrogrades":{"get":{"tags":["Events"],"summary":"Get retrograde periods","description":"Returns retrograde periods including station dates and shadow periods for a celestial body within a date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","Ceres","Juno","Vesta","Pallas"],"description":"Celestial body to check for retrogrades","example":"Mercury"},"required":true,"description":"Celestial body to check for retrogrades","name":"body","in":"query"}],"responses":{"200":{"description":"List of retrograde periods","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"periods":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"shadowStart":{"type":"string"},"stationRetrograde":{"type":"string"},"stationDirect":{"type":"string"},"shadowEnd":{"type":"string"},"retrogradeStartLongitude":{"type":"number"},"retrogradeEndLongitude":{"type":"number"},"retrogradeStartSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"retrogradeEndSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["body","shadowStart","stationRetrograde","stationDirect","shadowEnd","retrogradeStartLongitude","retrogradeEndLongitude","retrogradeStartSign","retrogradeEndSign"]}}},"required":["body","startDate","endDate","periods"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/events/retrogrades/stations":{"get":{"tags":["Events"],"summary":"Get retrograde station dates","description":"Returns just the station dates (when planets turn retrograde or direct) without shadow period calculations.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","Ceres","Juno","Vesta","Pallas"],"description":"Celestial body to check for stations","example":"Mercury"},"required":true,"description":"Celestial body to check for stations","name":"body","in":"query"}],"responses":{"200":{"description":"List of station events","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"stations":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"type":{"type":"string","enum":["stationRetrograde","stationDirect"]},"date":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["body","type","date","longitude","sign"]}}},"required":["body","startDate","endDate","stations"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/events/retrogrades/current":{"get":{"tags":["Events"],"summary":"Get currently retrograde planets","description":"Returns all planets that are currently in retrograde motion.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of currently retrograde planets","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"retrogradeCount":{"type":"number"},"retrogrades":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["body","longitude","sign"]}}},"required":["date","retrogradeCount","retrogrades"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/events/retrogrades/check":{"get":{"tags":["Events"],"summary":"Check if a planet is retrograde","description":"Check whether a specific planet is in retrograde motion on a given date.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","Ceres","Juno","Vesta","Pallas"],"description":"Celestial body to check","example":"Mercury"},"required":true,"description":"Celestial body to check","name":"body","in":"query"}],"responses":{"200":{"description":"Retrograde status","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"date":{"type":"string"},"isRetrograde":{"type":"boolean"},"longitude":{"type":"number"},"sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["body","date","isRetrograde","longitude","sign"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/houses":{"get":{"tags":["Houses"],"summary":"Calculate house cusps","description":"Calculate astrological house cusps for a given time and location. Supports Placidus, Koch, Equal, and Whole Sign house systems.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"default":"Placidus","description":"House system to use","example":"Placidus"},"required":false,"description":"House system to use","name":"system","in":"query"}],"responses":{"200":{"description":"House calculation results","content":{"application/json":{"schema":{"type":"object","properties":{"system":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"]},"date":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"cusps":{"type":"array","items":{"$ref":"#/components/schemas/HouseCusp"}},"ascendant":{"type":"number","description":"Ascendant longitude in degrees","example":105.5},"ascendant_sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"midheaven":{"type":"number","description":"Midheaven (MC) longitude in degrees","example":15.3},"midheaven_sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"vertex":{"type":"number","description":"Vertex longitude in degrees","example":245.7},"vertex_sign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"warning":{"type":"string","description":"Warning message for high latitude calculations"}},"required":["system","date","latitude","longitude","cusps","ascendant","ascendant_sign","midheaven","midheaven_sign","vertex","vertex_sign"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/houses/systems":{"get":{"tags":["Houses"],"summary":"List available house systems","description":"Returns information about available house calculation systems.","responses":{"200":{"description":"List of house systems","content":{"application/json":{"schema":{"type":"object","properties":{"systems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"]},"description":{"type":"string"},"high_latitude_support":{"type":"boolean"}},"required":["name","description","high_latitude_support"]}}},"required":["systems"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/seasons":{"get":{"tags":["Seasons"],"summary":"Get equinoxes and solstices for a year","description":"Returns the exact dates and times of the four seasonal events (two equinoxes and two solstices) for a given year.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Year to calculate seasons for. Defaults to current year.","example":"2025"},"required":false,"description":"Year to calculate seasons for. Defaults to current year.","name":"year","in":"query"}],"responses":{"200":{"description":"Seasonal events for the year","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number"},"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","enum":["march_equinox","june_solstice","september_equinox","december_solstice"]},"name":{"type":"string"},"date":{"type":"string"},"timestamp":{"type":"string"},"seasonNorth":{"type":"string","enum":["spring","summer","autumn","winter"]},"seasonSouth":{"type":"string","enum":["autumn","winter","spring","summer"]}},"required":["event","name","date","timestamp","seasonNorth","seasonSouth"]}}},"required":["year","events"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/seasons/range":{"get":{"tags":["Seasons"],"summary":"Get seasons for a range of years","description":"Returns seasonal events for multiple consecutive years.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Starting year","example":"2025"},"required":true,"description":"Starting year","name":"startYear","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Ending year","example":"2030"},"required":true,"description":"Ending year","name":"endYear","in":"query"}],"responses":{"200":{"description":"Seasonal events for the year range","content":{"application/json":{"schema":{"type":"object","properties":{"startYear":{"type":"number"},"endYear":{"type":"number"},"years":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","enum":["march_equinox","june_solstice","september_equinox","december_solstice"]},"name":{"type":"string"},"date":{"type":"string"},"timestamp":{"type":"string"},"seasonNorth":{"type":"string","enum":["spring","summer","autumn","winter"]},"seasonSouth":{"type":"string","enum":["autumn","winter","spring","summer"]}},"required":["event","name","date","timestamp","seasonNorth","seasonSouth"]}}},"required":["year","events"]}}},"required":["startYear","endYear","years"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/seasons/next":{"get":{"tags":["Seasons"],"summary":"Get the next seasonal event","description":"Returns the next upcoming equinox or solstice from the current date.","responses":{"200":{"description":"Next seasonal event","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["march_equinox","june_solstice","september_equinox","december_solstice"]},"name":{"type":"string"},"date":{"type":"string"},"timestamp":{"type":"string"},"seasonNorth":{"type":"string","enum":["spring","summer","autumn","winter"]},"seasonSouth":{"type":"string","enum":["autumn","winter","spring","summer"]}},"required":["event","name","date","timestamp","seasonNorth","seasonSouth"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/seasons/current":{"get":{"tags":["Seasons"],"summary":"Get the current season","description":"Returns the current astronomical season for the specified hemisphere.","parameters":[{"schema":{"type":"string","enum":["north","south"],"default":"north","description":"Hemisphere to calculate season for. Defaults to north.","example":"north"},"required":false,"description":"Hemisphere to calculate season for. Defaults to north.","name":"hemisphere","in":"query"}],"responses":{"200":{"description":"Current season information","content":{"application/json":{"schema":{"type":"object","properties":{"hemisphere":{"type":"string","enum":["north","south"]},"season":{"type":"string","enum":["spring","summer","autumn","winter"]},"date":{"type":"string"}},"required":["hemisphere","season","date"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses":{"get":{"tags":["Eclipses"],"summary":"Get eclipses within a date range","description":"Returns all solar and lunar eclipses within the specified date range. For solar eclipses, note that visibility depends on geographic location.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["all","lunar","solar"],"default":"all","description":"Type of eclipses to return","example":"all"},"required":false,"description":"Type of eclipses to return","name":"type","in":"query"}],"responses":{"200":{"description":"List of eclipses","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"typeFilter":{"type":"string","enum":["all","lunar","solar"]},"count":{"type":"number"},"eclipses":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["lunar"]},"kind":{"type":"string","enum":["penumbral","partial","total"]},"date":{"type":"string"},"peakTime":{"type":"string"},"obscuration":{"type":"number"},"partialDurationMinutes":{"type":"number","nullable":true},"totalDurationMinutes":{"type":"number","nullable":true},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"moonLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","obscuration","partialDurationMinutes","totalDurationMinutes","moonSign","moonLongitude"]},{"type":"object","properties":{"type":{"type":"string","enum":["solar"]},"kind":{"type":"string","enum":["partial","annular","total","hybrid"]},"date":{"type":"string"},"peakTime":{"type":"string"},"magnitude":{"type":"number"},"sunSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"sunLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","magnitude","sunSign","sunLongitude"]}]}}},"required":["startDate","endDate","typeFilter","count","eclipses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/lunar":{"get":{"tags":["Eclipses"],"summary":"Get lunar eclipses within a date range","description":"Returns all lunar eclipses within the specified date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of lunar eclipses","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"count":{"type":"number"},"eclipses":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["lunar"]},"kind":{"type":"string","enum":["penumbral","partial","total"]},"date":{"type":"string"},"peakTime":{"type":"string"},"obscuration":{"type":"number"},"partialDurationMinutes":{"type":"number","nullable":true},"totalDurationMinutes":{"type":"number","nullable":true},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"moonLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","obscuration","partialDurationMinutes","totalDurationMinutes","moonSign","moonLongitude"]}}},"required":["startDate","endDate","count","eclipses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/solar":{"get":{"tags":["Eclipses"],"summary":"Get solar eclipses within a date range","description":"Returns all solar eclipses within the specified date range. Note: Visibility depends on geographic location.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of solar eclipses","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"count":{"type":"number"},"eclipses":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["solar"]},"kind":{"type":"string","enum":["partial","annular","total","hybrid"]},"date":{"type":"string"},"peakTime":{"type":"string"},"magnitude":{"type":"number"},"sunSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"sunLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","magnitude","sunSign","sunLongitude"]}}},"required":["startDate","endDate","count","eclipses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/next":{"get":{"tags":["Eclipses"],"summary":"Get the next eclipse","description":"Returns the next upcoming eclipse (lunar or solar, whichever comes first).","parameters":[{"schema":{"type":"string","enum":["any","lunar","solar"],"default":"any","description":"Type of eclipse to find","example":"any"},"required":false,"description":"Type of eclipse to find","name":"type","in":"query"}],"responses":{"200":{"description":"Next eclipse","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["lunar"]},"kind":{"type":"string","enum":["penumbral","partial","total"]},"date":{"type":"string"},"peakTime":{"type":"string"},"obscuration":{"type":"number"},"partialDurationMinutes":{"type":"number","nullable":true},"totalDurationMinutes":{"type":"number","nullable":true},"moonSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"moonLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","obscuration","partialDurationMinutes","totalDurationMinutes","moonSign","moonLongitude"]},{"type":"object","properties":{"type":{"type":"string","enum":["solar"]},"kind":{"type":"string","enum":["partial","annular","total","hybrid"]},"date":{"type":"string"},"peakTime":{"type":"string"},"magnitude":{"type":"number"},"sunSign":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"sunLongitude":{"type":"number"}},"required":["type","kind","date","peakTime","magnitude","sunSign","sunLongitude"]}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/local":{"get":{"tags":["Eclipses"],"summary":"Get local solar eclipse visibility","description":"Returns solar eclipses visible from a specific geographic location within a date range. Includes local obscuration, timing of phases, and Sun altitude at peak.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"List of locally visible solar eclipses","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"elevation":{"type":"number"},"count":{"type":"number"},"eclipses":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"peakTime":{"type":"string"},"peakAltitude":{"type":"number"},"obscuration":{"type":"number"},"partialBegin":{"type":"string"},"partialEnd":{"type":"string"},"totalBegin":{"type":"string"},"totalEnd":{"type":"string"}},"required":["kind","peakTime","peakAltitude","obscuration","partialBegin","partialEnd"]}}},"required":["startDate","endDate","latitude","longitude","elevation","count","eclipses"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/planetary-hours":{"get":{"tags":["Planetary Hours"],"summary":"Get planetary hours for a date and location","description":"Returns all 24 planetary hours for a given date and geographic location.\n\n**How Planetary Hours Work:**\n- The time from sunrise to sunset is divided into 12 equal \"day hours\"\n- The time from sunset to next sunrise is divided into 12 equal \"night hours\"\n- Hour lengths vary by season - they're longer in summer days and shorter in winter\n- Each hour is ruled by one of the 7 traditional planets in Chaldean order\n\n**Day Rulers:**\n- Sunday: Sun\n- Monday: Moon\n- Tuesday: Mars\n- Wednesday: Mercury\n- Thursday: Jupiter\n- Friday: Venus\n- Saturday: Saturn","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Observer latitude in degrees (-90 to 90)","example":"40.7128"},"required":true,"description":"Observer latitude in degrees (-90 to 90)","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in degrees (-180 to 180)","example":"-74.0060"},"required":true,"description":"Observer longitude in degrees (-180 to 180)","name":"longitude","in":"query"}],"responses":{"200":{"description":"Planetary hours for the day","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"sunrise":{"type":"string"},"sunset":{"type":"string"},"nextSunrise":{"type":"string"},"dayRuler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"dayHourLength":{"type":"number"},"nightHourLength":{"type":"number"},"hours":{"type":"array","items":{"type":"object","properties":{"hourNumber":{"type":"number"},"isDayHour":{"type":"boolean"},"ruler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"start":{"type":"string"},"startTimestamp":{"type":"string"},"end":{"type":"string"},"endTimestamp":{"type":"string"},"durationMinutes":{"type":"number"}},"required":["hourNumber","isDayHour","ruler","start","startTimestamp","end","endTimestamp","durationMinutes"]}}},"required":["date","location","sunrise","sunset","nextSunrise","dayRuler","dayHourLength","nightHourLength","hours"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/planetary-hours/current":{"get":{"tags":["Planetary Hours"],"summary":"Get the current planetary hour","description":"Returns the planetary hour that is currently in effect for the specified location.","parameters":[{"schema":{"type":"string","description":"Observer latitude in degrees (-90 to 90)","example":"40.7128"},"required":true,"description":"Observer latitude in degrees (-90 to 90)","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in degrees (-180 to 180)","example":"-74.0060"},"required":true,"description":"Observer longitude in degrees (-180 to 180)","name":"longitude","in":"query"}],"responses":{"200":{"description":"Current planetary hour","content":{"application/json":{"schema":{"type":"object","properties":{"hourNumber":{"type":"number"},"isDayHour":{"type":"boolean"},"ruler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"start":{"type":"string"},"startTimestamp":{"type":"string"},"end":{"type":"string"},"endTimestamp":{"type":"string"},"durationMinutes":{"type":"number"}},"required":["hourNumber","isDayHour","ruler","start","startTimestamp","end","endTimestamp","durationMinutes"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/planetary-hours/next/{ruler}":{"get":{"tags":["Planetary Hours"],"summary":"Get the next hour ruled by a specific planet","description":"Returns when the next planetary hour ruled by the specified planet will occur.","parameters":[{"schema":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"],"description":"Planet to find next hour for","example":"Venus"},"required":true,"description":"Planet to find next hour for","name":"ruler","in":"path"},{"schema":{"type":"string","description":"Observer latitude in degrees (-90 to 90)","example":"40.7128"},"required":true,"description":"Observer latitude in degrees (-90 to 90)","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in degrees (-180 to 180)","example":"-74.0060"},"required":true,"description":"Observer longitude in degrees (-180 to 180)","name":"longitude","in":"query"}],"responses":{"200":{"description":"Next hour ruled by the planet","content":{"application/json":{"schema":{"type":"object","properties":{"hourNumber":{"type":"number"},"isDayHour":{"type":"boolean"},"ruler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"start":{"type":"string"},"startTimestamp":{"type":"string"},"end":{"type":"string"},"endTimestamp":{"type":"string"},"durationMinutes":{"type":"number"}},"required":["hourNumber","isDayHour","ruler","start","startTimestamp","end","endTimestamp","durationMinutes"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/year/{year}":{"get":{"tags":["Chinese Calendar"],"summary":"Get Chinese year information","description":"Returns comprehensive Chinese lunar calendar information for a Gregorian year, including zodiac animal, element, sexagenary cycle, and Chinese New Year date.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Gregorian year (1900-2100)","example":"2025"},"required":true,"description":"Gregorian year (1900-2100)","name":"year","in":"path"}],"responses":{"200":{"description":"Chinese year information","content":{"application/json":{"schema":{"type":"object","properties":{"gregorianYear":{"type":"integer"},"chineseYear":{"type":"integer"},"sexagenaryCycle":{"type":"object","properties":{"yearInCycle":{"type":"integer","minimum":1,"maximum":60},"stem":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9},"chinese":{"type":"string"},"pinyin":{"type":"string"},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"polarity":{"type":"string","enum":["Yang","Yin"]}},"required":["index","chinese","pinyin","element","polarity"]},"branch":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":11},"chinese":{"type":"string"},"pinyin":{"type":"string"},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}},"required":["index","chinese","pinyin","animal"]},"combined":{"type":"string"},"combinedPinyin":{"type":"string"}},"required":["yearInCycle","stem","branch","combined","combinedPinyin"]},"zodiacAnimal":{"type":"object","properties":{"english":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"chinese":{"type":"string"},"pinyin":{"type":"string"},"characteristics":{"type":"array","items":{"type":"string"}},"compatibleWith":{"type":"array","items":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}},"incompatibleWith":{"type":"array","items":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}}},"required":["english","chinese","pinyin","characteristics","compatibleWith","incompatibleWith"]},"element":{"type":"object","properties":{"english":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"chinese":{"type":"string"},"pinyin":{"type":"string"}},"required":["english","chinese","pinyin"]},"polarity":{"type":"string","enum":["Yang","Yin"]},"newYear":{"type":"object","properties":{"date":{"type":"string"},"gregorianDate":{"type":"string"}},"required":["date","gregorianDate"]},"hasLeapMonth":{"type":"boolean"},"leapMonth":{"type":"integer","nullable":true,"minimum":1,"maximum":12},"totalDays":{"type":"integer"}},"required":["gregorianYear","chineseYear","sexagenaryCycle","zodiacAnimal","element","polarity","newYear","hasLeapMonth","leapMonth","totalDays"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/date/{date}":{"get":{"tags":["Chinese Calendar"],"summary":"Convert Gregorian date to Chinese lunar date","description":"Converts a Gregorian date to its Chinese lunar calendar equivalent, including the lunar month, day, zodiac animal, and element.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Gregorian date in YYYY-MM-DD format","example":"2025-06-15"},"required":true,"description":"Gregorian date in YYYY-MM-DD format","name":"date","in":"path"}],"responses":{"200":{"description":"Chinese date information","content":{"application/json":{"schema":{"type":"object","properties":{"gregorian":{"type":"string"},"lunar":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":30},"isLeapMonth":{"type":"boolean"},"monthName":{"type":"object","properties":{"chinese":{"type":"string"},"pinyin":{"type":"string"},"meaning":{"type":"string"}},"required":["chinese","pinyin"]},"dayName":{"type":"string"}},"required":["year","month","day","isLeapMonth","monthName","dayName"]},"zodiacAnimal":{"type":"object","properties":{"english":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"chinese":{"type":"string"}},"required":["english","chinese"]},"element":{"type":"object","properties":{"english":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"chinese":{"type":"string"}},"required":["english","chinese"]},"stemBranch":{"type":"object","properties":{"combined":{"type":"string"},"combinedPinyin":{"type":"string"}},"required":["combined","combinedPinyin"]}},"required":["gregorian","lunar","zodiacAnimal","element","stemBranch"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/today":{"get":{"tags":["Chinese Calendar"],"summary":"Get Chinese lunar date for today","description":"Returns today's date converted to the Chinese lunar calendar.","responses":{"200":{"description":"Chinese date information for today","content":{"application/json":{"schema":{"type":"object","properties":{"gregorian":{"type":"string"},"lunar":{"type":"object","properties":{"year":{"type":"integer"},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":30},"isLeapMonth":{"type":"boolean"},"monthName":{"type":"object","properties":{"chinese":{"type":"string"},"pinyin":{"type":"string"},"meaning":{"type":"string"}},"required":["chinese","pinyin"]},"dayName":{"type":"string"}},"required":["year","month","day","isLeapMonth","monthName","dayName"]},"zodiacAnimal":{"type":"object","properties":{"english":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"chinese":{"type":"string"}},"required":["english","chinese"]},"element":{"type":"object","properties":{"english":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"chinese":{"type":"string"}},"required":["english","chinese"]},"stemBranch":{"type":"object","properties":{"combined":{"type":"string"},"combinedPinyin":{"type":"string"}},"required":["combined","combinedPinyin"]}},"required":["gregorian","lunar","zodiacAnimal","element","stemBranch"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/new-year":{"get":{"tags":["Chinese Calendar"],"summary":"Get Chinese New Year dates","description":"Returns Chinese New Year dates for a range of years, including the zodiac animal and element for each year.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Starting year. Defaults to current year.","example":"2020"},"required":false,"description":"Starting year. Defaults to current year.","name":"startYear","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Ending year. Defaults to startYear + 10.","example":"2030"},"required":false,"description":"Ending year. Defaults to startYear + 10.","name":"endYear","in":"query"}],"responses":{"200":{"description":"Chinese New Year dates","content":{"application/json":{"schema":{"type":"object","properties":{"newYears":{"type":"array","items":{"type":"object","properties":{"gregorianYear":{"type":"integer"},"date":{"type":"string"},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]}},"required":["gregorianYear","date","animal","element"]}}},"required":["newYears"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/compatibility":{"get":{"tags":["Chinese Calendar"],"summary":"Calculate zodiac compatibility","description":"Calculates compatibility between two birth years based on Chinese zodiac animals and elements. Uses traditional six harmonies, six clashes, and three harmonies relationships.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"First birth year","example":"1988"},"required":true,"description":"First birth year","name":"year1","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Second birth year","example":"1990"},"required":true,"description":"Second birth year","name":"year2","in":"query"}],"responses":{"200":{"description":"Compatibility analysis","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"year":{"type":"integer"},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]}},"required":["year","animal","element"]},"person2":{"type":"object","properties":{"year":{"type":"integer"},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]}},"required":["year","animal","element"]},"compatibility":{"type":"object","properties":{"rating":{"type":"string","enum":["excellent","good","moderate","challenging","difficult"]},"score":{"type":"integer","minimum":0,"maximum":100},"summary":{"type":"string"},"strengths":{"type":"array","items":{"type":"string"}},"challenges":{"type":"array","items":{"type":"string"}}},"required":["rating","score","summary","strengths","challenges"]}},"required":["person1","person2","compatibility"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/months/{year}":{"get":{"tags":["Chinese Calendar"],"summary":"Get lunar months for a year","description":"Returns all lunar months for a Chinese year, including leap months if present. Each month includes start/end dates and the traditional Chinese name.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Gregorian year (1900-2100)","example":"2025"},"required":true,"description":"Gregorian year (1900-2100)","name":"year","in":"path"}],"responses":{"200":{"description":"Lunar months for the year","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"months":{"type":"array","items":{"type":"object","properties":{"monthNumber":{"type":"integer","minimum":1,"maximum":12},"isLeapMonth":{"type":"boolean"},"name":{"type":"object","properties":{"chinese":{"type":"string"},"pinyin":{"type":"string"},"meaning":{"type":"string"}},"required":["chinese","pinyin"]},"startDate":{"type":"string"},"endDate":{"type":"string"},"days":{"type":"integer","minimum":29,"maximum":30}},"required":["monthNumber","isLeapMonth","name","startDate","endDate","days"]}}},"required":["year","months"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chinese-calendar/current-year":{"get":{"tags":["Chinese Calendar"],"summary":"Get current Chinese year information","description":"Returns comprehensive Chinese lunar calendar information for the current year based on today's date.","responses":{"200":{"description":"Current Chinese year information","content":{"application/json":{"schema":{"type":"object","properties":{"gregorianYear":{"type":"integer"},"chineseYear":{"type":"integer"},"sexagenaryCycle":{"type":"object","properties":{"yearInCycle":{"type":"integer","minimum":1,"maximum":60},"stem":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9},"chinese":{"type":"string"},"pinyin":{"type":"string"},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"polarity":{"type":"string","enum":["Yang","Yin"]}},"required":["index","chinese","pinyin","element","polarity"]},"branch":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":11},"chinese":{"type":"string"},"pinyin":{"type":"string"},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}},"required":["index","chinese","pinyin","animal"]},"combined":{"type":"string"},"combinedPinyin":{"type":"string"}},"required":["yearInCycle","stem","branch","combined","combinedPinyin"]},"zodiacAnimal":{"type":"object","properties":{"english":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"chinese":{"type":"string"},"pinyin":{"type":"string"},"characteristics":{"type":"array","items":{"type":"string"}},"compatibleWith":{"type":"array","items":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}},"incompatibleWith":{"type":"array","items":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]}}},"required":["english","chinese","pinyin","characteristics","compatibleWith","incompatibleWith"]},"element":{"type":"object","properties":{"english":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"chinese":{"type":"string"},"pinyin":{"type":"string"}},"required":["english","chinese","pinyin"]},"polarity":{"type":"string","enum":["Yang","Yin"]},"newYear":{"type":"object","properties":{"date":{"type":"string"},"gregorianDate":{"type":"string"}},"required":["date","gregorianDate"]},"hasLeapMonth":{"type":"boolean"},"leapMonth":{"type":"integer","nullable":true,"minimum":1,"maximum":12},"totalDays":{"type":"integer"}},"required":["gregorianYear","chineseYear","sexagenaryCycle","zodiacAnimal","element","polarity","newYear","hasLeapMonth","leapMonth","totalDays"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/fixed-stars":{"get":{"tags":["Fixed Stars"],"summary":"Get all fixed star positions","description":"Returns positions of 50+ prominent fixed stars for a given date, with precession correction from J2000 epoch. Optionally includes rise/set/culmination times when observer location is provided.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Observer latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Observer latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in decimal degrees","example":"-74.006"},"required":false,"description":"Observer longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Fixed star positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"},"stars":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"constellation":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string"},"degree":{"type":"number"},"minute":{"type":"number"},"magnitude":{"type":"number"},"nature":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"rise":{"type":"string"},"set":{"type":"string"},"culmination":{"type":"string"},"isPermanentlyAboveHorizon":{"type":"boolean"},"isPermanentlyBelowHorizon":{"type":"boolean"}},"required":["name","constellation","longitude","sign","degree","minute","magnitude","nature","keywords"]}}},"required":["date","count","stars"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/fixed-stars/conjunctions":{"get":{"tags":["Fixed Stars"],"summary":"Find planet-star conjunctions","description":"Returns all conjunctions between specified celestial bodies and fixed stars within a given orb.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","description":"Maximum orb in degrees (default: 1)","example":"1"},"required":false,"description":"Maximum orb in degrees (default: 1)","name":"orb","in":"query"}],"responses":{"200":{"description":"Planet-star conjunctions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"orb":{"type":"number"},"conjunctions":{"type":"array","items":{"type":"object","properties":{"star":{"type":"string"},"body":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"]},"orb":{"type":"number"},"starLongitude":{"type":"number"},"bodyLongitude":{"type":"number"},"sign":{"type":"string"}},"required":["star","body","orb","starLongitude","bodyLongitude","sign"]}}},"required":["date","orb","conjunctions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/fixed-stars/{name}":{"get":{"tags":["Fixed Stars"],"summary":"Get a single fixed star by name","description":"Returns the position of a specific fixed star (case-insensitive name matching). Optionally includes rise/set/culmination times when observer location is provided.","parameters":[{"schema":{"type":"string","description":"Star name (case-insensitive)","example":"Regulus"},"required":true,"description":"Star name (case-insensitive)","name":"name","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Observer latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Observer latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Observer longitude in decimal degrees","example":"-74.006"},"required":false,"description":"Observer longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Star position","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"star":{"type":"object","properties":{"name":{"type":"string"},"constellation":{"type":"string"},"longitude":{"type":"number"},"sign":{"type":"string"},"degree":{"type":"number"},"minute":{"type":"number"},"magnitude":{"type":"number"},"nature":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"rise":{"type":"string"},"set":{"type":"string"},"culmination":{"type":"string"},"isPermanentlyAboveHorizon":{"type":"boolean"},"isPermanentlyBelowHorizon":{"type":"boolean"}},"required":["name","constellation","longitude","sign","degree","minute","magnitude","nature","keywords"]}},"required":["date","star"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/aspects/patterns":{"get":{"tags":["Aspects"],"summary":"Detect aspect patterns in a chart","description":"Detects geometric aspect patterns (Grand Trine, T-Square, Grand Cross, Yod, Kite, Mystic Rectangle, Stellium), classifies chart shape, and calculates hemispheric/quadrant emphasis when location is provided.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees (required for house-based analysis)","example":"40.7128"},"required":false,"description":"Latitude in decimal degrees (required for house-based analysis)","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees (required for house-based analysis)","example":"-74.0060"},"required":false,"description":"Longitude in decimal degrees (required for house-based analysis)","name":"longitude","in":"query"}],"responses":{"200":{"description":"Aspect patterns, chart shape, and optional hemispheric analysis","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-07-15"},"patterns":{"type":"array","items":{"$ref":"#/components/schemas/AspectPattern"}},"chartShape":{"$ref":"#/components/schemas/ChartShape"},"hemisphericEmphasis":{"$ref":"#/components/schemas/HemisphericEmphasis"},"quadrantEmphasis":{"$ref":"#/components/schemas/QuadrantEmphasis"}},"required":["date","patterns","chartShape"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/dignities":{"get":{"tags":["Dignities"],"summary":"Get dignity status for celestial bodies","description":"Returns essential dignity information for each requested celestial body at the given date, including primary dignity status and complete Lilly scoring.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Dignity data for requested bodies","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-07-15"},"dignities":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string"},"longitude":{"type":"number"},"degreeInSign":{"type":"number"},"primaryDignity":{"type":"object","properties":{"dignity":{"type":"string","enum":["domicile","exaltation","moolatrikona","triplicity","term","face","detriment","fall","peregrine"]},"score":{"type":"number"}},"required":["dignity","score"]},"scoring":{"type":"object","properties":{"totalScore":{"type":"number"},"dignities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["domicile","exaltation","moolatrikona","triplicity","term","face","detriment","fall","peregrine"]},"score":{"type":"number"}},"required":["type","score"]}}},"required":["totalScore","dignities"]}},"required":["body","sign","longitude","degreeInSign","primaryDignity","scoring"]}}},"required":["date","dignities"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/reference/dignities":{"get":{"tags":["Reference"],"summary":"Get complete dignity reference table","description":"Returns the complete traditional essential dignity table including domicile, exaltation, detriment, fall, triplicity, term (Egyptian bounds), and face/decan assignments for all 12 zodiac signs.","responses":{"200":{"description":"Complete dignity reference data","content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"},"signs":{"type":"array","items":{"type":"object","properties":{"sign":{"type":"string"},"domicile":{"type":"string"},"exaltation":{"type":"string","nullable":true},"detriment":{"type":"array","items":{"type":"string"}},"fall":{"type":"string","nullable":true},"element":{"type":"string"},"triplicityDay":{"type":"string"},"triplicityNight":{"type":"string"},"triplicityParticipating":{"type":"string"},"terms":{"type":"array","items":{"type":"object","properties":{"ruler":{"type":"string"},"startDegree":{"type":"number"},"endDegree":{"type":"number"}},"required":["ruler","startDegree","endDegree"]}},"faces":{"type":"array","items":{"type":"object","properties":{"decan":{"type":"number"},"ruler":{"type":"string"}},"required":["decan","ruler"]}}},"required":["sign","domicile","exaltation","detriment","fall","element","triplicityDay","triplicityNight","triplicityParticipating","terms","faces"]}}},"required":["description","signs"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/reference/planetary-joys":{"get":{"tags":["Reference"],"summary":"Get planetary joy assignments","description":"Returns the traditional planetary joy house assignments. Each classical planet has a house where it \"rejoices\" and expresses its nature most naturally.","responses":{"200":{"description":"Planetary joy data","content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"},"joys":{"type":"array","items":{"$ref":"#/components/schemas/PlanetaryJoy"}}},"required":["description","joys"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/planet-in-sign":{"get":{"tags":["Interpretations"],"summary":"Get planet-in-sign interpretation","description":"Returns a detailed interpretation for a celestial body placed in a zodiac sign, including summary, keywords, description, strengths, and challenges.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Sun"},"required":true,"name":"body","in":"query"},{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"example":"Aries"},"required":true,"name":"sign","in":"query"}],"responses":{"200":{"description":"Planet-in-sign interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanetInSignInterpretation"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/planet-in-house":{"get":{"tags":["Interpretations"],"summary":"Get planet-in-house interpretation","description":"Returns a detailed interpretation for a celestial body placed in a house, including summary, keywords, description, strengths, and challenges.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Moon"},"required":true,"name":"body","in":"query"},{"schema":{"type":"string","example":"4"},"required":true,"name":"house","in":"query"}],"responses":{"200":{"description":"Planet-in-house interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanetInHouseInterpretation"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/aspect":{"get":{"tags":["Interpretations"],"summary":"Get detailed aspect interpretation","description":"Returns a detailed interpretation for an aspect between two celestial bodies, including summary, description, and keywords.","parameters":[{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Venus"},"required":true,"name":"body1","in":"query"},{"schema":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","Chiron","NorthNode","SouthNode","NorthNodeMean","SouthNodeMean","Ceres","Juno","Vesta","Pallas","LilithMean","LilithTrue","Eris","Sedna","Makemake","Haumea","Quaoar","Ixion","Varuna","Hygiea","Astraea","Psyche","Eros","Sappho","Amor","Cupido","Hades","Zeus","Kronos","Apollon","Admetos","Vulkanus","Poseidon","Vertex","AntiVertex"],"example":"Mars"},"required":true,"name":"body2","in":"query"},{"schema":{"type":"string","enum":["conjunction","sextile","square","trine","opposition","quincunx","semiSextile","semiSquare","sesquiquadrate","quintile","biquintile"],"example":"conjunction"},"required":true,"name":"aspect","in":"query"}],"responses":{"200":{"description":"Aspect interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectInterpretationDetailed"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/house-meaning":{"get":{"tags":["Interpretations"],"summary":"Get house meaning","description":"Returns the meaning of a specific astrological house, including name, keywords, description, ruling sign, and ruling planet.","parameters":[{"schema":{"type":"string","example":"1"},"required":true,"name":"house","in":"query"}],"responses":{"200":{"description":"House meaning","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseMeaning"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/sabian-symbol":{"get":{"tags":["Interpretations"],"summary":"Get Sabian symbol","description":"Returns the Sabian symbol for a specific zodiac sign and degree (1-30). Degree 1 corresponds to 0:00-0:59, degree 30 to 29:00-29:59.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"example":"Aries"},"required":true,"name":"sign","in":"query"},{"schema":{"type":"string","example":"1"},"required":true,"name":"degree","in":"query"}],"responses":{"200":{"description":"Sabian symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SabianSymbol"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":404,"message":"Resource not found","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/interpretation/decan":{"get":{"tags":["Interpretations"],"summary":"Get decan information","description":"Returns decan information from an ecliptic longitude (0-360) or a sign and degree. Includes Chaldean ruler, triplicity ruler, and description.","parameters":[{"schema":{"type":"string","example":"15.5"},"required":false,"name":"longitude","in":"query"},{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"example":"Aries"},"required":false,"name":"sign","in":"query"},{"schema":{"type":"string","example":"15"},"required":false,"name":"degree","in":"query"}],"responses":{"200":{"description":"Decan information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecanInfo"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/natal":{"post":{"tags":["Natal Chart"],"summary":"Calculate a natal chart","description":"Calculate a complete natal birth chart including positions, houses, aspects, element/modality balance, and chart ruler.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartRequest"}}}},"responses":{"200":{"description":"Complete natal chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/nakshatra/moon":{"get":{"tags":["Vedic"],"summary":"Get Moon's nakshatra","description":"Returns the Moon's nakshatra, pada, ruler, and other details for a given date using sidereal coordinates.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"}],"responses":{"200":{"description":"Moon's nakshatra information","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"moonLongitude":{"type":"object","properties":{"tropical":{"type":"number"},"sidereal":{"type":"number"}},"required":["tropical","sidereal"]},"nakshatra":{"$ref":"#/components/schemas/Nakshatra"}},"required":["date","ayanamsa","moonLongitude","nakshatra"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/nakshatra/compatibility":{"post":{"tags":["Vedic"],"summary":"Calculate Ashtakoot compatibility","description":"Calculates the Ashtakoot (eight-fold) compatibility score between two Moon positions. Provide the Moon's sidereal longitude for each person.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"moonLongitude1":{"type":"number","minimum":0,"maximum":360,"description":"First person's Moon sidereal longitude in degrees","example":45.5},"moonLongitude2":{"type":"number","minimum":0,"maximum":360,"description":"Second person's Moon sidereal longitude in degrees","example":180.3}},"required":["moonLongitude1","moonLongitude2"]}}}},"responses":{"200":{"description":"Ashtakoot compatibility score","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"$ref":"#/components/schemas/Nakshatra"},"person2":{"$ref":"#/components/schemas/Nakshatra"},"compatibility":{"$ref":"#/components/schemas/AshtakootScore"}},"required":["person1","person2","compatibility"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/dasha/vimshottari":{"get":{"tags":["Vedic"],"summary":"Get Vimshottari Dasha timeline","description":"Calculates the full Mahadasha timeline based on the Moon's position at birth. Provides all 9 major periods with sub-periods (Antardashas).","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Birth date in ISO format","example":"1990-01-15"},"required":true,"description":"Birth date in ISO format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Birth latitude in decimal degrees","example":"28.6139"},"required":true,"description":"Birth latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Birth longitude in decimal degrees","example":"77.2090"},"required":true,"description":"Birth longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system for sidereal calculation","name":"ayanamsa","in":"query"}],"responses":{"200":{"description":"Vimshottari Dasha timeline","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"moonLongitude":{"type":"object","properties":{"tropical":{"type":"number"},"sidereal":{"type":"number"}},"required":["tropical","sidereal"]},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"currentPeriod":{"type":"object","properties":{"mahadasha":{"type":"string"},"antardasha":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"}},"required":["mahadasha","antardasha","startDate","endDate"]},"periods":{"type":"array","items":{"$ref":"#/components/schemas/DashaPeriod"}}},"required":["birthDate","moonLongitude","ayanamsa","currentPeriod","periods"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/varga":{"get":{"tags":["Vedic"],"summary":"Get divisional chart positions","description":"Calculates planetary positions in a divisional (Varga) chart. Supported divisions: D7 (Saptamsa), D9 (Navamsa), D10 (Dashamsa), D12 (Dwadashamsa).","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"},{"schema":{"type":"string","description":"Chart division number (e.g., 9 for Navamsa)","example":"9"},"required":true,"description":"Chart division number (e.g., 9 for Navamsa)","name":"division","in":"query"}],"responses":{"200":{"description":"Divisional chart positions","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"division":{"type":"number"},"chartName":{"type":"string"},"ayanamsa":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"number"}},"required":["system","value"]},"positions":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string"},"sign":{"type":"string"},"degree":{"type":"number"}},"required":["body","sign","degree"]}}},"required":["date","division","chartName","ayanamsa","positions"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/vedic/aspects":{"get":{"tags":["Vedic"],"summary":"Get Vedic (Jyotish) aspects","description":"Calculates Vedic sign-based aspects (drishti) for the seven classical planets. All planets aspect the 7th sign; Mars additionally aspects 4th and 8th, Jupiter 5th and 9th, Saturn 3rd and 10th.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","enum":["lahiri","raman","krishnamurti","faganBradley","yukteshwar","jnBhasin","bvRaman","djwhalKhul","sassanian","galacticCenter0Sag","galacticCenterMidMula","hipparchos","ushashashi","trueChitrapaksha"],"default":"lahiri","description":"Ayanamsa system for sidereal calculation","example":"lahiri"},"required":false,"description":"Ayanamsa system for sidereal calculation","name":"ayanamsa","in":"query"},{"schema":{"type":"string","description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","example":"23.5"},"required":false,"description":"Custom ayanamsha offset in degrees. When provided, bypasses the named ayanamsa system.","name":"customAyanamsha","in":"query"}],"responses":{"200":{"description":"Vedic aspect results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VedicAspectResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/lots":{"get":{"tags":["Hellenistic"],"summary":"Calculate Arabic parts (lots)","description":"Returns Hellenistic lots including Fortune, Spirit, Eros, Necessity, Courage, Victory, and Nemesis for the given date and location.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole"],"description":"House system for ascendant calculation","example":"Whole"},"required":false,"description":"House system for ascendant calculation","name":"houseSystem","in":"query"},{"schema":{"type":"string","description":"When true, always use the day formula regardless of sect (some Hellenistic practitioners prefer this)","example":"false"},"required":false,"description":"When true, always use the day formula regardless of sect (some Hellenistic practitioners prefer this)","name":"alwaysUseDayFormula","in":"query"}],"responses":{"200":{"description":"Calculated lots","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"isDaySect":{"type":"boolean"},"ascendantLongitude":{"type":"number"},"lots":{"type":"array","items":{"$ref":"#/components/schemas/ArabicPart"}}},"required":["date","isDaySect","ascendantLongitude","lots"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/profections":{"get":{"tags":["Hellenistic"],"summary":"Calculate annual profections","description":"Returns the activated house, sign, and lord of the year for the given birth date and target date.","parameters":[{"schema":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"1990-06-15"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Target date for profection (defaults to today)","example":"2025-06-15"},"required":false,"description":"Target date for profection (defaults to today)","name":"targetDate","in":"query"},{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign on the ascendant at birth","example":"Aries"},"required":true,"description":"Zodiac sign on the ascendant at birth","name":"ascendantSign","in":"query"}],"responses":{"200":{"description":"Annual profection data","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"targetDate":{"type":"string"},"profection":{"$ref":"#/components/schemas/Profection"}},"required":["birthDate","targetDate","profection"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/zodiacal-releasing":{"get":{"tags":["Hellenistic"],"summary":"Calculate zodiacal releasing periods","description":"Returns zodiacal releasing time-lord periods from a given lot longitude. Typically starts from the Lot of Spirit (career) or Lot of Fortune (health).","parameters":[{"schema":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"1990-06-15"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"End date for period calculation (defaults to today)","example":"2025-06-15"},"required":false,"description":"End date for period calculation (defaults to today)","name":"targetDate","in":"query"},{"schema":{"type":"string","description":"Ecliptic longitude of the lot to release from (0-360)","example":"45.5"},"required":true,"description":"Ecliptic longitude of the lot to release from (0-360)","name":"lotLongitude","in":"query"},{"schema":{"type":"string","description":"Number of sub-period levels (1-4, default 2)","example":"2"},"required":false,"description":"Number of sub-period levels (1-4, default 2)","name":"levels","in":"query"}],"responses":{"200":{"description":"Zodiacal releasing periods","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"targetDate":{"type":"string"},"lotLongitude":{"type":"number"},"startingSign":{"type":"string"},"periods":{"type":"array","items":{"$ref":"#/components/schemas/ZodiacalReleasingPeriod"}}},"required":["birthDate","targetDate","lotLongitude","startingSign","periods"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/antiscia":{"get":{"tags":["Hellenistic"],"summary":"Calculate antiscia and contra-antiscia","description":"Returns antiscia (mirror across Cancer/Capricorn axis) and contra-antiscia (mirror across Aries/Libra axis) for all celestial bodies, plus any connections between them.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"}],"responses":{"200":{"description":"Antiscia data and connections","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"antiscia":{"type":"array","items":{"$ref":"#/components/schemas/Antiscia"}},"connections":{"type":"array","items":{"$ref":"#/components/schemas/AntisciaConnection"}}},"required":["date","antiscia","connections"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/temperament":{"get":{"tags":["Hellenistic"],"summary":"Analyze classical temperament","description":"Returns a classical four-temperament analysis (Sanguine, Choleric, Melancholic, Phlegmatic) based on the ascendant sign, Moon sign, solar season, and sect.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Temperament analysis","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"ascendantSign":{"type":"string"},"moonSign":{"type":"string"},"season":{"type":"string"},"sect":{"type":"string"},"temperament":{"$ref":"#/components/schemas/Temperament"}},"required":["date","ascendantSign","moonSign","season","sect","temperament"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/prenatal-lunation":{"get":{"tags":["Hellenistic"],"summary":"Find prenatal lunation","description":"Finds the most recent New Moon or Full Moon before the given birth date. This prenatal syzygy is significant in Hellenistic natal astrology.","parameters":[{"schema":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"2000-01-15"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"}],"responses":{"200":{"description":"Prenatal lunation data","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"prenatalLunation":{"$ref":"#/components/schemas/PrenatalLunation"}},"required":["birthDate","prenatalLunation"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/transits/natal":{"get":{"tags":["Transits"],"summary":"Get transits to natal chart","description":"Calculate current planetary transits aspecting natal chart positions.","parameters":[{"schema":{"type":"string","description":"Birth date YYYY-MM-DD","example":"1990-06-15"},"required":true,"description":"Birth date YYYY-MM-DD","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Birth time HH:MM (optional, defaults to noon UTC)","example":"14:30"},"required":false,"description":"Birth time HH:MM (optional, defaults to noon UTC)","name":"birthTime","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.006"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","description":"Transit date YYYY-MM-DD (defaults to today)","example":"2025-07-15"},"required":false,"description":"Transit date YYYY-MM-DD (defaults to today)","name":"transitDate","in":"query"},{"schema":{"type":"string","enum":["modern-western","traditional","vedic","tight"],"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","example":"modern-western"},"required":false,"description":"Named orb profile to use. Determines base orbs for each aspect type and planet modifiers. Options: modern-western (generous), traditional (moderate), vedic (tight, no planet modifiers), tight (very tight, research-grade).","name":"orbProfile","in":"query"}],"responses":{"200":{"description":"Transit aspects to natal chart","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"transitDate":{"type":"string"},"transits":{"type":"array","items":{"$ref":"#/components/schemas/TransitAspect"}}},"required":["birthDate","transitDate","transits"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/progressions":{"get":{"tags":["Chart Predictions"],"summary":"Calculate secondary progressed chart","description":"Calculates a secondary progressed chart using the day-for-a-year technique. Each day of planetary motion after birth represents one year of life.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Birth date in YYYY-MM-DD format","example":"2000-01-01"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Target date for progression (defaults to today)","example":"2030-01-01"},"required":false,"description":"Target date for progression (defaults to today)","name":"targetDate","in":"query"}],"responses":{"200":{"description":"Secondary progressed chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressedChart"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/solar-return":{"get":{"tags":["Chart Predictions"],"summary":"Calculate solar return chart","description":"Finds the exact moment the Sun returns to its natal position in a given year and casts a chart for that moment. Optionally includes house cusps if a location is provided.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Birth date in YYYY-MM-DD format","example":"2000-01-01"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Target year for the solar return (defaults to current year)","example":"2025"},"required":false,"description":"Target year for the solar return (defaults to current year)","name":"year","in":"query"},{"schema":{"type":"string","description":"Latitude for house calculation","example":"40.7128"},"required":false,"description":"Latitude for house calculation","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude for house calculation","example":"-74.0060"},"required":false,"description":"Longitude for house calculation","name":"longitude","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole","Campanus","Regiomontanus","Morinus","Porphyry","Alcabitius","Topocentric","Meridian","VehlowEqual","NaturalGraduation","Sripati"],"description":"House system to use (requires latitude and longitude)","example":"Placidus"},"required":false,"description":"House system to use (requires latitude and longitude)","name":"houseSystem","in":"query"}],"responses":{"200":{"description":"Solar return chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarReturn"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/lunar-return":{"get":{"tags":["Chart Predictions"],"summary":"Calculate lunar return chart","description":"Finds the exact moment the Moon returns to its natal position. The Moon completes a full cycle approximately every 27.3 days. Optionally find multiple consecutive returns.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Birth date in YYYY-MM-DD format","example":"2000-01-01"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start searching from this date (defaults to today)","example":"2025-01-01"},"required":false,"description":"Start searching from this date (defaults to today)","name":"fromDate","in":"query"},{"schema":{"type":"string","description":"Latitude for house calculation","example":"40.7128"},"required":false,"description":"Latitude for house calculation","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude for house calculation","example":"-74.0060"},"required":false,"description":"Longitude for house calculation","name":"longitude","in":"query"},{"schema":{"type":"string","description":"Number of consecutive lunar returns to find (1-13, default 1)","example":"1"},"required":false,"description":"Number of consecutive lunar returns to find (1-13, default 1)","name":"count","in":"query"}],"responses":{"200":{"description":"Lunar return chart(s)","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/LunarReturn"},{"type":"array","items":{"$ref":"#/components/schemas/LunarReturn"}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/solar-arc":{"get":{"tags":["Chart Predictions"],"summary":"Calculate solar arc directions","description":"Calculates solar arc directions by adding the progressed Sun arc to all natal positions. The arc equals the angular distance the progressed Sun has moved from its natal position.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Birth date in YYYY-MM-DD format","example":"2000-01-01"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Target date for directions (defaults to today)","example":"2030-01-01"},"required":false,"description":"Target date for directions (defaults to today)","name":"targetDate","in":"query"}],"responses":{"200":{"description":"Solar arc direction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarArc"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/synastry":{"post":{"tags":["Charts"],"summary":"Calculate synastry chart","description":"Calculate a synastry chart comparing two natal charts, including inter-aspects, house overlays, and compatibility scores.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynastryRequest"}}}},"responses":{"200":{"description":"Synastry chart data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynastryResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/composite":{"post":{"tags":["Charts"],"summary":"Calculate composite chart","description":"Calculate a composite (midpoint) chart representing the relationship between two people, including composite positions, aspects, and angles.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeRequest"}}}},"responses":{"200":{"description":"Composite chart data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/positions/declinations":{"get":{"tags":["Declinations"],"summary":"Get declinations for all celestial bodies","description":"Returns declination data for celestial bodies at a given date.\n\nDeclination is the angular distance north or south of the celestial equator.\nBodies with declination exceeding ~23.43° (the Sun's maximum) are considered\n\"out of bounds\" — associated with unconventional or amplified planetary expression.\n\nAlso includes parallel and contraparallel aspects (declination-based equivalents\nof conjunction and opposition) and the True (osculating) Lilith position.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of celestial bodies to include","example":"Sun,Moon,Mars"},"required":false,"description":"Comma-separated list of celestial bodies to include","name":"bodies","in":"query"},{"schema":{"type":"string","description":"Maximum orb in degrees for parallel/contraparallel aspects (default: 1)","example":"1"},"required":false,"description":"Maximum orb in degrees for parallel/contraparallel aspects (default: 1)","name":"orb","in":"query"}],"responses":{"200":{"description":"Declination data including positions, parallels, and out-of-bounds bodies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclinationsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/midpoints":{"get":{"tags":["Midpoints"],"summary":"Get all planetary midpoints","description":"Calculate all midpoints between the 10 main planetary bodies (Sun through Pluto). Returns 45 unique midpoint pairs with zodiac positions.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of all planetary midpoints","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"},"midpoints":{"type":"array","items":{"$ref":"#/components/schemas/Midpoint"}}},"required":["date","count","midpoints"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/midpoints/activations":{"get":{"tags":["Midpoints"],"summary":"Get active midpoint activations","description":"Find transiting planets that are conjunct, square, or opposed to planetary midpoints within the specified orb. This is a core technique in cosmobiology.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Maximum orb in degrees (default: 1.5)","example":"1.5"},"required":false,"description":"Maximum orb in degrees (default: 1.5)","name":"orb","in":"query"}],"responses":{"200":{"description":"List of midpoint activations","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"orb":{"type":"number"},"count":{"type":"number"},"activations":{"type":"array","items":{"$ref":"#/components/schemas/MidpointActivation"}}},"required":["date","orb","count","activations"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/midpoints/dial":{"get":{"tags":["Midpoints"],"summary":"Get 90-degree dial positions","description":"Calculate 90-degree dial positions for all main bodies. The 90-degree dial folds conjunctions, squares, and oppositions into the same visual space, making midpoint structures easier to identify.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"90-degree dial positions for all bodies","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"},"dial":{"type":"array","items":{"$ref":"#/components/schemas/MidpointDial"}}},"required":["date","count","dial"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/heliacal":{"get":{"tags":["Heliacal"],"summary":"Get heliacal events in a date range","description":"Find heliacal risings, heliacal settings, acronychal risings, and cosmical settings for the visible planets (Mercury through Saturn) within the specified date range and observer location.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"List of heliacal events","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"count":{"type":"number"},"events":{"type":"array","items":{"$ref":"#/components/schemas/HeliacalEvent"}}},"required":["startDate","endDate","count","events"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/heliacal/venus-phase":{"get":{"tags":["Heliacal"],"summary":"Get current Venus synodic phase","description":"Determine the current phase of the Venus synodic cycle: morning star, evening star, superior conjunction, inferior conjunction, or maximum elongation.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Venus synodic phase information","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"venus":{"$ref":"#/components/schemas/VenusCyclePhase"}},"required":["date","venus"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/chart/lots/extended":{"get":{"tags":["Hellenistic"],"summary":"Calculate extended Arabic parts (lots)","description":"Returns 18 extended lots beyond the core Hellenistic set, covering marriage, children, father, mother, illness, death, travel, vocation, commerce, friends, enemies, imprisonment, nobility, knowledge, love, property, inheritance, and surgery.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","enum":["Placidus","Koch","Equal","Whole"],"description":"House system for ascendant calculation","example":"Whole"},"required":false,"description":"House system for ascendant calculation","name":"houseSystem","in":"query"},{"schema":{"type":"string","description":"When true, always use the day formula regardless of sect (some Hellenistic practitioners prefer this)","example":"false"},"required":false,"description":"When true, always use the day formula regardless of sect (some Hellenistic practitioners prefer this)","name":"alwaysUseDayFormula","in":"query"}],"responses":{"200":{"description":"Calculated extended lots","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"isDaySect":{"type":"boolean"},"ascendantLongitude":{"type":"number"},"lots":{"type":"array","items":{"$ref":"#/components/schemas/ArabicPart"}}},"required":["date","isDaySect","ascendantLongitude","lots"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/natal-impact":{"get":{"tags":["Eclipses"],"summary":"Calculate eclipse impacts on a natal chart","description":"For each eclipse in the specified date range, determines which natal planets are closely aspected by the eclipse position and assigns a significance rating based on orb.","parameters":[{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":true,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":true,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"},{"schema":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"1990-06-15"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Birth time in HH:MM format (24h)","example":"14:30"},"required":false,"description":"Birth time in HH:MM format (24h)","name":"birthTime","in":"query"},{"schema":{"type":"string","description":"Start of eclipse search range in YYYY-MM-DD format","example":"2025-01-01"},"required":true,"description":"Start of eclipse search range in YYYY-MM-DD format","name":"startDate","in":"query"},{"schema":{"type":"string","description":"End of eclipse search range in YYYY-MM-DD format","example":"2025-12-31"},"required":true,"description":"End of eclipse search range in YYYY-MM-DD format","name":"endDate","in":"query"}],"responses":{"200":{"description":"Eclipse impacts on natal chart","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string"},"startDate":{"type":"string"},"endDate":{"type":"string"},"eclipseCount":{"type":"number"},"impacts":{"type":"array","items":{"$ref":"#/components/schemas/EclipseNatalImpact"}}},"required":["birthDate","startDate","endDate","eclipseCount","impacts"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/seasons":{"get":{"tags":["Eclipses"],"summary":"Find eclipse seasons in a date range","description":"Returns eclipse seasons (periods when the Sun is within 18.5 degrees of a lunar node, making eclipses possible) within the specified date range.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Start date in ISO format (YYYY-MM-DD)","example":"2025-11-01"},"required":true,"description":"Start date in ISO format (YYYY-MM-DD)","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"End date in ISO format (YYYY-MM-DD)","example":"2025-11-30"},"required":true,"description":"End date in ISO format (YYYY-MM-DD)","name":"endDate","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"List of eclipse seasons","content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"count":{"type":"number"},"seasons":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"ISO date when the eclipse season begins","example":"2025-03-11"},"end":{"type":"string","description":"ISO date when the eclipse season ends","example":"2025-04-15"},"midpoint":{"type":"string","description":"ISO date of closest Sun-Node approach","example":"2025-03-29"},"node":{"type":"string","enum":["north","south"],"description":"Which lunar node the Sun is near","example":"north"},"sunNodeSeparation":{"type":"number","description":"Angular distance between Sun and node at midpoint (degrees)","example":0.45}},"required":["start","end","midpoint","node","sunNodeSeparation"]}}},"required":["startDate","endDate","count","seasons"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/seasons/current":{"get":{"tags":["Eclipses"],"summary":"Get the current or next eclipse season","description":"Returns the eclipse season the given date falls within, or the next upcoming eclipse season if no season is currently active.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Current or next eclipse season","content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string","description":"ISO date when the eclipse season begins","example":"2025-03-11"},"end":{"type":"string","description":"ISO date when the eclipse season ends","example":"2025-04-15"},"midpoint":{"type":"string","description":"ISO date of closest Sun-Node approach","example":"2025-03-29"},"node":{"type":"string","enum":["north","south"],"description":"Which lunar node the Sun is near","example":"north"},"sunNodeSeparation":{"type":"number","description":"Angular distance between Sun and node at midpoint (degrees)","example":0.45}},"required":["start","end","midpoint","node","sunNodeSeparation"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/eclipses/seasons/nodal-cycle":{"get":{"tags":["Eclipses"],"summary":"Get nodal cycle position","description":"Returns the current position within the ~18.6-year nodal cycle, including the North Node longitude, cycle phase (0-1), and estimated completion date.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Nodal cycle position data","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","description":"ISO date for this calculation","example":"2025-06-15"},"northNodeLongitude":{"type":"number","description":"North Node's ecliptic longitude in degrees","example":345.67},"cyclePosition":{"type":"number","description":"Phase of the nodal cycle (0-1)","example":0.4523},"nextFullCycleDate":{"type":"string","description":"Approximate ISO date when the nodal cycle completes one revolution","example":"2043-12-15"}},"required":["date","northNodeLongitude","cyclePosition","nextFullCycleDate"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/calendar/retrogrades":{"get":{"tags":["Retrograde Calendar"],"summary":"Get annual retrograde calendar","description":"Returns all retrograde periods (with shadow phases) for major planets in a given year, sorted chronologically.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Year to generate retrograde calendar for","example":"2025"},"required":true,"description":"Year to generate retrograde calendar for","name":"year","in":"query"}],"responses":{"200":{"description":"Annual retrograde calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrogradeCalendarResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/almanac":{"get":{"tags":["Almanac"],"summary":"Get daily almanac","description":"Returns a daily astrological almanac including Moon phase, Moon sign, void-of-course status, retrograde planets, and a day highlight.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Daily almanac information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlmanacDay"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/moon/guidance":{"get":{"tags":["Lunar Guidance"],"summary":"Get lunar activity guidance","description":"Returns activity recommendations based on the current Moon sign, phase, and void-of-course status. When the Moon is void-of-course, recommendations shift to routine and rest activities.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"}],"responses":{"200":{"description":"Lunar activity guidance and recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LunarGuidance"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/compatibility/{sign1}/{sign2}":{"get":{"tags":["Compatibility"],"summary":"Get compatibility between two zodiac signs","description":"Returns a detailed compatibility analysis between two zodiac signs.\n\n**Scoring Factors:**\n- **Element Harmony** (40% weight): Same element = 10, compatible (Fire-Air, Earth-Water) = 7, challenging = 3\n- **Modality Interaction** (20% weight): Same modality = 5 (tension), different = 7 (complementary)\n- **Natural Aspect** (40% weight): Based on zodiac distance (conjunction=10, trine=9, sextile=8, etc.)\n\nThe overall score ranges from 0-100, where higher values indicate greater natural compatibility.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"First zodiac sign","example":"Aries"},"required":true,"description":"First zodiac sign","name":"sign1","in":"path"},{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Second zodiac sign","example":"Leo"},"required":true,"description":"Second zodiac sign","name":"sign2","in":"path"}],"responses":{"200":{"description":"Sign compatibility analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignCompatibility"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/electional":{"post":{"tags":["Electional"],"summary":"Find optimal times for an activity","description":"Electional astrology finds the most auspicious times to begin important activities.\n\n**Scoring Factors:**\n- **Moon Sign**: Certain Moon signs favor certain activities (e.g., Taurus Moon for financial matters)\n- **Moon Phase**: Waxing phases and New Moon favor new beginnings; waning phases less so\n- **Void-of-Course Moon**: Heavy penalty — avoid starting anything important during VOC\n- **Retrograde Planets**: Mercury retrograde penalizes contracts/communication; Venus retrograde penalizes weddings/creative work\n- **Planetary Hours**: Bonus when the midday planetary hour ruler matches the activity\n\nReturns the best and worst time windows within the specified date range (max 30 days).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectionalRequest"}}}},"responses":{"200":{"description":"Electional windows ranked by score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectionalResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/monthly":{"get":{"tags":["Horoscope"],"summary":"Get monthly horoscope","description":"Returns a monthly horoscope for the specified zodiac sign, including weekly breakdown, key dates, and moon phases.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Leo"},"required":true,"description":"Zodiac sign","name":"sign","in":"query"},{"schema":{"type":"string","description":"Year","example":"2026"},"required":true,"description":"Year","name":"year","in":"query"},{"schema":{"type":"string","description":"Month (1-12)","example":"3"},"required":true,"description":"Month (1-12)","name":"month","in":"query"},{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective (sun, moon, or rising)","example":"sun"},"required":false,"description":"Astrological perspective (sun, moon, or rising)","name":"perspective","in":"query"}],"responses":{"200":{"description":"Monthly horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlyHoroscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/yearly":{"get":{"tags":["Horoscope"],"summary":"Get yearly horoscope","description":"Returns a yearly horoscope for the specified zodiac sign, including quarterly breakdown, eclipses, and retrograde periods.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Leo"},"required":true,"description":"Zodiac sign","name":"sign","in":"query"},{"schema":{"type":"string","description":"Year","example":"2026"},"required":true,"description":"Year","name":"year","in":"query"},{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective (sun, moon, or rising)","example":"sun"},"required":false,"description":"Astrological perspective (sun, moon, or rising)","name":"perspective","in":"query"}],"responses":{"200":{"description":"Yearly horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YearlyHoroscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/personalized":{"get":{"tags":["Horoscope"],"summary":"Get personalized horoscope","description":"Returns a personalized horoscope based on birth data and current transit positions against the natal chart.","parameters":[{"schema":{"type":"string","description":"Birth date in YYYY-MM-DD format","example":"1990-06-15"},"required":true,"description":"Birth date in YYYY-MM-DD format","name":"birthDate","in":"query"},{"schema":{"type":"string","description":"Birth time in HH:MM format (24h)","example":"14:30"},"required":false,"description":"Birth time in HH:MM format (24h)","name":"birthTime","in":"query"},{"schema":{"type":"string","description":"Birth location latitude","example":"40.7128"},"required":true,"description":"Birth location latitude","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Birth location longitude","example":"-74.0060"},"required":true,"description":"Birth location longitude","name":"longitude","in":"query"},{"schema":{"type":"string","description":"Transit date in YYYY-MM-DD format (defaults to today)","example":"2026-03-17"},"required":false,"description":"Transit date in YYYY-MM-DD format (defaults to today)","name":"date","in":"query"},{"schema":{"type":"string","enum":["sun","moon","rising"],"description":"Astrological perspective","example":"sun"},"required":false,"description":"Astrological perspective","name":"perspective","in":"query"}],"responses":{"200":{"description":"Personalized horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalizedHoroscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/horoscope/dynamic":{"get":{"tags":["Horoscope"],"summary":"Get dynamic horoscope","description":"Returns a dynamically generated horoscope based on real-time planetary transits, sign ruler position, and aspects.","parameters":[{"schema":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac sign","example":"Leo"},"required":true,"description":"Zodiac sign","name":"sign","in":"query"},{"schema":{"type":"string","description":"Date in YYYY-MM-DD format (defaults to today)","example":"2026-03-17"},"required":false,"description":"Date in YYYY-MM-DD format (defaults to today)","name":"date","in":"query"}],"responses":{"200":{"description":"Dynamic horoscope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicHoroscope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/kp/chart":{"get":{"tags":["KP (Krishnamurti Paddhati)"],"summary":"Get full KP chart","description":"Returns a full Krishnamurti Paddhati chart with planetary positions, Placidus house cusps, significators, and ruling planets using the Krishnamurti ayanamsha.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":false,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"Full KP chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KpChartResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/kp/sublord":{"get":{"tags":["KP (Krishnamurti Paddhati)"],"summary":"Look up KP sub-lord for a degree","description":"Returns the KP sub-lord entry for a given sidereal longitude (0-360 degrees).","parameters":[{"schema":{"type":"string","description":"Sidereal longitude in degrees (0-360)","example":"45.5"},"required":true,"description":"Sidereal longitude in degrees (0-360)","name":"longitude","in":"query"}],"responses":{"200":{"description":"Sub-lord entry","content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"number"},"startDegree":{"type":"number"},"endDegree":{"type":"number"},"sign":{"type":"string"},"signLord":{"type":"string"},"nakshatraIndex":{"type":"number"},"nakshatraName":{"type":"string"},"nakshatraLord":{"type":"string"},"subLord":{"type":"string"}},"required":["index","startDegree","endDegree","sign","signLord","nakshatraIndex","nakshatraName","nakshatraLord","subLord"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/kp/ruling-planets":{"get":{"tags":["KP (Krishnamurti Paddhati)"],"summary":"Get KP ruling planets","description":"Returns the ruling planets for the given date and location: day lord, Moon sign/star/sub lords, and Ascendant sign/star/sub lords.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":false,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"KP ruling planets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KpRulingPlanets"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/kp/horary":{"get":{"tags":["KP (Krishnamurti Paddhati)"],"summary":"Get KP horary chart","description":"Creates a KP horary chart based on a number from 1 to 249. The number maps to a sub-lord division of the zodiac.","parameters":[{"schema":{"type":"string","description":"Horary number (1-249)","example":"42"},"required":true,"description":"Horary number (1-249)","name":"number","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":false,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"KP horary chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KpHoraryResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}},"/api/v1/kp/significators":{"get":{"tags":["KP (Krishnamurti Paddhati)"],"summary":"Get KP significators","description":"Returns the KP significators for all planets in the chart, showing house occupation, star lord, sub-lord, and houses signified.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:?\\d{2}))?$","description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","example":"2025-11-26"},"required":false,"description":"Date in ISO format (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:MM:SSZ or with offset). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","example":"America/New_York"},"required":false,"description":"IANA timezone name (e.g., America/New_York). Used with date-only values to resolve local time.","name":"timezone","in":"query"},{"schema":{"type":"string","description":"Latitude in decimal degrees","example":"40.7128"},"required":false,"description":"Latitude in decimal degrees","name":"latitude","in":"query"},{"schema":{"type":"string","description":"Longitude in decimal degrees","example":"-74.0060"},"required":false,"description":"Longitude in decimal degrees","name":"longitude","in":"query"},{"schema":{"type":"string","default":0,"description":"Observer elevation in meters above sea level","example":"0"},"required":false,"description":"Observer elevation in meters above sea level","name":"elevation","in":"query"}],"responses":{"200":{"description":"KP significators","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"significators":{"type":"array","items":{"$ref":"#/components/schemas/KpSignificator"}}},"required":["date","significators"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":400,"message":"Validation error","requestId":"req-xxx"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":401,"message":"Missing or invalid API key","requestId":"req-xxx"}}}}}},"429":{"description":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":429,"message":"Rate limit exceeded. Includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.","requestId":"req-xxx"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["status","message","requestId"]}},"required":["error"],"example":{"error":{"status":500,"message":"Internal server error","requestId":"req-xxx"}}}}}}}}}}}