{"api":"Astrolib API","version":"0.1.0","description":"Astrological chart calculation API. Returns canonical JSON optimised for LLM consumption. Every endpoint accepts optional *filters* to limit the response to only the sections you need.","utility_endpoints":[{"endpoint":"GET /","description":"API info — name, version, quick links"},{"endpoint":"GET /discovery","description":"This guide — all endpoints, filters, presets"},{"endpoint":"GET /health","description":"Health check"},{"endpoint":"GET /docs","description":"Interactive Swagger UI"},{"endpoint":"GET /openapi.json","description":"OpenAPI 3.1 specification"},{"endpoint":"GET /api/tools","description":"OpenAI function/tool definitions"},{"endpoint":"GET /api/tools/summary","description":"Compact tool summary by category"}],"chart_endpoints":[{"endpoint":"POST /charts/natal","description":"Birth chart — personality, life patterns, potential","required":["birth_date","location"],"optional":["birth_time"]},{"endpoint":"POST /charts/transit","description":"Transit chart — where the planets are right now (or at a given date)","required":["transit_date","location"],"optional":["transit_time"]},{"endpoint":"POST /charts/natal-transit","description":"Transits TO a natal chart — bi-wheel with natal (inner) and current transits (outer). USE THIS when the user asks 'what are my transits', 'how do current planets affect my chart', or any question about transits in relation to a birth chart.","required":["birth_date","location"],"optional":["birth_time","transit_date","transit_time","transit_location"]},{"endpoint":"POST /charts/progression","description":"Secondary progression — inner psychological development (1 day = 1 year)","required":["birth_date","birth_location"],"optional":["birth_time","progression_date","progression_location"]},{"endpoint":"POST /charts/solar-arc","description":"Solar arc directions — predictive technique, Sun's arc moves all planets","required":["birth_date","birth_location"],"optional":["birth_time","arc_date"]},{"endpoint":"POST /charts/solar-return","description":"Solar return — chart for the year ahead (Sun returns to natal position)","required":["birth_date","birth_location"],"optional":["birth_time","current_location","period","return_date"]},{"endpoint":"POST /charts/lunar-return","description":"Lunar return — chart for the month ahead (Moon returns to natal position)","required":["birth_date","birth_location"],"optional":["birth_time","current_location","period","return_year","return_month"]},{"endpoint":"POST /charts/synastry","description":"Synastry — inter-chart aspects between two people (compatibility). Renders a bi-wheel with person 1 (inner) and person 2 (outer).","required":["person1_birth_date","person1_location","person2_birth_date","person2_location"],"optional":["person1_name","person2_name","person1_birth_time","person2_birth_time"]},{"endpoint":"POST /charts/composite","description":"Composite — midpoint chart representing the relationship itself","required":["person1_birth_date","person1_location","person2_birth_date","person2_location"],"optional":["person1_name","person2_name","person1_birth_time","person2_birth_time"]},{"endpoint":"POST /charts/harmonic","description":"Harmonic chart — multiply all longitudes to reveal hidden patterns","required":["birth_date","birth_location"],"optional":["birth_time","harmonic (default 4)"]},{"endpoint":"POST /charts/event","description":"Event chart — electional or mundane astrology for a specific moment","required":["event_date","location"],"optional":["event_time","event_name"]},{"endpoint":"POST /charts/firdaria","description":"Firdaria — ancient Persian planetary period timing technique","required":["birth_date","location"],"optional":["birth_time","is_day_birth"]},{"endpoint":"POST /charts/lunar-mansions","description":"Lunar mansions (manzils) — 28 divisions of the zodiac, Arabic tradition","required":["birth_date","location"],"optional":["birth_time"]},{"endpoint":"POST /charts/fixed-stars","description":"Fixed-star positions and contacts to natal planets","required":["birth_date","location"],"optional":["birth_time","options.fixed_stars_magnitude_limit","options.fixed_stars_orb_limit"]},{"endpoint":"POST /charts/arabic-parts","description":"Arabic Parts / Lots such as Fortune, Spirit, Eros, Marriage, and more","required":["birth_date","location"],"optional":["birth_time","calculate_all_parts"]},{"endpoint":"POST /charts/aspect-timeline","description":"Timeline of transit aspects, optionally transits to a natal chart","required":["start_date","location"],"optional":["end_date","months","weeks","birth_date","birth_time","birth_location"]}],"output_sections":{"meta":{"description":"Chart type, datetime, location, house system, diurnal/nocturnal","always_present":true,"approx_chars":300},"planets":{"description":"Planetary positions — longitude, sign, degree, minute, house, speed, retrograde","approx_chars":2500},"houses":{"description":"House cusps — sign, degree, longitude for all 12 houses","approx_chars":1200},"distributions":{"description":"Element/quality/polarity balance — dominant element, quality, polarity, balance score","approx_chars":2500},"essential_dignities":{"description":"Planet strength by zodiac sign — domicile, exaltation, detriment, fall, scores","approx_chars":4600},"accidental_dignities":{"description":"Planet strength by house position — angular/succedent/cadent, aspects, scores","approx_chars":8200},"dispositors":{"description":"Dispositor chains — which planet rules which, final dispositors","approx_chars":1900},"receptions":{"description":"Mutual and one-way receptions between planets","approx_chars":1200},"aspects":{"description":"All aspects — planet pair, type, angle, orb, applying/separating, quality","approx_chars":20000,"note":"Use aspects_filter='major' or planets filter to reduce size significantly"},"patterns":{"description":"Geometric patterns — Grand Trine, T-Square, Grand Cross, Stellium, etc.","approx_chars":500},"traditional_configurations":{"description":"Traditional configurations — besiegement, cazimi, combust, etc.","approx_chars":1000},"arabic_parts":{"description":"Arabic Parts (Lots) — Part of Fortune, Part of Spirit, and others","approx_chars":500},"almuten":{"description":"Almuten figuris — strongest planet at key chart points (ASC, MC, Sun, Moon)","approx_chars":400},"void_of_course_moon":{"description":"Whether the Moon is void of course and its next aspect","approx_chars":100},"fixed_stars":{"description":"Fixed star positions and their conjunctions to planets","approx_chars":5000},"firdaria":{"description":"Firdaria planetary periods with start/end dates and current period","approx_chars":8000,"note":"Only populated when chart type is Firdaria or firdaria was computed"},"lunar_mansions":{"description":"Moon's lunar mansion with Arabic name and analysis","approx_chars":500,"note":"Only populated when chart type is Lunar Mansions"}},"planet_groups":{"TRADITIONAL":["SUN","MOON","MERCURY","VENUS","MARS","JUPITER","SATURN"],"MODERN":["SUN","MOON","MERCURY","VENUS","MARS","JUPITER","SATURN","URANUS","NEPTUNE","PLUTO"],"ANGLES":["ASC","MC"],"ALL":["SUN","MOON","MERCURY","VENUS","MARS","JUPITER","SATURN","URANUS","NEPTUNE","PLUTO","NORTH_NODE","SOUTH_NODE","CHIRON","CERES","PALLAS","JUNO","VESTA","LILITH","ASC","MC","VERTEX"]},"aspects_filters":{"major":"Only the big 5: conjunction (0°), opposition (180°), trine (120°), square (90°), sextile (60°)","applying":"Only aspects that are forming (planets getting closer — future influence)","major_applying":"Major aspects that are forming — the most important upcoming influences"},"house_systems":{"P":"Placidus (most common Western)","K":"Koch","E":"Equal houses","W":"Whole Sign (traditional / Hellenistic)","C":"Campanus","R":"Regiomontanus (horary)"},"calculation_systems":{"traditional":"Classical Western — Ptolemaic aspects, traditional dignities","modern":"Modern Western — includes minor aspects, modern rulerships","vedic":"Jyotish — sidereal zodiac, Vedic aspects and dignities"},"recommended_presets":{"quick_personality":{"description":"Fast personality overview — minimal context, good first call","endpoint":"POST /charts/natal","filters":{"include":["planets","houses","aspects"],"planets":["SUN","MOON","MERCURY","VENUS","MARS","JUPITER","SATURN","ASC","MC"],"aspects_filter":"major"},"approx_chars":5000},"full_traditional":{"description":"Complete traditional analysis — everything except niche sections","endpoint":"POST /charts/natal","filters":{"exclude":["firdaria","lunar_mansions","fixed_stars"]},"approx_chars":45000},"timing_focus":{"description":"For transit/progression timing questions — what's active now","endpoint":"POST /charts/transit","filters":{"include":["planets","aspects","void_of_course_moon"],"aspects_filter":"applying"},"approx_chars":12000},"dignity_analysis":{"description":"Planet strength assessment — who's strong, who's weak","endpoint":"POST /charts/natal","filters":{"include":["planets","essential_dignities","accidental_dignities","almuten","dispositors","receptions"]},"approx_chars":18000},"relationship_quick":{"description":"Quick compatibility check — major aspects between two charts","endpoint":"POST /charts/synastry","filters":{"include":["planets","aspects"],"planets":["SUN","MOON","MERCURY","VENUS","MARS","JUPITER","SATURN","URANUS","NEPTUNE","PLUTO","ASC","MC"],"aspects_filter":"major"},"approx_chars":6000},"aspect_timeline":{"description":"Grouped timing report for upcoming transit periods","endpoint":"POST /charts/aspect-timeline","body":{"start_date":"2026-02-01","months":3,"location":"New York, NY","aspect_filter":"major_only","output_format":"summary"},"approx_chars":8000}},"tips":["Start with 'quick_personality' preset for initial natal readings, then request more sections if needed.","Use the 'planets' filter to focus on traditional 7 (Sun–Saturn) — cuts aspect count by ~70%.","Request 'distributions' first to understand overall chart balance before diving into details.","For relationship questions use synastry (aspects between charts) or composite (midpoint chart).","Chart endpoints render a PNG by default. Set options.include_image=false for JSON-only calls.","The 'meta' section is always included regardless of filters.","Aspects with applying=true are forming (future), applying=false are separating (past).","For horary questions, use the event chart endpoint with Regiomontanus houses (house_system='R').","When birth time is unknown, omit birth_time — the chart uses noon and house positions become unreliable.","IMPORTANT — 'transits to my chart' vs 'transit chart': Use /charts/natal-transit when the user has birth data and wants to see how current planets affect them. Use /charts/transit only for a standalone sky-of-the-moment chart with no birth data."],"image_support":{"description":"A PNG chart-wheel image is generated by default for every chart endpoint that supports it. Set options.include_image=false to skip rendering when only JSON is needed.","response_field":"image_url — a public URL to the rendered chart wheel PNG.","display_hint":"Render in markdown: ![Person Name — Natal Chart](image_url)","no_image_support":["firdaria — data-only (planetary period timings)","lunar-mansions — data-only (mansion placements)"]}}