{"openapi":"3.1.0","info":{"title":"RoxyAPI","version":"2.0.0","description":"# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 12 domains (astrology, Vedic astrology, forecast, human design, numerology, tarot, biorhythm, I-Ching, crystals, dreams, angel numbers, location), 178+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (Remote MCP)\n\nRoxyAPI ships a Remote MCP server per product over Streamable HTTP, with no local setup and no Docker. Your AI agent auto-discovers all 178+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable — safe to switch on programmatically).\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 per month for 50K requests, up to 3M requests, with custom volume above that.\n\nSee [roxyapi.com/pricing](https://roxyapi.com/pricing)\n\n## Resources\n\n- [Quickstart guide](https://roxyapi.com/docs/quickstart) - first API call in 60 seconds\n- [Documentation](https://roxyapi.com/docs) - guides, tutorials, domain reference\n- [MCP setup](https://roxyapi.com/docs/mcp) - connect AI agents\n- [Starter apps](https://roxyapi.com/starters) - clone and deploy in 30 minutes\n- [FAQ](https://roxyapi.com/faq) - common questions\n- [Contact](https://roxyapi.com/contact) - support and API key recovery\n","contact":{"name":"RoxyAPI Support","url":"https://roxyapi.com/contact"},"license":{"name":"Proprietary","url":"https://roxyapi.com/policy/terms"}},"externalDocs":{"description":"Complete API Documentation with Examples","url":"https://roxyapi.com/docs"},"servers":[{"url":"/api/v2","description":"Production API v2"}],"security":[{"apiKey":[]}],"tags":[{"name":"Western Astrology","description":"Western astrology API for natal birth charts, daily, weekly, and monthly horoscopes with unique content per sign, synastry compatibility scores, composite charts, solar and lunar returns, real-time transit aspects, and moon phases. 4 house systems (Placidus, Koch, Whole Sign, Equal) with accurate tropical ephemeris, aspect-pattern detection (Grand Trine, T-Square, Yod), astrocartography planetary lines, relocation charts, and local space maps for location based astrology, plus classical and professional points like fixed star conjunctions, Arabic lots, the asteroid goddesses (Ceres, Pallas, Juno, Vesta), mean and true Black Moon Lilith, and timing techniques like secondary progressions, solar arc directions, and annual profections. Built for horoscope platforms, astrology dating apps, AI chatbots, wellness products, and zodiac content engines. Schedule future horoscopes with a date parameter for editorial workflows, no astronomy expertise needed. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Vedic Astrology","description":"Vedic astrology (Jyotish) and KP API for kundli generation with 15 divisional charts (D1-D60), Ashtakoot Gun Milan kundli matching, Vimshottari Dasha predictions, dosha detection with remedies, a 301-entry planetary yoga glossary with 48 of them chart-detected and evidenced, complete Panchang, and KP horary with 249-level sub-lord analysis. Calculations verified against NASA JPL Horizons at arc-second-level accuracy. Built for matrimonial apps, horoscope platforms, spiritual wellness services, and AI-powered astrology chatbots. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Forecast","description":"Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm critical days, and Vimshottari dasha changes into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over Remote MCP with typed SDKs. Horizon capped at 90 days."},{"name":"Human Design","description":"Generate the full Human Design bodygraph from a birth moment: type, strategy, inner authority, profile, definition, incarnation cross, the nine centers, defined channels, and all 26 gate activations, plus two-person connection charts and small-group Penta analysis. Planetary positions verified against NASA JPL Horizons, the Design side solved on the exact 88 degree solar arc. One key, Remote MCP, typed SDKs."},{"name":"Numerology","description":"Numerology API to calculate life path, expression, soul urge, personality, and maturity numbers, with Pinnacle and Challenge life-phase timing, Hidden Passion, Subconscious Self, and Cornerstone and Capstone name analysis. Birth day 1-31 profiles, lucky associations (colors, gemstones, planets), personal year and month forecasts, relationship compatibility, and karmic debt and lessons. Unicode-aware multilingual name handling transliterates Spanish, French, German, Russian, Hindi, Bengali, Tamil, Japanese, Chinese, Korean, Arabic, Greek, and Hebrew names to correct Pythagorean numbers so non-Latin scripts no longer drop letters. Both Pythagorean and Chaldean systems in one call, Cheiro compound numbers (10 to 52) with planetary rulers, and business and brand name analysis. Built for numerology apps, editorial platforms, AI chatbots, and wellness services. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Tarot","description":"Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and spiritual growth. Celtic Cross, three-card, love, career, yes/no oracle, daily card, and custom spreads, each with upright and reversed interpretations. Seeded reproducibility for personalized daily readings, and card images included. Built for tarot apps, AI tarot chatbots, fortune-telling platforms, and spiritual wellness products. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Biorhythm","description":"The most complete biorhythm API: 10 cycle types across 3 primary (physical, emotional, intellectual), 4 secondary (intuitive, aesthetic, awareness, spiritual), and 3 composite (passion, mastery, wisdom). Critical-day detection with severity classification, 90-day forecasts with best and worst days, two-person compatibility scoring, phase tracking for dashboards, and seeded daily readings for push notifications. 8 languages, deterministic results, and editorial-grade interpretations. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs. Ship a biorhythm feature in hours, not weeks."},{"name":"I-Ching","description":"I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making. Cast readings with the authentic three-coin method, get a daily hexagram, and explore the Book of Changes programmatically. Built for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Crystals and Healing Stones","description":"Crystal healing API covering the most popular and widely-searched healing crystals and gemstones, from Amethyst and Rose Quartz to Moldavite and Selenite, each with its spiritual, emotional, and physical properties. Filter by chakra (Root through Crown), zodiac sign, or element, search by keyword, browse birthstones by month, discover crystal pairings, and get random or daily crystal picks. Includes Mohs hardness, numerological vibration, and planetary associations per stone. Built for wellness apps, crystal shops, chakra-balancing tools, astrology integrations, and AI spiritual advisors. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Dreams","description":"Dream interpretation API with a 2,000+ symbol dream dictionary and psychological meanings covering animals, objects, emotions, people, scenarios, and abstract concepts. Decode dreams about falling, flying, teeth falling out, being chased, water, snakes, and more. Search, browse A-Z, or discover random symbols. Build dream journal apps, AI dream analysis chatbots, sleep-tracking features, and wellness platforms. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Angel Numbers","description":"Angel numbers API with meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 75+ sequences covering every common family. Each reading breaks down into spiritual, love, career, money, and twin flame guidance, plus a biblical perspective and an honest shadow reading. Smart lookup analyzes any number sequence with pattern detection, digit-root calculation, classification, and an optional sighting-context note. Daily angel number endpoint, and filter by type (repeating, sequential, mirror, master, compound). Built for synchronicity apps, spiritual journals, daily guidance features, AI chatbots, and wellness platforms. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Location and Timezone","description":"Location and timezone API with city search and geocoding across 235,000+ cities in 240+ countries, returning latitude, longitude, IANA timezone, and DST-aware UTC offset. Coverage goes down to towns of a few hundred people and every administrative seat, so a rural birthplace resolves as reliably as a capital. The location layer for birth chart forms, horoscope apps, event planners, and any feature that needs place-to-coordinates resolution. Fully offline dataset with no third party geocoding call, and fields that map directly to the astrology endpoints. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."},{"name":"Usage","description":"Monitor your API usage, check rate limits, and track request consumption. Get detailed usage breakdowns by endpoint, current month statistics, and recommendations for plan upgrades when approaching limits. Essential for managing API quotas and optimizing subscription plans."},{"name":"Languages","description":"List the response languages accepted by the `lang` query parameter on every i18n-aware endpoint. Use to populate language pickers, validate user input, or auto-detect available locales in agent integrations."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key for accessing RoxyAPI. Alternatively, you can pass the API key as a query parameter \"api_key\"."}},"schemas":{"NatalChartResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Birth date used for this chart (YYYY-MM-DD)."},"time":{"type":"string","example":"14:30:00","description":"Birth time used for this chart (HH:MM:SS, 24-hour)."},"latitude":{"type":"number","example":40.7128,"description":"Birth latitude in decimal degrees."},"longitude":{"type":"number","example":-74.006,"description":"Birth longitude in decimal degrees."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC in decimal hours."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details echoed back from the request. Confirms the input used for this chart calculation."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360)."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":22.45,"description":"Degree within the zodiac sign (0-29.999)."},"house":{"type":"number","example":7,"description":"House placement (1-12) based on the selected house system."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in retrograde motion."},"dignity":{"type":"string","enum":["domicile","exaltation","detriment","fall","peregrine"],"example":"domicile","description":"Essential dignity of this body in the sign it occupies: domicile (the sign it rules, its strongest placement), exaltation (honoured and amplified), detriment (opposite its rulership, where it struggles), fall (opposite its exaltation, where it is weakened), or peregrine (in none of its own dignity signs). Absent for the lunar nodes, Chiron and Black Moon Lilith, which rule no sign and therefore hold no dignity at all, so an absent field and peregrine are different answers. Derived by sign only, so triplicity, bounds and face are not considered. Always English, whatever the lang parameter says, so it stays safe to compare against in code. The four dignity signs behind it are published per body by GET /planet-meanings/{id}."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","description":"One-sentence interpretation of this planet in its sign and house placement.","example":"Your Sun in Cancer in The Seventh House reveals how you express self-awareness and ego in the realm of partnerships."},"detailed":{"type":"string","description":"Multi-sentence detailed interpretation with personality insights.","example":"Sun represents self-awareness and ego. In Cancer, this energy becomes nurturing, protective, emotionally intelligent..."},"keywords":{"type":"array","items":{"type":"string"},"description":"Key personality traits and themes for this placement.","example":["Nurturing","Protective","Emotional","Intuitive","Home-oriented"]}},"required":["summary","detailed","keywords"],"description":"Planet-in-sign-in-house interpretation. Narrative analysis of what this placement means in the natal chart."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, house placements, and interpretations."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12)."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps with zodiac positions. House cusps divide the chart into life areas."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Sun","description":"First planet in the aspect pair. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (growing stronger) or separating (fading)."},"strength":{"type":"number","example":75,"description":"Aspect strength percentage (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature: harmonious, challenging, or neutral. Always English, whatever the lang parameter says, because it is an identifier to compare and style on. Read aspectInterpretation for the sentence a reader sees."},"aspectInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Your Sun forms a very strong conjunction (0) with Jupiter, currently separating (weakening). This neutral aspect creates Planets and points that form a conjunction are energies that are united. They are blended; therefore...","description":"One-sentence read of THIS pair: which two bodies, how tight the aspect is, whether it is applying or separating, and how it is classified. Translated in place, so it arrives in the requested language."},"keywords":{"type":"array","items":{"type":"string"},"example":["blend","difficult","unite","united"],"description":"Themes this aspect activates between the two bodies. Translated in place, so they arrive in the requested language."}},"required":["summary","keywords"],"description":"Narrative interpretation of this aspect for this chart. The reference description of the aspect TYPE is not repeated per row, use GET or POST /astrology/aspects for that card."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","aspectInterpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and interpretation."},"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"Detected multi-planet aspect configurations (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium). Grand Cross suppresses contained T-Squares, Kite suppresses underlying Grand Trine."},"aspectsInterpretation":{"type":"object","properties":{"summary":{"type":"string","description":"Narrative summary of the overall aspect pattern in this chart.","example":"Your chart contains 15 aspects: 8 harmonious, 5 challenging, and 2 neutral. This creates a harmonious overall pattern."},"dominant":{"type":"string","example":"harmonious","description":"Whether the chart is predominantly harmonious, challenging, or balanced."},"harmonious":{"type":"number","example":8,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":5,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":2,"description":"Count of neutral aspects (conjunction)."}},"required":["summary","dominant","harmonious","challenging","neutral"],"description":"Aspect pattern analysis showing the balance of harmonious vs challenging energies in the chart."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on the Ascendant (rising sign). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","example":45.32,"description":"Absolute ecliptic longitude of the Ascendant (0-360)."}},"required":["sign","degree","longitude"],"description":"Ascendant (rising sign). The eastern horizon at birth, defining outward personality and physical appearance."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the Midheaven (MC). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Acuario","description":"Midheaven sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":8.76,"description":"Degree within the Midheaven sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude of the Midheaven (0-360)."}},"required":["sign","degree","longitude"],"description":"Midheaven (MC). The highest point of the ecliptic at birth, representing career direction and public image."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."},"signLocalized":{"type":"string","example":"Leo","description":"Part of Fortune sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"signLocalized":{"type":"string","example":"Cáncer","description":"Vertex sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."},"summary":{"type":"object","properties":{"dominantElement":{"type":"string","example":"Water","description":"Most represented element in the chart (Fire, Earth, Air, Water). Always English, whatever the lang parameter says. Use dominantElementLocalized for anything a reader sees."},"dominantElementLocalized":{"type":"string","example":"Agua","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dominantModality":{"type":"string","example":"Cardinal","description":"Most represented modality in the chart (Cardinal, Fixed, Mutable). Always English, whatever the lang parameter says. Use dominantModalityLocalized for anything a reader sees."},"dominantModalityLocalized":{"type":"string","example":"Cardinal","description":"Modality name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"retrogradePlanets":{"type":"array","items":{"type":"string"},"example":["Mercury","Saturn"],"description":"Planets in retrograde motion at the time of birth. Always English, whatever the lang parameter says. Use retrogradePlanetsLocalized for anything a reader sees."},"retrogradePlanetsLocalized":{"type":"array","items":{"type":"string"},"example":["Mercurio","Saturno"],"description":"The same retrograde bodies in the requested language, for display only. Index aligned with retrogradePlanets, so entry n of one names entry n of the other. Present only when lang is set to a language other than English, since in English it would repeat retrogradePlanets exactly."},"elementDistribution":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of planets placed in this element (Fire, Earth, Air, Water). Read the four counts together to spot an emphasis or a missing element."},"example":{"Fire":2,"Earth":3,"Air":1,"Water":4},"description":"Count of planets in each element. Shows elemental emphasis in the personality."},"modalityDistribution":{"type":"object","additionalProperties":{"type":"number","example":4,"description":"Number of planets placed in this modality (Cardinal, Fixed, Mutable). The largest count is the dominant operating mode."},"example":{"Cardinal":4,"Fixed":3,"Mutable":3},"description":"Count of planets in each modality. Shows the dominant operating mode."}},"required":["dominantElement","dominantModality","retrogradePlanets","elementDistribution","modalityDistribution"],"description":"Chart summary with dominant element, modality, retrograde planets, and distribution analysis."}},"required":["birthDetails","planets","houses","houseSystem","aspects","aspectsInterpretation","ascendant","midheaven","partOfFortune","vertex","summary"]},"NatalChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for dividing the chart into 12 houses. Placidus (default) is most popular in Western astrology and time-sensitive. Whole Sign assigns one sign per house (simpler, ancient). Equal houses divide chart into 30° segments from Ascendant. Koch emphasizes houses in high latitudes."}},"required":["date","time","latitude","longitude","timezone"]},"HousesResponse":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Input date used for this house cusp calculation."},"time":{"type":"string","example":"14:30:00","description":"Input time used for this house cusp calculation."},"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for horizon-based house calculations."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to this calculation."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for this calculation (placidus, whole-sign, equal, koch, or all)."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on the Ascendant (rising sign). Determines the first house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","example":45.32,"description":"Absolute ecliptic longitude of the Ascendant in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Ascendant (rising sign) position. The eastern horizon point at the moment of birth, defining personality expression and physical appearance in Western astrology."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the Midheaven (MC). Indicates career direction and public reputation."},"degree":{"type":"number","example":8.76,"description":"Degree within the Midheaven sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude of the Midheaven in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Midheaven (MC) position. The highest point of the ecliptic at birth, representing career aspirations and public image in natal astrology."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12). Each house governs specific life areas."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps with their zodiac positions. House cusps divide the chart into life areas: identity (1st), resources (2nd), communication (3rd), home (4th), creativity (5th), health (6th), partnerships (7th), transformation (8th), philosophy (9th), career (10th), community (11th), spirituality (12th)."},"comparison":{"type":"object","additionalProperties":{"type":"object","properties":{"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12). Each house governs specific life areas."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360), as this house system places it."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp in this house system."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps as this system computes them. Compare the same house number across the four keys to see how far the systems disagree, which is largest at high latitudes and for the intermediate cusps."}},"required":["houses"]},"description":"Side-by-side house cusp comparison across all four systems (Placidus, Whole Sign, Equal, Koch). Only included when houseSystem is set to \"all\". Useful for educational tools and system comparison."}},"required":["date","time","latitude","longitude","timezone","houseSystem","ascendant","midheaven","houses"]},"AspectsResponse":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Date used for this aspect calculation (YYYY-MM-DD)."},"time":{"type":"string","example":"14:30:00","description":"Time used for this calculation (HH:MM:SS)."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC in decimal hours."},"aspectsFound":{"type":"number","example":12,"description":"Total number of aspects found after any filters applied."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Sun","description":"First planet in the aspect pair. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle defining this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (growing stronger) or separating (fading)."},"strength":{"type":"number","example":75,"description":"Aspect strength (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature for this pair: harmonious, challenging, or neutral. Always English, whatever the lang parameter says, because it is an identifier to compare and style on. This is the field to branch on; meaning.nature is the reference card characterisation of the aspect type and is translated for display."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Trine","description":"Aspect display name."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Planets in trine support each other. Trines, by nature, are accepting. They allow us to accept others, ourselves, and situations. The talents that trines offer a native are so natural that they are almost unconscious.","description":"Brief aspect description."},"long":{"type":"string","example":"These talents are second nature and completely natural. So, for example, if a chart has Venus trine Neptune, the native may be poetic, romantic, or artistic, and may easily accept a romantic partner for who they are. With Venus square Neptune the same qualities exist, but expressing them takes conscious work rather than coming naturally.","description":"Detailed aspect description with astrological context."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"How this aspect type is characterised in its reference card, in the requested language, exactly like the name, description and keywords beside it. This is a property of the aspect TYPE, so branch on the aspect-level interpretation field instead, which is always English and is the classification applied to this particular pair."}},"required":["name","description","keywords","nature"],"description":"Aspect meaning with keywords, description, and nature classification."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All aspects found between the specified planets, with strength, orb, and interpretation."},"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"Detected multi-planet aspect configurations (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium)."},"summary":{"type":"object","properties":{"totalAspects":{"type":"number","example":12,"description":"Total aspects found."},"harmonious":{"type":"number","example":7,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":4,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":1,"description":"Count of neutral aspects (conjunction)."},"byType":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of aspects of this type found in the chart. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"CONJUNCTION":2,"TRINE":3,"SQUARE":2,"SEXTILE":2,"OPPOSITION":1},"description":"Aspect count grouped by type."}},"required":["totalAspects","harmonious","challenging","neutral","byType"],"description":"Aspect summary with counts by nature and type."}},"required":["date","time","timezone","aspectsFound","aspects","summary"]},"AspectsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Date in YYYY-MM-DD format"},"time":{"type":"string","format":"time","example":"14:30:00","description":"Time in HH:MM:SS format (24-hour)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone offset from UTC in decimal hours (NOT minutes format). Examples: New York EST = -5, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format (5.5, not 5:30).","example":-5},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mercury","Venus","Mars"],"description":"Optional: specific bodies to calculate aspects for (defaults to all 14: the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith)"},"aspectTypes":{"type":"array","items":{"type":"string"},"example":["CONJUNCTION","OPPOSITION","TRINE","SQUARE"],"description":"Optional: specific aspect types to find (defaults to all 9)"}},"required":["date","time","timezone"]},"AspectPatternsResponse":{"type":"object","properties":{"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"All aspect patterns detected in the chart, in detection order: Grand Cross first, then Kite, Grand Trine, T-Square, Yod, Mystic Rectangle, Stellium. Patterns absorbed by a higher-priority detection (T-Squares inside a Grand Cross, Grand Trines absorbed by a Kite) are not reported separately."},"total":{"type":"number","example":3,"description":"Total number of detected aspect patterns in this chart."},"options":{"type":"object","properties":{"strictOrbs":{"type":"boolean","example":false,"description":"Whether the strict (Pontopia-style) orb budget was used. False uses industry-standard orbs (8 for major aspects, 9 for square, 6 for sextile, 3 for quincunx)."},"include":{"type":"array","items":{"type":"string","enum":["chiron","northNode"]},"example":[],"description":"Optional bodies included beyond the default Sun-Pluto set. Empty means classical 10-planet detection only."}},"required":["strictOrbs","include"],"description":"Echo of the options used for this detection run. Useful for reproducibility and for downstream UI display."}},"required":["patterns","total","options"]},"AspectPatternsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"example":{"date":"1955-02-24","time":"19:15:00","latitude":37.77,"longitude":-122.42,"timezone":-8}},"TransitsResponse":{"type":"object","properties":{"transitDate":{"type":"string","example":"2025-12-19","description":"Date of the transit calculation (YYYY-MM-DD)."},"transitTime":{"type":"string","example":"12:00:00","description":"Time of the transit calculation (HH:MM:SS, 24-hour)."},"timezone":{"type":"number","example":0,"description":"Timezone offset from UTC in hours used for this calculation."},"transitPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":267.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for sign and aspect calculation."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets except Moon and Pluto."},"sign":{"type":"string","example":"Sagittarius","description":"Tropical zodiac sign the planet currently occupies. Changes when longitude crosses a 30-degree boundary. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Sagitario","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":27.45,"description":"Degree within the current zodiac sign (0-29.999). Indicates how far into the sign the planet has progressed."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is currently in apparent retrograde motion. Retrograde transits are considered more introspective and revisionary."}},"required":["name","longitude","latitude","sign","degree","speed","isRetrograde"]},"description":"Current positions of all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) in the tropical zodiac. Use for daily transit tracking, horoscope generation, and aspect monitoring."},"transitAspects":{"type":"array","items":{"type":"object","properties":{"transitPlanet":{"type":"string","example":"Sun","description":"Transiting planet forming the aspect. Always English, whatever the lang parameter says. Use transitPlanetLocalized for anything a reader sees."},"transitPlanetLocalized":{"type":"string","example":"Sol","description":"Transiting planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalPlanet":{"type":"string","example":"Mars","description":"Natal planet being aspected. Always English, whatever the lang parameter says. Use natalPlanetLocalized for anything a reader sees."},"natalPlanetLocalized":{"type":"string","example":"Marte","description":"Natal planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"CONJUNCTION","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Conjunción","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":0,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":1.2,"description":"Distance from exact aspect in degrees. Tighter orb = stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the transiting planet is moving toward exactitude (applying) or away from it (separating). Applying aspects grow stronger."},"strength":{"type":"number","example":88,"description":"Aspect strength percentage (0-100) based on orb tightness, where 100 is exact."},"nature":{"type":"string","example":"neutral","description":"Aspect nature: harmonious (trine, sextile), challenging (square, opposition), or neutral (conjunction)."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun activates your natal Mars neutrally","description":"Narrative interpretation of what this transit aspect means and how it manifests."},"timing":{"type":"string","example":"Active for a few days","description":"How long this transit influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego merges with Assertiveness and aggression. Intensifies this energy.","description":"Strength and nature of the transit impact on your natal chart."},"guidance":{"type":"string","example":"Pay attention to how this combination manifests. Strong energy requires conscious direction.","description":"Practical advice for working with or navigating this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["blend","difficult","unite","united"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect including narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["transitPlanet","natalPlanet","type","angle","orb","isApplying","strength","nature","interpretation"]},"description":"Transit-to-natal aspects (only included when natalChart is provided in the request). Shows which transiting planets are aspecting natal planets."},"summary":{"type":"object","properties":{"totalAspects":{"type":"number","example":8,"description":"Total transit-to-natal aspects found."},"harmonious":{"type":"number","example":4,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":3,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":1,"description":"Count of neutral aspects (conjunction)."}},"required":["totalAspects","harmonious","challenging","neutral"],"description":"Transit aspect summary counts (only included when natalChart is provided). Quick overview of the current transit weather."}},"required":["transitDate","transitTime","timezone","transitPlanets"]},"TransitsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-12-19","description":"Transit date in YYYY-MM-DD format (defaults to current date)"},"time":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS format (defaults to current time)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Transit timezone: decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the transit date. Defaults to 0 (UTC).","example":0},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"natalChart":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Time in 24-hour format. Seconds are optional and default to 00 (14:30 becomes 14:30:00); a single-digit hour is zero-padded. Out-of-range values are rejected."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Natal birth latitude in decimal degrees, positive north. Sets the local sidereal time behind the natal Ascendant and house cusps that the transits are measured against."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Natal birth longitude in decimal degrees, positive east and negative west. Example: New York -74.0060, London -0.1276, Sydney 151.2093."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Natal timezone: decimal hours OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the natal date.","example":-5}},"required":["date","time","latitude","longitude","timezone"],"description":"Optional natal chart data to compare transits against"}}},"AstrocartographyResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every planetary line."},"lines":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Celestial body this set of planetary lines belongs to. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this body."},"rightAscension":{"type":"number","example":90.66,"description":"Equatorial right ascension of the body in degrees (0 to 360), the basis for every line."},"declination":{"type":"number","example":23.44,"description":"Equatorial declination of the body in degrees (-90 to 90), which sets how far the rising and setting lines curve."},"mc":{"type":"object","properties":{"longitude":{"type":"number","example":-111.0142,"description":"Constant geographic longitude of this vertical meridian line in decimal degrees. The body culminates (MC) along it, so plot it as a straight north to south line."},"interpretation":{"type":"string","example":"Your Sun Midheaven line runs through places where Self-awareness and ego comes forward in your public life, career, and reputation. Living or working along this line tends to push this part of you into the spotlight.","description":"Plain language meaning of this Midheaven planetary line for relocation, suitable for chart reports and AI agents."}},"required":["longitude","interpretation"],"description":"Midheaven (MC) line. Places along this meridian where the body was culminating overhead, tied to public life, career, and reputation."},"ic":{"type":"object","properties":{"longitude":{"type":"number","example":68.9858,"description":"Constant geographic longitude of this vertical meridian line in decimal degrees. The body anti-culminates (IC) along it, so plot it as a straight north to south line."},"interpretation":{"type":"string","example":"Your Sun Imum Coeli line runs through places where Self-awareness and ego settles into your home, family, and inner foundations. This line deepens your sense of roots and private life.","description":"Plain language meaning of this Imum Coeli planetary line for relocation, suitable for chart reports and AI agents."}},"required":["longitude","interpretation"],"description":"Imum Coeli (IC) line, opposite the MC. Places where the body was anti-culminating, tied to home, family, and inner foundations."},"ascendant":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":40,"description":"Geographic latitude of this sampled point in decimal degrees."},"longitude":{"type":"number","example":139.7118,"description":"Geographic longitude in decimal degrees where the body sits exactly on the eastern (rising) horizon at this latitude."}},"required":["latitude","longitude"]},"description":"Sampled geographic points tracing this rising line from 70 South to 70 North. Join them in latitude order to draw the curved planetary line on a world map."},"circumpolarBeyond":{"type":["number","null"],"example":68.5262,"description":"Absolute latitude in degrees beyond which the body never crosses the horizon, so the line has no points past it. Null when the line spans the full sampled range."},"interpretation":{"type":"string","example":"Your Sun Ascendant line runs through places where Self-awareness and ego colors your identity, vitality, and how you first come across to others. This part of you feels switched on here.","description":"Plain language meaning of this rising (Ascendant) planetary line for relocation, suitable for chart reports and AI agents."}},"required":["points","circumpolarBeyond","interpretation"],"description":"Ascendant (rising) line. Places where the body was on the eastern horizon, tied to identity, vitality, and self-expression."},"descendant":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":40,"description":"Geographic latitude of this sampled point in decimal degrees."},"longitude":{"type":"number","example":-1.7402,"description":"Geographic longitude in decimal degrees where the body sits exactly on the western (setting) horizon at this latitude."}},"required":["latitude","longitude"]},"description":"Sampled geographic points tracing this setting line from 70 South to 70 North. Join them in latitude order to draw the curved planetary line on a world map."},"circumpolarBeyond":{"type":["number","null"],"example":68.5262,"description":"Absolute latitude in degrees beyond which the body never crosses the horizon, so the line has no points past it. Null when the line spans the full sampled range."},"interpretation":{"type":"string","example":"Your Sun Descendant line runs through places where Self-awareness and ego shapes your close relationships, partnerships, and the people you attract. Connection themes stand out along this line.","description":"Plain language meaning of this setting (Descendant) planetary line for relocation, suitable for chart reports and AI agents."}},"required":["points","circumpolarBeyond","interpretation"],"description":"Descendant (setting) line. Places where the body was on the western horizon, tied to relationships and partnerships."}},"required":["planet","rightAscension","declination","mc","ic","ascendant","descendant"]},"description":"One entry per body, each carrying its Midheaven, Imum Coeli, Ascendant, and Descendant planetary lines for relocation mapping."},"summary":{"type":"string","example":"Astrocartography lines for 1990-07-15. 10 bodies, each with Midheaven, Imum Coeli, Ascendant, and Descendant lines mapping where their themes turn angular worldwide for relocation planning.","description":"Short overview of the astrocartography map for previews and report intros."}},"required":["birthDetails","lines","summary"]},"RelocationChartResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1961-08-04","description":"Birth date used for this chart (YYYY-MM-DD)."},"time":{"type":"string","example":"19:24:00","description":"Birth time used for this chart (HH:MM:SS, 24-hour)."},"latitude":{"type":"number","example":21.3069,"description":"Birthplace latitude in decimal degrees."},"longitude":{"type":"number","example":-157.8583,"description":"Birthplace longitude in decimal degrees."},"timezone":{"type":"number","example":-10,"description":"Birth timezone offset from UTC in decimal hours."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birthplace details echoed back. The birth instant is unchanged by relocation."},"relocation":{"type":"object","properties":{"latitude":{"type":"number","example":40.7167,"description":"New location latitude in decimal degrees."},"longitude":{"type":"number","example":-74.006,"description":"New location longitude in decimal degrees."}},"required":["latitude","longitude"],"description":"New location the chart was recomputed for."},"planets":{"type":"array","items":{"$ref":"#/components/schemas/RelocationPlanet"},"description":"All 14 celestial bodies with their unchanged natal signs and degrees, reassigned to the houses they occupy in the relocated chart."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["number","longitude","sign","degree"]},"description":"All 12 relocated house cusps with zodiac positions for the new location."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for the relocated chart (placidus, whole-sign, equal, or koch). Quadrant systems fall back to whole-sign above the polar circle."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign on this relocated angle. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Géminis","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":12.67,"description":"Degree within the zodiac sign on this angle (0-29.999)."},"longitude":{"type":"number","example":72.67,"description":"Absolute ecliptic longitude of this angle in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Relocated Ascendant (rising sign). The eastern horizon at the new place, defining how you come across there."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign on this relocated angle. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Géminis","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":12.67,"description":"Degree within the zodiac sign on this angle (0-29.999)."},"longitude":{"type":"number","example":72.67,"description":"Absolute ecliptic longitude of this angle in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Relocated Midheaven (MC). The highest point of the ecliptic at the new place, tied to career and public image there."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"signLocalized":{"type":"string","example":"Sagitario","description":"Vertex sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house"],"description":"Relocated Vertex. The western prime-vertical and ecliptic intersection at the new place, read as a point of fated encounters."},"changes":{"type":"object","properties":{"ascendantSignChanged":{"type":"boolean","example":true,"description":"Whether the Ascendant sign differs between the birthplace chart and the relocated chart."},"planetsChangedHouse":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Body that occupies a different house after relocation. Always English, whatever the lang parameter says. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalHouse":{"type":"number","example":5,"description":"House this body occupied in the birthplace chart (1-12)."},"relocatedHouse":{"type":"number","example":3,"description":"House this body occupies in the relocated chart (1-12)."}},"required":["planet","natalHouse","relocatedHouse"]},"description":"Bodies whose house placement shifts from the birthplace chart to the relocated chart. Empty when nothing changes house."},"angularPlanets":{"type":"array","items":{"type":"string"},"example":["Venus"],"description":"Bodies within three degrees of a relocated angle (Ascendant, Imum Coeli, Descendant, or Midheaven), where their influence is strongest at this location. Always English, whatever the lang parameter says. Use angularPlanetsLocalized for anything a reader sees."},"angularPlanetsLocalized":{"type":"array","items":{"type":"string"},"example":["Venus"],"description":"The same angular bodies in the requested language, for display only. Index aligned with angularPlanets. Present only when lang is set to a language other than English."},"distanceKm":{"type":"number","example":7983.4,"description":"Great-circle distance from the birthplace to the new location in kilometers."},"direction":{"type":"string","example":"northeast","description":"Compass direction (16-point) from the birthplace to the new location."}},"required":["ascendantSignChanged","planetsChangedHouse","angularPlanets","distanceKm","direction"],"description":"How relocation reshapes the chart: Ascendant shift, planets that change house, angular planets, and the move geometry from the birthplace."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Relocated to this place, your chart angles shift while the planets keep their birth positions. The Ascendant moves to Gemini and the Midheaven to Aquarius, and Venus moves close to the angles, where its influence grows strongest in daily life here.","description":"Narrative summary of the relocation: the new Ascendant and Midheaven signs and any planets that move onto the angles. Localized via the lang query parameter."}},"required":["summary"],"description":"Relocation interpretation summary."}},"required":["birthDetails","relocation","planets","houses","houseSystem","ascendant","midheaven","vertex","changes","interpretation"]},"RelocationPlanet":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Your Sun in Leo in The Third House reveals how you express self-awareness and ego in the realm of communication.","description":"One-sentence interpretation of this planet in its sign and relocated house."},"detailed":{"type":"string","example":"Sun represents self-awareness and ego. In Leo, this energy becomes confident and expressive...","description":"Multi-sentence interpretation of this relocated placement."},"keywords":{"type":"array","items":{"type":"string"},"example":["Confident","Expressive","Communicative"],"description":"Key themes for this relocated placement."}},"required":["summary","detailed","keywords"],"description":"Relocated placement interpretation. The planet keeps its natal sign, so this reads its meaning through the new house it occupies at this location."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"RelocationChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1961-08-04","description":"Birth date in YYYY-MM-DD format. The birth moment is unchanged by relocation, so this still defines the planetary positions of the chart."},"time":{"type":"string","format":"time","example":"19:24:00","description":"Birth time in 24-hour HH:MM:SS format. Combined with the timezone it fixes the exact birth instant, which the relocated angles and houses are recomputed for."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Birth timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\"). Resolved to the DST-correct offset for the birth date. This is the birthplace timezone, not the new location timezone.","example":-10},"birthLatitude":{"type":"number","minimum":-90,"maximum":90,"example":21.3069,"description":"Birthplace latitude in decimal degrees (-90 to 90). Used for the original natal angles and houses that the relocated chart is compared against."},"birthLongitude":{"type":"number","minimum":-180,"maximum":180,"example":-157.8583,"description":"Birthplace longitude in decimal degrees (-180 to 180). Positive East, negative West."},"relocationLatitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7167,"description":"New location latitude in decimal degrees (-90 to 90). The relocated Ascendant and house cusps are most sensitive to north-south movement."},"relocationLongitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"New location longitude in decimal degrees (-180 to 180). The relocated Midheaven shifts roughly one degree per degree of longitude moved."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for dividing the relocated chart into 12 houses. Placidus (default) is time-sensitive and most popular in Western astrology. Whole Sign assigns one sign per house. Equal divides into 30 degree segments from the Ascendant. Koch emphasizes higher latitudes. Quadrant systems fall back to Whole Sign above the polar circle."}},"required":["date","time","timezone","birthLatitude","birthLongitude","relocationLatitude","relocationLongitude"]},"LocalSpaceResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Birth date echoed from the request."},"time":{"type":"string","example":"14:30:00","description":"Birth time echoed from the request."},"latitude":{"type":"number","example":40.7128,"description":"Birthplace latitude, the origin of every local space line."},"longitude":{"type":"number","example":-74.006,"description":"Birthplace longitude, the origin of every local space line."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to the birth instant."}},"required":["date","time","latitude","longitude","timezone"],"description":"The birthplace and birth instant the map was computed for."},"bodies":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Body name (Sun, Moon, Mercury through Pluto, plus North Node, Chiron, or Black Moon Lilith when requested). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this body."},"azimuth":{"type":"number","example":113.63,"description":"Compass bearing of the body as seen from the birthplace, in degrees clockwise from true north (0 = north, 90 = east, 180 = south, 270 = west). This is the direction the local space line points."},"altitude":{"type":"number","example":59.48,"description":"Angular height of the body above (positive) or below (negative) the local horizon at birth, in degrees (-90 to 90)."},"compassDirection":{"type":"string","example":"ESE","description":"Nearest 16-point compass abbreviation for the azimuth (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW)."},"aboveHorizon":{"type":"boolean","example":true,"description":"True when the body is above the local horizon (altitude greater than 0) at the birth moment."},"line":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":39.42,"description":"Waypoint latitude in decimal degrees."},"longitude":{"type":"number","example":-72.71,"description":"Waypoint longitude in decimal degrees."}},"required":["latitude","longitude"]},"description":"Ordered latitude and longitude waypoints tracing the great-circle local space line from the birthplace along the body azimuth. The first point is the birthplace itself."}},"required":["points"],"description":"The great-circle directional line for this body, ready to plot on a map."},"interpretation":{"type":"string","example":"Your Sun line points southeast from your birthplace. Travelling or facing this direction tends to emphasize Self-awareness and ego in your daily experience.","description":"Plain-language reading of what travelling or facing along this body line tends to emphasize. Localized when a translation exists."}},"required":["planet","azimuth","altitude","compassDirection","aboveHorizon","line","interpretation"]},"description":"Every requested body with its horizon direction, altitude, compass direction, great-circle line, and interpretation."},"summary":{"type":"string","example":"Local space directional map of 10 celestial bodies seen from latitude 40.7128, longitude -74.006. 6 of them sit above the horizon at the birth moment.","description":"One-line overview of the local space map."}},"required":["birthDetails","bodies","summary"]},"FixedStarsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to precess every star."},"orb":{"type":"number","example":1,"description":"Conjunction orb in degrees applied to detect contacts between stars and natal points."},"stars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"regulus","description":"Lowercase identifier for the fixed star."},"name":{"type":"string","example":"Regulus","description":"Proper name of the fixed star."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":150.06,"description":"Tropical ecliptic longitude of the star in degrees (0-360), precessed from its J2000 position to the chart date."},"sign":{"type":"string","example":"Virgo","description":"Tropical zodiac sign the star currently occupies."},"degree":{"type":"number","minimum":0,"maximum":30,"example":0.06,"description":"Degree within the zodiac sign (0-29.999)."},"magnitude":{"type":"number","example":1.4,"description":"Apparent visual magnitude. Lower is brighter, and the brightest stars are negative."},"nature":{"type":"string","example":"Mars and Jupiter","description":"Traditional planetary nature of the star in classical astrology."},"keywords":{"type":"array","items":{"type":"string"},"example":["royalty","honor","power","ambition","downfall"],"description":"Traditional astrological keywords associated with the star."},"conjunctions":{"type":"array","items":{"type":"object","properties":{"point":{"type":"string","example":"Sun","description":"Natal point conjunct this star: a planet name, or the chart angles MC and ASC. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use pointLocalized for anything a reader sees."},"pointLocalized":{"type":"string","example":"Sol","description":"Natal point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"pointLongitude":{"type":"number","example":149.21,"description":"Tropical ecliptic longitude of the natal point in degrees (0-360)."},"orb":{"type":"number","example":0.62,"description":"Angular separation in degrees between the star and the natal point. Smaller means a tighter, stronger contact."}},"required":["point","pointLongitude","orb"]},"description":"Natal points within the chosen orb of this star. Empty when no planet or angle contacts the star."}},"required":["id","name","longitude","sign","degree","magnitude","nature","keywords","conjunctions"]},"description":"Every catalog star with its precessed tropical position, magnitude, traditional nature, and any conjunctions to the natal chart."},"conjunctions":{"type":"array","items":{"type":"object","properties":{"star":{"type":"string","example":"Regulus","description":"Proper name of the conjunct fixed star."},"point":{"type":"string","example":"Sun","description":"Natal point conjunct the star: a planet name, or the chart angles MC and ASC. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use pointLocalized for anything a reader sees."},"pointLocalized":{"type":"string","example":"Sol","description":"Natal point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"orb":{"type":"number","example":0.62,"description":"Angular separation in degrees between the star and the natal point."},"interpretation":{"type":"string","example":"The fixed star Regulus sits within 0.6 degrees of your Sun, a star of Mars and Jupiter nature in classical astrology. A star this close to a chart point colors how that point expresses itself with its traditional meaning.","description":"Plain language meaning of this star contact, blending the star traditional nature with the chart point. Localized to the requested language."}},"required":["star","point","orb","interpretation"]},"description":"Flat list of every star to natal point conjunction, sorted tightest first, each with an interpretation. The high-value summary of where fixed stars touch the chart."},"summary":{"type":"string","example":"Fixed star positions for 1990-07-15 with 3 conjunctions within 1 degrees across the major named stars including Regulus, Spica, and Algol.","description":"Short overview of the fixed-star report for previews and report intros."}},"required":["birthDetails","orb","stars","conjunctions","summary"]},"ArabicLotsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every lot."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect that selected each formula. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Every lot swaps its two non-Ascendant terms between day and night."},"lots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"fortune","description":"Stable machine identifier for the lot (fortune, spirit, eros, necessity, courage, victory, nemesis). Use this for lookups."},"name":{"type":"string","example":"Part of Fortune","description":"Name of the lot. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Parte de la Fortuna","description":"Lot name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute tropical ecliptic longitude of the lot in degrees (0 to 360)."},"sign":{"type":"string","example":"Aries","description":"Tropical zodiac sign the lot falls in."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree of the lot within its zodiac sign (0 to 29.999)."},"formula":{"type":"string","example":"Ascendant + Sun - Moon","description":"Human readable arc used for this chart, with the day or night term order already applied by sect."},"interpretation":{"type":"string","example":"Your Part of Fortune falls in Aries, marking the body, health, material wellbeing, and the flow of fortune through your life. Lots are sensitive points derived by arc from the Ascendant, Sun, Moon, and planets, with the formula reversed between day and night charts.","description":"Plain language meaning of this lot in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["id","name","longitude","sign","degree","formula","interpretation"]},"description":"The seven Hermetic lots in canonical order: Part of Fortune and Part of Spirit from the luminaries, then Eros, Necessity, Courage, Victory, and Nemesis from a planet paired with Fortune or Spirit."},"summary":{"type":"string","example":"Seven Hermetic lots for 1990-07-15 cast from a night chart: Fortune, Spirit, Eros, Necessity, Courage, Victory, and Nemesis, each projected by arc from the Ascendant.","description":"Short overview of the lot set for previews and report intros."}},"required":["birthDetails","sect","lots","summary"]},"ArabicLotsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to place the Sun, which determines the chart sect (day when the Sun is above the horizon, night when below) and therefore which lot formula applies. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone"]},"AsteroidsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every asteroid."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system actually used to place the asteroids, after any polar fallback to Whole Sign."},"asteroids":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ceres","description":"Name of the asteroid: Ceres, Pallas, Juno, or Vesta. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Palas","description":"Asteroid name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":64.72,"description":"Absolute tropical ecliptic longitude of the asteroid in degrees (0 to 360)."},"latitude":{"type":"number","example":-2.83,"description":"Ecliptic latitude in degrees, the angular distance north or south of the ecliptic plane."},"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign the asteroid falls in."},"degree":{"type":"number","minimum":0,"maximum":30,"example":4.72,"description":"Degree of the asteroid within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Natal house placement (1 to 12) from the selected house system and birth location."},"speed":{"type":"number","example":0.409,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the asteroid appears to move backward from Earth, true when the daily speed is negative."},"interpretation":{"type":"string","example":"Your Ceres in Gemini speaks to how you nurture and are nurtured, the cycles of nourishment, loss, and return, and the bond between caretaker and cared-for.","description":"Plain language meaning of this asteroid in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde","interpretation"]},"description":"The four classical asteroid goddesses in canonical order: Ceres, Pallas, Juno, and Vesta, each with its tropical position, house, motion, and interpretation."},"summary":{"type":"string","example":"Asteroid goddess positions for 1990-07-15: Ceres, Pallas, Juno, and Vesta placed by sign, house, and retrograde motion.","description":"Short overview of the asteroid set for previews and report intros."}},"required":["birthDetails","houseSystem","asteroids","summary"]},"AsteroidsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to assign each asteroid to a natal house. Placidus (default), Whole Sign, Equal, or Koch. Above the polar circle, quadrant systems fall back to Whole Sign and the echoed houseSystem reports the system actually used."}},"required":["date","time","latitude","longitude","timezone"]},"LilithResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute both Lilith variants."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system applied when placing each variant in a house."},"lilith":{"type":"array","items":{"type":"object","properties":{"variant":{"type":"string","enum":["mean","true"],"example":"mean","description":"Which lunar apogee this entry describes. The mean variant is the smoothed average apogee; the true variant is the instantaneous osculating apogee. Always one of these two English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use variantLocalized for anything a reader sees."},"variantLocalized":{"type":"string","example":"media","description":"Apogee variant label in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":140.58,"description":"Absolute tropical ecliptic longitude of the apogee in degrees (0 to 360)."},"latitude":{"type":"number","example":-0.66,"description":"Ecliptic latitude in degrees, the projection of the apogee off the ecliptic plane. Reaches up to about 5 degrees because the lunar orbit is inclined."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the apogee falls in, naming where the suppressed instinct lives."},"degree":{"type":"number","minimum":0,"maximum":30,"example":20.58,"description":"Degree of the apogee within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1 to 12) in the selected house system, the area of life where the Lilith theme plays out."},"speed":{"type":"number","example":0.1108,"description":"Daily motion in degrees per day. The mean apogee is always positive (direct); the true apogee can be negative (retrograde)."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the apogee is moving backward. Always false for the mean apogee; the true apogee turns retrograde when the osculating ellipse swings the apogee direction backward."},"interpretation":{"type":"string","example":"Your mean Black Moon Lilith in Leo marks where you meet the wild, untamed, and unapologetic in yourself, the instincts you were taught to suppress and the line past which you refuse to be tamed or shamed.","description":"Plain language meaning of this Lilith variant in its sign, suitable for chart reports and AI agents. Localized to the requested language."},"note":{"type":"string","example":"The mean apogee is the smoothed average position, steadier and the most widely used for psychological reading.","description":"Short explanation of how this variant is defined and how it differs from the other, localized to the requested language."}},"required":["variant","longitude","latitude","sign","degree","house","speed","isRetrograde","interpretation","note"]},"description":"Both Black Moon Lilith variants, the mean lunar apogee first and the true (osculating) apogee second."},"summary":{"type":"string","example":"Black Moon Lilith for 1961-08-04: mean apogee in Leo and true osculating apogee in Leo, each with sign, degree, house, and interpretation.","description":"Short overview of both variants for previews and report intros."}},"required":["birthDetails","houseSystem","lilith","summary"]},"LilithRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to place each Lilith variant in a house. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone"]},"ProgressionsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place the progressed chart is built from."},"targetDate":{"type":"string","example":"2025-07-15","description":"The requested date the chart was progressed to."},"progressedDate":{"type":"string","example":"1990-08-17","description":"UTC calendar date of the progressed moment, the ephemeris day whose real positions stand in for the target date. One day after birth per year of elapsed life."},"elapsedYears":{"type":"number","example":35,"description":"Years elapsed between birth and the target date, measured in mean tropical years. Drives both the progressed planets and the Naibod progression of the angles. Negative values progress the chart converse (before birth)."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Body name in canonical English. One of the 10 classical planets, the lunar nodes, Chiron, or Black Moon Lilith. Unchanged by the lang parameter, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":165.18,"description":"Progressed tropical ecliptic longitude in degrees (0 to 360)."},"sign":{"type":"string","example":"Virgo","description":"Tropical zodiac sign the progressed body falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Virgo","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.18,"description":"Degree of the progressed body within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Whole-sign house (1 to 12) counted from the progressed Ascendant sign. The 1st house is the entire sign the progressed Ascendant falls in."},"speed":{"type":"number","example":0.985,"description":"Daily motion of the body at the progressed instant in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the body is retrograde at the progressed instant, true when the daily speed is negative."},"interpretation":{"type":"string","example":"Your progressed Sun in Virgo reflects how self-awareness and ego has matured and shifted since birth.","description":"Plain language meaning of this progressed body in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","longitude","sign","degree","house","speed","isRetrograde","interpretation"]},"description":"Every progressed body in canonical order: the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith. The progressed Sun moves about one degree per year and the progressed Moon about one sign per two and a half years, so these two are the headline movers in any progressed reading."},"ascendant":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"maximum":360,"example":134.27,"description":"Absolute tropical ecliptic longitude of the progressed angle in degrees (0 to 360)."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the progressed angle falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Leo","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":14.27,"description":"Degree of the progressed angle within its zodiac sign (0 to 29.999)."}},"required":["longitude","sign","degree"],"description":"Progressed Ascendant, the rising degree advanced by the Naibod arc per year. Marks the evolving outward style and immediate environment."},"midheaven":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"maximum":360,"example":134.27,"description":"Absolute tropical ecliptic longitude of the progressed angle in degrees (0 to 360)."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the progressed angle falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Leo","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":14.27,"description":"Degree of the progressed angle within its zodiac sign (0 to 29.999)."}},"required":["longitude","sign","degree"],"description":"Progressed Midheaven, the culminating degree advanced by the Naibod arc per year. Marks the evolving vocation and public direction."},"summary":{"type":"string","example":"Your secondary progressed chart advances the birth chart by one day for each year of life.","description":"Short overview of the progressed chart led by the progressed Sun and Moon. Localized to the requested language."}},"required":["birthDetails","targetDate","progressedDate","elapsedYears","planets","ascendant","midheaven","summary"]},"ProgressionsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Date to progress the chart to, in YYYY-MM-DD format. Usually today or a forecast date. The day-for-a-year key turns the elapsed years since birth into the same number of ephemeris days after the birth moment."}},"required":["date","time","latitude","longitude","timezone","targetDate"]},"SolarArcResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute the natal chart and the solar arc."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Echo of the date the chart was directed to."},"solarArc":{"type":"number","minimum":0,"maximum":360,"example":34.52,"description":"The solar arc in degrees: the secondary-progressed Sun longitude minus the natal Sun longitude. Approximately one degree per year of life. Every natal point is advanced by exactly this arc."},"summary":{"type":"string","example":"Solar arc directions move every point in your chart forward by the same arc the Sun has travelled by progression, about one degree per year.","description":"Short overview of the directed chart for previews and report intros. Localized to the requested language."},"directed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Name of the directed point, covering the planets and the two angles, the Ascendant and the Midheaven, alike. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Directed point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalLongitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Absolute tropical ecliptic longitude of the point in the natal chart, in degrees (0 to 360)."},"directedLongitude":{"type":"number","minimum":0,"maximum":360,"example":143.78,"description":"Absolute tropical ecliptic longitude after directing, in degrees (0 to 360). Equals the natal longitude plus the solar arc, normalized to a full circle."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the directed point falls in. A directed point crossing into a new sign marks a developmental turning point."},"degree":{"type":"number","minimum":0,"maximum":30,"example":23.78,"description":"Degree of the directed point within its zodiac sign (0 to 29.999)."},"interpretation":{"type":"string","example":"Your solar arc directed Sun has moved to Leo, carrying self-awareness and ego forward by the 31 degree arc.","description":"Plain language meaning of this directed point, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","natalLongitude","directedLongitude","sign","degree","interpretation"]},"description":"Every natal point advanced by the solar arc: the planets and bodies in canonical order first, then the Ascendant and the Midheaven."}},"required":["birthDetails","targetDate","solarArc","summary","directed"]},"SolarArcRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Date to direct the chart to, in YYYY-MM-DD format. Every natal point is advanced by the solar arc accumulated from birth to this date, about one degree for each year of life."}},"required":["date","time","latitude","longitude","timezone","targetDate"]},"ProfectionsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to derive the natal Ascendant and the lord of the year placement."},"targetDate":{"type":"string","format":"date","example":"2025-08-04","description":"Target date whose profection year was computed, echoed from the request."},"age":{"type":"integer","minimum":0,"example":30,"description":"Completed whole years from birth to the target date. Age 0 is the birth year and profects the first house."},"profectedHouse":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Profected whole sign house activated for the year (1 to 12), computed as age modulo 12 plus 1. House 1 is the rising sign and the cycle repeats every twelve years."},"profectedSign":{"type":"string","example":"Leo","description":"Tropical zodiac sign on the profected house: the rising sign advanced by one whole sign for each completed year."},"lordOfYear":{"type":"string","example":"Sun","description":"Lord of the year (annual time lord): the traditional ruling planet of the profected sign whose natal condition and transits color the themes of the year."},"lordNatalPosition":{"type":"object","properties":{"sign":{"type":"string","example":"Leo","description":"Zodiac sign the lord of the year occupies in the natal chart."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"Natal house the lord of the year occupies (1 to 12), in the requested house system."}},"required":["sign","house"],"description":"Where the lord of the year sits in the birth chart: the natal sign and house that ground the theme of the profection year."},"interpretation":{"type":"string","example":"This profection year activates The Seventh House in Leo, making Sun your lord of the year. The year takes its tone from partnerships and relationships and from how Sun sits in your birth chart.","description":"Plain language reading of the profection year, combining the profected house theme, the profected sign, and the lord of the year. Localized to the requested language."},"summary":{"type":"string","example":"At age 30, the annual profection activates house 7 in Leo, making Sun the lord of the year for 2025-08-04.","description":"Short overview of the profection year for previews and report intros."}},"required":["birthDetails","targetDate","age","profectedHouse","profectedSign","lordOfYear","lordNatalPosition","interpretation","summary"]},"ProfectionsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-08-04","description":"Date whose profection year you want, in YYYY-MM-DD format. The completed whole years from the birth date to this date select the profected house and sign. Must fall on or after the birth date."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used only to report where the lord of the year sits in the natal chart. The profected house and sign always use whole sign profection from the rising sign. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone","targetDate"]},"BirthChartResponse":{"type":"object","properties":{"aries":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"taurus":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"gemini":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"cancer":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"leo":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"virgo":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"libra":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"scorpio":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"sagittarius":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"capricorn":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"aquarius":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"pisces":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the block it sits in, so the aries block carries \"aries\" and the pisces block carries \"pisces\"."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Mars","description":"Planet (graha) placed in this sign."},"longitude":{"type":"number","example":15.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Bharani","description":"Nakshatra (lunar mansion, 1 of 27) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra has 4 padas of 3 degrees 20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."},"house":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi). Present on the D1 birth chart; divisional charts (navamsa, varga) omit it."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"modernPlanets":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Uranus","Neptune","Pluto"],"example":"Uranus","description":"Modern planet name. These three are outside the classical Navagraha and are returned only when modernPlanets true is sent."},"sanskritName":{"type":"string","enum":["Arun","Varun","Yam"],"example":"Arun","description":"Sanskrit name Indian software prints for this body: Arun for Uranus, Varun for Neptune, Yam for Pluto. Transliterated rather than translated, the same treatment as rashi and nakshatra lord names, so it is identical in every locale."},"longitude":{"type":"number","example":214.44,"description":"Sidereal longitude in degrees (0-360), in the same ayanamsa frame as every other position in this response."},"rashi":{"type":"string","example":"Scorpio","description":"Zodiac sign (rashi) the body occupies."},"degreeInRashi":{"type":"number","example":4.44,"description":"Degrees advanced into the sign, 0 to 30. This is the figure a chart displays beside the sign."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Vishakha","description":"Nakshatra (lunar mansion, 1 of 27) the body occupies."},"pada":{"type":"number","example":3,"description":"Nakshatra pada (quarter, 1-4)."},"key":{"type":"number","example":16,"description":"Nakshatra index (1-27) starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Vimshottari ruling planet of this nakshatra."}},"required":["name","pada","key","lord"],"description":"Nakshatra placement. Reported because it is purely positional; it does not imply the body participates in Vimshottari dasha, which is built on the Moon alone."},"isRetrograde":{"type":"boolean","example":true,"description":"True when the body appears to move backward. All three are retrograde for roughly 40 percent of each year, so this is the normal case rather than the exception."}},"required":["planet","sanskritName","longitude","rashi","degreeInRashi","nakshatra","isRetrograde"]},"description":"Uranus, Neptune and Pluto, present only when modernPlanets true was sent. Deliberately separate from meta and deliberately without dignity, avastha, combustion or aspect fields: those are constructs of the nine-graha system and the modern planets rule no sign, so no classical value exists for them. Order is always Uranus, Neptune, Pluto."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"Bhava (house) number 1-12. House 1 is the Lagna (Ascendant), house 7 the partnership axis, house 10 the career axis."},"name":{"type":"string","example":"Tanu Bhava","description":"Classical name of the bhava (house). Present when an interpretation entry exists for this house."},"description":{"type":"string","example":"Self, body, personality, and overall life direction.","description":"Significations of the bhava (house). Present when an interpretation entry exists for this house."},"themes":{"type":"array","items":{"type":"string"},"example":["self","body","health","personality","vitality"],"description":"Significations of the bhava as short keywords, the compact form of description. Bhava 1 covers self, body and vitality; 2 wealth and speech; 7 marriage and partnership; 10 career and status. Suited to chart labels, table cells and legends where the full classical description is too long, and identical to the houseThemes map returned by the Vimshottari dasha and KP chart routes. Localized by the lang query parameter."}},"required":["number"]},"description":"The twelve bhavas (houses) in order, each with its classical name and significations. Houses are counted whole-sign from the Lagna."},"combustion":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mercury","description":"Graha that is combust (too close to the Sun, astangata)."},"distanceFromSun":{"type":"number","example":4.21,"description":"Angular separation from the Sun in degrees."},"orb":{"type":"number","example":12,"description":"Combustion orb in degrees applied for this graha. A planet within this orb of the Sun is treated as combust, weakening its results."}},"required":["planet","distanceFromSun","orb"]},"description":"Combust planets (astangata graha): grahas within their combustion orb of the Sun. Combustion weakens a planet significations. Empty when no planet is combust."},"planetaryWar":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Mars","description":"First graha in the planetary war (graha yuddha) pair."},"planet2":{"type":"string","example":"Saturn","description":"Second graha in the planetary war (graha yuddha) pair."},"distance":{"type":"number","example":0.42,"description":"Angular separation between the two grahas in degrees."},"winner":{"type":"string","example":"Mars","description":"Graha that wins the planetary war, the one with the more northerly ecliptic latitude. The winner keeps its strength, the loser is weakened."}},"required":["planet1","planet2","distance","winner"]},"description":"Planetary wars (graha yuddha): pairs of visible planets within 1 degree of each other. Empty when no two planets are in war."},"interpretations":{"type":"object","additionalProperties":{"type":"object","properties":{"rashi":{"type":"string","example":"Confident, authoritative, and self-driven expression.","description":"Interpretation of the planet placement in its rashi (sign)."},"nakshatra":{"type":"string","example":"Ambitious and disciplined, with a focus on legacy.","description":"Interpretation of the planet placement in its nakshatra."}},"required":["rashi","nakshatra"]},"description":"Planet-in-rashi and planet-in-nakshatra interpretation summaries, keyed by planet name. Translated when a supported lang is requested."},"yogas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"gajakesari","description":"Glossary id (lowercase, kebab-case) matching an entry in the 301-entry planetary-yoga catalog. Use with GET /yoga/{id} to retrieve the full glossary text."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Classical Sanskrit name of the yoga as referenced in BPHS (Brihat Parashara Hora Shastra), Phaladeepika, and B.V. Raman *Three Hundred Important Combinations*."},"description":{"type":"string","example":"Jupiter in kendra from Moon","description":"Brief classical formation rule. Identifies the planetary placement, lordship, dignity, aspect pattern, sign modality, or whole-chart bhava distribution required for the yoga to form."},"result":{"type":"string","example":"Gajakesari Yoga is one of the most powerful yogas...","description":"Classical phala (life-effect) description of the yoga when present, sourced from the parashari and phaladeepika tradition."},"quality":{"type":"string","enum":["Positive","Negative","Both"],"example":"Positive","description":"Overall nature. Auspicious yogas (Pancha Mahapurusha, Gajakesari) bestow benefits; inauspicious yogas (Kemadruma) indicate challenges; Both denotes context-dependent effects."},"family":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Classical grouping, ALWAYS present on a detection verdict: one of the four Nabhasa families (asraya, dala, akriti, sankhya) or classical for the twelve single-combination yogas such as Gajakesari and the Pancha Mahapurusha. Group the verdict list on this key to render a Nabhasa result the way the tradition arranges it. Never translated, so grouping works identically under any lang."},"present":{"type":"boolean","example":true,"description":"True if every classical condition for the yoga is satisfied by the given chart. False means one of TWO different things: the rule failed, or the rule held and a stronger family outranked it. Read `suppressedBy` to tell those apart, which is exact and locale-independent; `evidence` says the same thing in English prose."},"suppressedBy":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Set ONLY when this yoga matched its own classical rule and was then silenced by a higher-ranking family, so `present` is false for a reason a practitioner reads very differently from a failed rule. Names the family that took precedence, under the four classical norms: Akriti outranks Asraya, and Akriti, Asraya and Dala each outrank Sankhya. Absent means the rule genuinely did not hold."},"evidence":{"type":"string","example":"Jupiter in kendra from Moon, not retrograde, no malefic drishti. Strengtheners: Moon out of 6/8/12 (house 4); Moon 5 houses from Sun; Moon not in Scorpio.","description":"Human-readable rationale naming the specific rule that triggered or failed the detection, including planetary positions, dignity, kendradhipati status, lordship, malefic drishti, sign modality, or whole-chart bhava distribution. For a Nabhasa yoga that matched its own rule but was outranked, this names the precedence norm that silenced it, for example that an Akriti yoga outranks Asraya or that any other Nabhasa family suppresses Sankhya."}},"required":["id","name","description","result","quality","family","present"]},"description":"Forty-four classical yogas detected against this chart. Twelve conjunction and dignity yogas: Gajakesari (three-rule parashara definition), Sunapha, Anapha, Dhurdhura, Kemadruma, Chandra Mangala, Budha-Aditya, and the five Pancha Mahapurusha (Ruchaka, Bhadra, Hamsa, Malavya, Sasa). Plus all 32 Nabhasa distribution yogas across the Asraya, Dala, Akriti and Sankhya families, which read how the seven visible grahas are spread over the whole chart rather than any single conjunction, and which apply the four classical precedence norms so an outranked yoga is returned as absent with evidence naming the norm that silenced it. Each entry carries an `id` (matches `GET /yoga/{id}` for full glossary lookup), a `present` boolean, a `quality` (Positive, Negative, or Both = auspicious, inauspicious, or context-dependent), and classical-text `evidence` for the rule that triggered or failed. Filter on `present === true` for the active list."},"meta":{"type":"object","additionalProperties":{"type":"object","properties":{"graha":{"type":"string","example":"Jupiter","description":"Planet (graha) name. One of 9 Navagraha (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) or Lagna (Ascendant). Used for matching transits and dasha lords to natal positions."},"rashi":{"type":"string","example":"Sagittarius","description":"Zodiac sign (rashi) the planet occupies in the birth chart. One of 12 Vedic rashis from Aries (Mesha) to Pisces (Meena)."},"longitude":{"type":"number","example":248.73,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa. Precise position used for aspect calculations, divisional chart mapping, and transit analysis."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Vishakha","description":"Nakshatra (lunar mansion) the planet occupies. One of 27 Vedic nakshatras spanning 13 degrees 20 minutes each. Determines dasha lord and behavioral qualities."},"pada":{"type":"number","example":3,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra divides into 4 padas of 3 degrees 20 minutes. Pada determines Navamsa sign and refines personality traits."},"key":{"type":"number","example":16,"description":"Nakshatra sequence number (1-27) in zodiac order starting from Ashwini. Used for Tara Bala compatibility and dasha calculations."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Drives the dasha sequence and the nakshatra qualities."}},"required":["name","pada","key","lord"],"description":"Nakshatra (lunar mansion) data for this planet. Nakshatras are the 27-fold division of the zodiac central to Vedic timing and compatibility systems."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde motion (appears to move backward through the zodiac). Retrograde planets carry intensified or internalized significations in Vedic interpretation."},"house":{"type":"integer","minimum":1,"maximum":12,"example":9,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi; Lagna itself is house 1). Present on the D1 birth chart; divisional charts omit it."},"avasthaInfo":{"type":"object","properties":{"awastha":{"type":"object","properties":{"meaning":{"type":"string","example":"Adult","description":"One or two word gloss of the state, suitable for a table cell beside the graha."},"interpretation":{"type":"string","example":"At its full strength, the graha delivers its promised results without reservation or delay.","description":"Single-sentence classical reading of what the state does to the graha results, sourced from BPHS ch. 45, Saravali ch. 5 and Phaladeepika ch. 9. Localized by the lang query parameter."}},"required":["meaning","interpretation"]},"jagradadi":{"type":"object","properties":{"meaning":{"type":"string","example":"Adult","description":"One or two word gloss of the state, suitable for a table cell beside the graha."},"interpretation":{"type":"string","example":"At its full strength, the graha delivers its promised results without reservation or delay.","description":"Single-sentence classical reading of what the state does to the graha results, sourced from BPHS ch. 45, Saravali ch. 5 and Phaladeepika ch. 9. Localized by the lang query parameter."}},"required":["meaning","interpretation"]},"deeptadi":{"type":"object","properties":{"meaning":{"type":"string","example":"Adult","description":"One or two word gloss of the state, suitable for a table cell beside the graha."},"interpretation":{"type":"string","example":"At its full strength, the graha delivers its promised results without reservation or delay.","description":"Single-sentence classical reading of what the state does to the graha results, sourced from BPHS ch. 45, Saravali ch. 5 and Phaladeepika ch. 9. Localized by the lang query parameter."}},"required":["meaning","interpretation"]}},"description":"Localized readings for this graha avastha states, present only when avasthaInfo true was sent. Each key mirrors the state field of the same name and carries a short meaning plus a one-sentence classical interpretation, so a client can label Yuva or Swapna without a second lookup call."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs. D1 birth chart only."},"jagradadi":{"type":"string","enum":["Jagrat","Swapna","Sushupti"],"example":"Swapna","description":"Jagradadi avastha, the waking state of the graha set by its sign dignity: Jagrat (awake, own sign or exaltation, full results), Swapna (dreaming, a friendly or neutral sign, medium results), Sushupti (sleeping, an enemy sign or debilitation, no results). Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna own no sign and are omitted."},"deeptadi":{"type":"string","enum":["Dipta","Svastha","Pramudita","Shanta","Dina","Duhkhita","Vikala","Khala","Kopa"],"example":"Pramudita","description":"Deeptadi avastha, the dispositional state of the graha, one of nine: Dipta (exalted, blazing), Svastha (own sign, healthy), Pramudita (great friend sign, delighted), Shanta (friendly sign, at peace), Dina (neutral sign, helpless), Duhkhita (enemy sign, sorrowful), Khala (great enemy sign, harsh), Vikala (joined by a natural malefic, disabled), Kopa (eclipsed by the Sun, enraged). Where more than one applies the more severe is returned, so combustion outranks a malefic conjunction, which outranks the sign reading. Present for the seven classical grahas on the D1 chart; Rahu, Ketu and the Lagna are omitted."}},"required":["graha","rashi","longitude","nakshatra","isRetrograde"]},"description":"Quick lookup of all planet positions keyed by planet name. Contains Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu, and Lagna (Ascendant)."}},"required":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces","frame","houses","combustion","planetaryWar","interpretations","meta"],"example":{"aries":{"rashi":"aries","signs":[]},"meta":{"Sun":{"graha":"Sun","rashi":"Leo","longitude":132.45,"nakshatra":{"name":"Magha","pada":2,"key":9,"lord":"Ketu"},"isRetrograde":false,"house":5,"awastha":"Vriddha"},"Moon":{"graha":"Moon","rashi":"Cancer","longitude":98.32,"nakshatra":{"name":"Punarvasu","pada":4,"key":6,"lord":"Jupiter"},"isRetrograde":false,"house":4,"awastha":"Yuva"}}}},"BirthChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"avasthaInfo":{"type":"boolean","default":false,"example":true,"description":"Set true to include a localized meaning and one-sentence classical interpretation beside each graha avastha state, under avasthaInfo on that graha in meta. Defaults to false, so an existing integration is byte-identical until it opts in. Saves a second call to GET /avasthas and the client-side join that would otherwise be needed to turn Yuva or Swapna into readable text."},"modernPlanets":{"type":"boolean","default":false,"example":true,"description":"Set true to also return Uranus, Neptune and Pluto, under the Sanskrit names Arun, Varun and Yam that Indian software prints for them. They arrive in a separate modernPlanets array, NOT inside meta, because classical Jyotish is defined over nine grahas: the moderns rule no sign, so they have no dignity, avastha, combustion or aspect strength and it would be fabrication to report one. Each carries longitude, rashi, degree in sign, nakshatra with pada and lord, and retrograde status. Defaults to false, so an existing integration is byte-identical until it opts in."}},"required":["date","time","latitude","longitude"]},"NavamsaResponse":{"type":"object","properties":{"chart":{"type":"object","properties":{"meta":{"type":"object","additionalProperties":{"type":"object","properties":{"graha":{"type":"string","example":"Venus","description":"Planet (graha) name. One of 9 Navagraha (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) or Lagna (Ascendant). In Navamsa, Venus and Jupiter placements are especially significant for marriage and spiritual growth."},"rashi":{"type":"string","example":"Libra","description":"Zodiac sign (rashi) the planet occupies in the Navamsa (D9) chart. D9 sign placement reveals the deeper quality of a planet and is critical for spouse characteristics and marriage timing."},"longitude":{"type":"number","example":195.42,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa. Same as D1 birth chart longitude, preserved for cross-chart reference and aspect analysis."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Swati","description":"Nakshatra (lunar mansion) the planet occupies. One of 27 Vedic nakshatras spanning 13 degrees 20 minutes each. Determines dasha lord and behavioral qualities."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra divides into 4 padas of 3 degrees 20 minutes. Pada determines Navamsa sign and refines personality traits."},"key":{"type":"number","example":15,"description":"Nakshatra sequence number (1-27) in zodiac order starting from Ashwini. Used for Tara Bala compatibility and dasha calculations."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Carried over from the D1 nakshatra."}},"required":["name","pada","key","lord"],"description":"Nakshatra (lunar mansion) data for this planet. Nakshatras are the 27-fold division of the zodiac central to Vedic timing and compatibility systems."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde motion (appears to move backward through the zodiac). Retrograde planets carry intensified or internalized significations in Vedic interpretation."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Bhava (house) number 1-12 in the Navamsa chart, counted whole-sign from the D9 Lagna. This is the Navamsa-specific house and differs from the D1 birth-chart house."}},"required":["graha","rashi","longitude","nakshatra","isRetrograde"]},"description":"Planet positions in the Navamsa (D9) chart keyed by planet name. Contains all 9 Navagraha plus Lagna."},"aries":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the navamsa rashi-house block it sits in."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Venus","description":"Planet (graha) placed in this navamsa sign."},"longitude":{"type":"number","example":195.42,"description":"Original sidereal longitude in degrees (0-360), same as the D1 birth chart. Preserved for cross-chart reference."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Swati","description":"Nakshatra (lunar mansion) the planet occupies."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4)."},"key":{"type":"number","example":14,"description":"Nakshatra index in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Vimshottari ruling planet of this nakshatra."}},"required":["name","pada","key","lord"],"description":"Nakshatra (lunar mansion) data for this planet, carried over from the D1 chart."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde motion."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Bhava (house) number 1-12 in the Navamsa chart, counted whole-sign from the D9 Lagna."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this navamsa sign."}},"required":["rashi","signs"],"description":"One of the 12 navamsa rashi-house buckets (aries shown; taurus through pisces follow the identical shape). Each lists the planets placed in that sign."}},"required":["meta","aries"],"additionalProperties":{},"description":"Navamsa (D9) divisional chart showing planetary positions across 12 rashi houses plus a meta lookup. Same structure as the birth chart response."},"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"vargottama":{"type":"array","items":{"type":"string"},"description":"Planets that are Vargottama (same sign in D1 and D9)","example":["Sun","Moon"]},"vargottamaExplanation":{"type":"string","description":"Explanation of Vargottama significance","example":"Vargottama planets occupy the same zodiac sign in both D1 (birth chart) and D9 (Navamsa chart), indicating exceptional strength and purity. These planets deliver their full results with minimal affliction, bringing stability and success in their significations. Vargottama is considered highly auspicious, especially for benefics like Jupiter and Venus, as it doubles the positive effects in marriage, spirituality, and overall life prosperity."}},"required":["chart","frame","vargottama","vargottamaExplanation"]},"NavamsaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"DivisionalChartResponse":{"type":"object","properties":{"division":{"type":"object","properties":{"number":{"type":"integer","example":10,"description":"Division number (e.g. 10 for D10 Dasamsa)."},"name":{"type":"string","example":"Dasamsa","description":"English name of the divisional chart."},"sanskritName":{"type":"string","example":"Dasamsa","description":"Sanskrit name of the divisional chart."},"degreesPerDivision":{"type":"string","example":"3°","description":"Size of each division segment within a 30-degree sign."},"significance":{"type":"string","example":"Career, profession, public reputation, and social status","description":"Life areas this divisional chart reveals."}},"required":["number","name","sanskritName","degreesPerDivision","significance"],"description":"Metadata about the selected divisional chart."},"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"chart":{"type":"object","properties":{"meta":{"type":"object","additionalProperties":{"type":"object","properties":{"graha":{"type":"string","example":"Jupiter","description":"Planet (graha) name. One of 9 Navagraha (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) or Lagna (Ascendant). Used to match transits and dasha lords to divisional chart placements."},"rashi":{"type":"string","example":"Sagittarius","description":"Zodiac sign (rashi) the planet occupies in this divisional chart. May differ from the D1 birth chart sign. Comparing D1 and divisional rashi reveals Vargottama status and domain-specific strengths."},"longitude":{"type":"number","example":248.73,"description":"Original sidereal longitude in degrees (0-360) using Lahiri ayanamsa, same as D1 birth chart. Sign placement changes per division but longitude is preserved for cross-chart reference."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Vishakha","description":"Nakshatra (lunar mansion) the planet occupies. One of 27 Vedic nakshatras spanning 13 degrees 20 minutes each. Determines dasha lord and behavioral qualities."},"pada":{"type":"number","example":3,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra divides into 4 padas of 3 degrees 20 minutes. Pada determines Navamsa sign and refines personality traits."},"key":{"type":"number","example":16,"description":"Nakshatra sequence number (1-27) in zodiac order starting from Ashwini. Used for Tara Bala compatibility and dasha calculations."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Vimshottari ruling planet of this nakshatra. One of the nine grahas (Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury). Carried over from the D1 nakshatra."}},"required":["name","pada","key","lord"],"description":"Nakshatra (lunar mansion) data for this planet. Nakshatras are the 27-fold division of the zodiac central to Vedic timing and compatibility systems."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde motion (appears to move backward through the zodiac). Retrograde planets carry intensified or internalized significations in Vedic interpretation."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Bhava (house) number 1-12 in this divisional chart, counted whole-sign from the divisional Lagna. Specific to this varga and differs from the D1 birth-chart house."}},"required":["graha","rashi","longitude","nakshatra","isRetrograde"]},"description":"Planet positions in the divisional chart keyed by planet name. Contains all 9 Navagraha plus Lagna."},"aries":{"type":"object","properties":{"rashi":{"type":"string","example":"aries","description":"Zodiac sign name in lowercase. Always equals the key of the divisional rashi-house block it sits in."},"signs":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Jupiter","description":"Planet (graha) placed in this divisional sign."},"longitude":{"type":"number","example":248.73,"description":"Original sidereal longitude in degrees (0-360), same as the D1 birth chart. Preserved for cross-chart reference."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Vishakha","description":"Nakshatra (lunar mansion) the planet occupies."},"pada":{"type":"number","example":3,"description":"Nakshatra pada (quarter, 1-4)."},"key":{"type":"number","example":16,"description":"Nakshatra index in the zodiac sequence starting from Ashwini."},"lord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Vimshottari ruling planet of this nakshatra."}},"required":["name","pada","key","lord"],"description":"Nakshatra (lunar mansion) data for this planet, carried over from the D1 chart."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde motion."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Bhava (house) number 1-12 in this divisional chart, counted whole-sign from the divisional Lagna."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this divisional sign."}},"required":["rashi","signs"],"description":"One of the 12 divisional rashi-house buckets (aries shown; taurus through pisces follow the identical shape). Each lists the planets placed in that sign."}},"required":["meta","aries"],"additionalProperties":{},"description":"Divisional chart showing planetary positions across 12 rashi houses plus a meta lookup. Same structure as birth chart and navamsa responses."},"vargottama":{"type":"array","items":{"type":"string"},"description":"Planets that are Vargottama (same sign in D1 and this divisional chart). Vargottama planets deliver strong, consistent results.","example":["Sun","Jupiter"]}},"required":["division","frame","chart","vargottama"]},"DivisionalChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"division":{"type":"integer","example":10,"description":"Divisional chart number. Each division reveals a specific life area. Supported: 2 (Hora, wealth), 3 (Drekkana, siblings), 4 (Chaturthamsa, property), 7 (Saptamsa, children), 9 (Navamsa, marriage), 10 (Dasamsa, career), 12 (Dwadasamsa, parents), 16 (Shodasamsa, vehicles), 20 (Vimsamsa, spirituality), 24 (Chaturvimsamsa, education), 27 (Bhamsa, strength), 30 (Trimsamsa, misfortunes), 40 (Khavedamsa, merit), 45 (Akshavedamsa, character), 60 (Shashtiamsa, past life karma)."}},"required":["date","time","latitude","longitude","division"]},"CompatibilityResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"total":{"type":"number","example":24.5,"description":"Total Ashtakoot Gun Milan score out of 36. Scores above 18 are considered compatible for marriage. Higher scores indicate stronger marital harmony."},"maxScore":{"type":"number","example":36,"description":"Maximum possible Guna Milan score (always 36). The 36 points are distributed across 8 kootas (matching categories)."},"percentage":{"type":"number","example":68.1,"description":"Compatibility percentage derived from total/maxScore. Above 50% (18/36) is the traditional minimum threshold for marriage compatibility."},"isCompatible":{"type":"boolean","example":true,"description":"True when percentage >= 50% (18/36 minimum). Based on the traditional Ashtakoot Gun Milan threshold used by Vedic astrologers for kundli matching."},"recommendation":{"type":"string","example":"Union is recommended","description":"Human-readable marriage recommendation based on overall score and dosha analysis. Indicates whether the union is recommended, and if not, specifies the reason (e.g. Nadi Dosha, Bhakoot Dosha, low overall score)."},"doshas":{"type":"array","items":{"type":"string"},"example":[],"description":"List of active (uncancelled) doshas in the matching. Doshas that meet classical cancellation conditions from Muhurta Martanda or BPHS are excluded from this array and appear in doshaCancellations instead. Common doshas: Nadi Dosha (same Nadi type, 0/8 points), Bhakoot Dosha (inauspicious Moon sign distance, 0/7 points). Empty array when no doshas are present or all detected doshas are cancelled."},"doshaCancellations":{"type":"array","items":{"type":"object","properties":{"dosha":{"type":"string","example":"Bhakoot Dosha","description":"Name of the cancelled dosha (Nadi Dosha or Bhakoot Dosha)."},"reason":{"type":"string","example":"Moon sign lords are the same planet (Venus)","description":"Classical cancellation condition that neutralizes this dosha. Based on Muhurta Martanda for Nadi Dosha and BPHS for Bhakoot Dosha."}},"required":["dosha","reason"]},"description":"Doshas detected but cancelled by classical exception rules. Nadi Dosha cancels when partners share the same Moon sign with different nakshatras, same nakshatra with different padas, or same nakshatra spanning different signs. Bhakoot Dosha cancels when Moon sign lords are the same planet or mutual natural friends. Koota score remains 0 but the dosha is not counted against the recommendation."},"breakdown":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","example":"Varna","description":"One of 8 Ashtakoot matching categories: Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi."},"score":{"type":"number","example":1,"description":"Points scored in this category. Maximum varies: Varna (1), Vashya (2), Tara (3), Yoni (4), Graha Maitri (5), Gana (6), Bhakoot (7), Nadi (8)."},"maxScore":{"type":"number","example":1,"description":"Maximum possible points for this koota category."},"person1":{"type":"string","example":"Vaishya","description":"Classification of person 1 for this koota (e.g. Vaishya for Varna, Chatushpada for Vashya, Sheep for Yoni)."},"person2":{"type":"string","example":"Shudra","description":"Classification of person 2 for this koota."},"description":{"type":"string","example":"Spiritual compatibility and mutual respect","description":"Human-readable explanation of what this koota category evaluates."}},"required":["category","score","maxScore","person1","person2","description"]},"description":"Detailed breakdown of compatibility scores across all 8 Ashtakoot kootas. Each category evaluates a different aspect of marital compatibility: temperament, physical, mental, financial, and health."}},"required":["frame","total","maxScore","percentage","isCompatible","recommendation","doshas","doshaCancellations","breakdown"]},"CompatibilityRequest":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5}},"required":["date","time","latitude","longitude"],"description":"Birth data of the first person (typically the boy/groom in traditional Ashtakoot matching). Date, time, and location determine Moon nakshatra for koota scoring."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5}},"required":["date","time","latitude","longitude"],"description":"Birth data of the second person (typically the girl/bride in traditional Ashtakoot matching). Moon nakshatra compared against person 1 across all 8 kootas."},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["person1","person2"]},"PlanetaryPositionsResponse":{"type":"object","additionalProperties":{"type":"object","properties":{"graha":{"type":"string","example":"Sun","description":"Vedic planet (graha) name. One of the Navagraha: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu, or Lagna (Ascendant)."},"rashi":{"type":"string","example":"Leo","description":"Zodiac sign (rashi) the planet occupies. One of 12 Vedic rashis from Aries to Pisces."},"longitude":{"type":"number","example":132.45,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa. Precise planetary position for chart calculations."},"latitude":{"type":"number","example":1.23,"description":"Ecliptic latitude in degrees, the angular distance north (positive) or south (negative) of the ecliptic. Used in planetary war (graha yuddha) winner resolution and latitude-sensitive analysis. Omitted for the Lagna (Ascendant)."},"house":{"type":"number","example":5,"description":"House number (1-12) the planet occupies using Whole Sign house system. House 1 is the Lagna (Ascendant) sign. Essential for bhava analysis and house-level predictions."},"nakshatra":{"type":"object","properties":{"name":{"type":"string","example":"Magha","description":"Nakshatra (lunar mansion) the planet occupies. One of 27 Vedic nakshatras spanning 13 degrees 20 minutes each."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra divides into 4 padas of 3 degrees 20 minutes. Determines Navamsa sign."},"key":{"type":"number","example":9,"description":"Nakshatra sequence number (1-27) in zodiac order starting from Ashwini. Used for Tara Bala and dasha calculations."},"deity":{"type":"string","example":"Pitris (Ancestors)","description":"Presiding deity of the nakshatra from Vedic mythology. Influences the spiritual quality and karmic themes of the planet placement."},"symbol":{"type":"string","example":"Royal Throne","description":"Traditional symbol representing the nakshatra. Reflects core energy and life themes associated with this lunar mansion."},"characteristics":{"type":"string","example":"Leadership qualities...","description":"Personality traits and behavioral tendencies when a planet occupies this nakshatra. Used for character analysis and prediction."}},"required":["name","pada","key"],"description":"Nakshatra (lunar mansion) data with optional interpretive details from Vedic tradition."},"rashiDetails":{"type":"object","properties":{"vedicName":{"type":"string","example":"Simha","description":"Sanskrit name of the zodiac sign as used in traditional Jyotish texts."},"symbol":{"type":"string","example":"Lion","description":"Traditional symbol representing this zodiac sign."},"energy":{"type":"string","example":"Masculine, Fire","description":"Elemental and gender classification of the rashi (Masculine/Feminine, Fire/Earth/Air/Water)."},"characteristics":{"type":"string","example":"Natural leadership...","description":"Key personality traits and behavioral tendencies of this zodiac sign in Vedic astrology."}},"description":"Vedic zodiac sign (rashi) details including Sanskrit name, symbol, elemental energy, and personality characteristics. Present when interpretation data is available."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in retrograde motion (vakri). Rahu and Ketu are always retrograde in Vedic astrology."},"isCombust":{"type":"boolean","example":false,"description":"Whether the planet is combust (asta, moudhya). A planet is combust when too close to the Sun, weakening its significations. Limits per Surya Siddhanta: Moon 12 deg, Mars 17 deg, Mercury 14 deg (12 deg if retrograde), Jupiter 11 deg, Venus 10 deg (8 deg if retrograde), Saturn 15 deg. Compared against the difference in ecliptic longitude, which is the standard interpretive convention and matches what other Vedic software reports. It is a chart judgement and not a statement about naked-eye visibility, which additionally depends on the observer latitude: for that use the heliacal endpoint, which applies the same limits in the classical degrees of time. The field is omitted entirely for Sun, Rahu, Ketu and Lagna, since the question does not apply to them rather than the answer being no."},"combustionDistance":{"type":"number","example":8.45,"description":"Angular distance from the Sun in degrees (0-180). Smaller values indicate closer proximity. Null for Sun, Rahu, Ketu, and Lagna. Useful for gauging combustion severity and planetary strength analysis."},"awastha":{"type":"string","enum":["Bala","Kumara","Yuva","Vriddha","Mrita"],"example":"Yuva","description":"Baladi avastha, the planetary age-state set by the graha degree within its sign: Bala (infant), Kumara (child), Yuva (adult, strongest results), Vriddha (old), Mrita (dead, weakest). Bands run forward in odd signs and reversed in even signs."}},"required":["graha","rashi","longitude","house","nakshatra","isRetrograde"]},"example":{"Sun":{"graha":"Sun","rashi":"Leo","longitude":132.45,"house":5,"nakshatra":{"name":"Magha","pada":2,"key":9,"deity":"Pitris (Ancestors)","symbol":"Royal Throne","characteristics":"Leadership, ancestral pride, regal nature"},"rashiDetails":{"vedicName":"Simha","symbol":"Lion","energy":"Masculine, Fire","characteristics":"Natural leadership, confidence, creativity"},"isRetrograde":false},"Moon":{"graha":"Moon","rashi":"Cancer","longitude":98.32,"house":4,"nakshatra":{"name":"Punarvasu","pada":4,"key":6,"deity":"Aditi","symbol":"Bow and Quiver","characteristics":"Renewal, optimism, spiritual growth"},"rashiDetails":{"vedicName":"Karka","symbol":"Crab","energy":"Feminine, Water","characteristics":"Nurturing, emotional depth, protective"},"isRetrograde":false}}},"PlanetaryPositionsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"ManglikResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"present":{"type":"boolean","description":"Whether Manglik dosha (Kuja dosha) is present based on Mars placement from Lagna","example":true},"severity":{"type":"string","enum":["Mild","Moderate","Severe"],"description":"Manglik dosha intensity, Mild (houses 2, 12), Moderate (houses 4, 7), Severe (houses 1, 8)","example":"Mild"},"description":{"type":"string","description":"Human-readable Manglik dosha analysis with Mars house placement","example":"Manglik Dosha present. Mars in house 12 creates matrimonial afflictions."},"exceptions":{"type":"array","items":{"type":"string"},"description":"Classical cancellation factors that reduce Manglik dosha severity (own sign, exaltation, benefic aspects)","example":["Mars in own sign (reduces severity)"]},"remedies":{"type":"array","items":{"type":"string"},"description":"Traditional Vedic remedies for Manglik dosha mitigation based on severity level","example":["Chant Hanuman Chalisa daily","Visit Hanuman temple on Tuesdays"]},"effects":{"type":"object","properties":{"marriage":{"type":"string","description":"Impact of Manglik dosha on marriage and marital harmony","example":"Delays in marriage, marital discord, separation, or multiple marriages"},"personality":{"type":"string","description":"Influence on temperament and behavioral traits","example":"Aggressive behavior, impatience, dominance, short temper"},"timing":{"type":"string","description":"Age-related intensity and Mars maturity effects","example":"Effects significantly reduce after age 28 (Mars maturity age)"},"relationships":{"type":"string","description":"Impact on interpersonal and spousal relationships","example":"Conflicts with spouse, power struggles, lack of harmony"}},"required":["marriage","personality","timing","relationships"],"description":"Manglik dosha effects on marriage, personality, and relationships"}},"required":["frame","present","description"]},"ManglikRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"KalsarpaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"present":{"type":"boolean","description":"Whether Kalsarpa dosha (Kalsarpa yoga) is present, all planets hemmed between Rahu-Ketu axis","example":true},"severity":{"type":"string","enum":["Mild","Moderate","Severe"],"description":"Kalsarpa dosha intensity based on Rahu-Ketu house positions","example":"Moderate"},"type":{"type":"string","description":"One of 12 Kalsarpa types based on Rahu house position (Ananta, Kulik, Vasuki, Shankhapala, Padma, Mahapadma, Takshak, Karkotak, Shankhachud, Ghatak, Vishdhar, Sheshnag)","example":"Vasuki Kalsarpa"},"description":{"type":"string","description":"Human-readable Kalsarpa dosha analysis with Rahu-Ketu axis details","example":"Vasuki Kalsarpa Dosha present. All planets hemmed between Rahu (house 3) and Ketu."},"remedies":{"type":"array","items":{"type":"string"},"description":"Traditional Vedic remedies for Kalsarpa dosha including puja, mantras, and spiritual practices","example":["Perform Kaal Sarp Dosh Puja at Trimbakeshwar or Ujjain","Chant Mahamrityunjaya Mantra daily"]},"effects":{"type":"object","properties":{"duration":{"type":"string","description":"When Kalsarpa effects are most active in Vimshottari dasha","example":"Effects active during Rahu and Ketu Mahadasha/Antardasha periods"},"career":{"type":"string","description":"Impact on professional growth and career progress","example":"Obstacles in progress, sudden setbacks, delayed success"},"health":{"type":"string","description":"Physical and mental health implications","example":"Chronic health issues, accidents, mental stress"},"relationships":{"type":"string","description":"Impact on family bonds and personal relationships","example":"Family disputes, separation from loved ones"},"mindset":{"type":"string","description":"Psychological and emotional effects","example":"Anxiety, fear, nightmares, psychological struggles"},"positive":{"type":"string","description":"Potential spiritual and personal growth benefits","example":"Can bring spiritual inclination and inner strength when managed well"}},"required":["duration","career","health","relationships","mindset","positive"],"description":"Kalsarpa dosha effects on career, health, mindset, and relationships"}},"required":["frame","present","description"]},"KalsarpaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"SadhesatiResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"present":{"type":"boolean","description":"Whether Sade Sati is currently active, Saturn transiting 12th, 1st, or 2nd house from natal Moon","example":true},"severity":{"type":"string","enum":["Mild","Moderate","Severe"],"description":"Sadhesati intensity: Moderate for Rising/Setting phases, Severe for Peak phase (Saturn over natal Moon)","example":"Severe"},"type":{"type":"string","description":"Current Sadhesati phase: Rising (12th house), Peak (1st house), or Setting (2nd house)","example":"Peak phase (1st house)"},"description":{"type":"string","description":"Human-readable Sadhesati analysis with current Saturn transit phase relative to natal Moon","example":"Sadhesati active. Peak phase (1st house) - Saturn transiting relative to natal Moon."},"remedies":{"type":"array","items":{"type":"string"},"description":"Traditional Vedic remedies for Shani Sade Sati including Shani mantras, donations, and worship","example":["Chant Shani Mantra 108 times daily","Light mustard oil lamp under peepal tree on Saturdays"]},"effects":{"type":"object","properties":{"general":{"type":"string","description":"Overall impact of Saturn transit during Sade Sati period","example":"Overall period brings karmic lessons, maturity, and eventual growth through challenges"},"phases":{"type":"object","additionalProperties":{"type":"string","description":"What Shani delivers during this Sadhesati phase, keyed by the phase the transit is in. Only the phase the chart is currently in is present, so a client renders it without choosing between three.","example":"Health issues, relationship problems, career obstacles, maximum hardships"},"description":"Phase-specific effects for the current Sadhesati stage (Rising/Peak/Setting)","example":{"Peak phase (1st house)":"Health issues, relationship problems, career obstacles, maximum hardships"}}},"required":["general","phases"],"description":"Sadhesati effects by transit phase with general and phase-specific impacts"}},"required":["frame","present","description"]},"SadhesatiRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"YogaDetail":{"type":"object","properties":{"id":{"type":"string","example":"gajakesari","description":"Glossary id (lowercase, kebab-case) matching an entry in the 301-entry planetary-yoga catalog. Use with GET /yoga/{id} to retrieve the full glossary text."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Classical Sanskrit name of the yoga as referenced in BPHS (Brihat Parashara Hora Shastra), Phaladeepika, and B.V. Raman *Three Hundred Important Combinations*."},"description":{"type":"string","example":"Jupiter in kendra from Moon","description":"Brief classical formation rule. Identifies the planetary placement, lordship, dignity, aspect pattern, sign modality, or whole-chart bhava distribution required for the yoga to form."},"result":{"type":"string","example":"Gajakesari Yoga is one of the most powerful yogas...","description":"Classical phala (life-effect) description of the yoga when present, sourced from the parashari and phaladeepika tradition."},"quality":{"type":"string","enum":["Positive","Negative","Both"],"example":"Positive","description":"Overall nature. Auspicious yogas (Pancha Mahapurusha, Gajakesari) bestow benefits; inauspicious yogas (Kemadruma) indicate challenges; Both denotes context-dependent effects."},"family":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Nabhasa family this yoga belongs to, present only on the 32 Nabhasa distribution yogas: asraya (3, sign modality), dala (2, benefic or malefic kendra tenancy), akriti (20, bhava shape) and sankhya (7, count of occupied rasis). Absent on every other glossary row, which is most of the catalog, since those are single-combination yogas outside the Nabhasa scheme. Group or filter the catalog on this key; it is never translated."}},"required":["id","name","description","result","quality"]},"YogaDetectResponse":{"type":"object","properties":{"yogas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"gajakesari","description":"Glossary id (lowercase, kebab-case) matching an entry in the 301-entry planetary-yoga catalog. Use with GET /yoga/{id} to retrieve the full glossary text."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Classical Sanskrit name of the yoga as referenced in BPHS (Brihat Parashara Hora Shastra), Phaladeepika, and B.V. Raman *Three Hundred Important Combinations*."},"description":{"type":"string","example":"Jupiter in kendra from Moon","description":"Brief classical formation rule. Identifies the planetary placement, lordship, dignity, aspect pattern, sign modality, or whole-chart bhava distribution required for the yoga to form."},"result":{"type":"string","example":"Gajakesari Yoga is one of the most powerful yogas...","description":"Classical phala (life-effect) description of the yoga when present, sourced from the parashari and phaladeepika tradition."},"quality":{"type":"string","enum":["Positive","Negative","Both"],"example":"Positive","description":"Overall nature. Auspicious yogas (Pancha Mahapurusha, Gajakesari) bestow benefits; inauspicious yogas (Kemadruma) indicate challenges; Both denotes context-dependent effects."},"family":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Classical grouping, ALWAYS present on a detection verdict: one of the four Nabhasa families (asraya, dala, akriti, sankhya) or classical for the twelve single-combination yogas such as Gajakesari and the Pancha Mahapurusha. Group the verdict list on this key to render a Nabhasa result the way the tradition arranges it. Never translated, so grouping works identically under any lang."},"present":{"type":"boolean","example":true,"description":"True if every classical condition for the yoga is satisfied by the given chart. False means one of TWO different things: the rule failed, or the rule held and a stronger family outranked it. Read `suppressedBy` to tell those apart, which is exact and locale-independent; `evidence` says the same thing in English prose."},"suppressedBy":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Set ONLY when this yoga matched its own classical rule and was then silenced by a higher-ranking family, so `present` is false for a reason a practitioner reads very differently from a failed rule. Names the family that took precedence, under the four classical norms: Akriti outranks Asraya, and Akriti, Asraya and Dala each outrank Sankhya. Absent means the rule genuinely did not hold."},"evidence":{"type":"string","example":"Jupiter in kendra from Moon, not retrograde, no malefic drishti. Strengtheners: Moon out of 6/8/12 (house 4); Moon 5 houses from Sun; Moon not in Scorpio.","description":"Human-readable rationale naming the specific rule that triggered or failed the detection, including planetary positions, dignity, kendradhipati status, lordship, malefic drishti, sign modality, or whole-chart bhava distribution. For a Nabhasa yoga that matched its own rule but was outranked, this names the precedence norm that silenced it, for example that an Akriti yoga outranks Asraya or that any other Nabhasa family suppresses Sankhya."}},"required":["id","name","description","result","quality","family","present"]},"description":"Array of 48 detected yogas, always the full set so a caller can render absent verdicts too. Every entry carries a `present` boolean and a `quality` (Positive, Negative, or Both = auspicious, inauspicious, or context-dependent); filter on present === true for active yogas. Evidence text names the rule that triggered or failed, or the precedence norm that outranked it."},"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"total":{"type":"number","example":4,"description":"Count of yogas where present === true in this chart. Range 0-48, though real charts sit in the low single digits: the Nabhasa families are mutually constrained by the precedence norms, and most shape yogas are rare."},"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-04","description":"Birth date the kundli was cast for, YYYY-MM-DD, echoed back from the request."},"time":{"type":"string","example":"10:12:00","description":"Birth time the kundli was cast for, 24-hour HH:MM:SS, echoed back from the request. Lagna moves roughly one rashi every two hours, so this is what pins the bhava-dependent yogas."},"latitude":{"type":"number","example":28.6139,"description":"Birth latitude in decimal degrees, echoed back from the request. Feeds the local sidereal time behind the Lagna."},"longitude":{"type":"number","example":77.209,"description":"Birth longitude in decimal degrees, echoed back from the request. East is positive, west is negative."},"timezone":{"type":"number","example":5.5,"description":"Numeric UTC offset in decimal hours that the chart engine actually consumed. An IANA name sent on the request is resolved to its DST-correct offset upstream, so this is always a number."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the resolved birth data used for detection. Timezone is the numeric offset that the chart engine consumed (IANA names are resolved upstream)."}},"required":["yogas","frame","total","birthDetails"]},"YogaDetectRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"KPAyanamsaResponse":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-26","description":"Date for which ayanamsa was calculated"},"instant":{"type":"string","example":"2025-12-26T03:30:00.000Z","description":"The exact UTC instant the value was computed for, after applying the time and timezone. Echoed so a client reconciling to the arcsecond can confirm the moment rather than infer it from the date alone. Equals midnight UTC of the date when no time was supplied."},"ayanamsa":{"type":"number","example":24.22233926,"description":"KP-Newcomb ayanamsa value in degrees"},"type":{"type":"string","example":"kp-newcomb","description":"Ayanamsa type identifier"},"formula":{"type":"string","example":"Newcomb precession theory","description":"Mathematical basis for ayanamsa calculation"},"calculated":{"type":"string","example":"2025-12-26T10:30:00Z","description":"UTC timestamp when calculation was performed"}},"required":["date","instant","ayanamsa","type","formula","calculated"]},"KPPlanetsResponse":{"type":"object","properties":{"ayanamsa":{"type":"number","example":24.22233926,"description":"Applied ayanamsa value in degrees"},"planets":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Vedic graha name (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu)."},"longitude":{"type":"number","example":108.23,"description":"KP sidereal longitude in degrees (0-360). Used to determine Placidus house placement and KP subdivision (sign, star, sub)."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign (rashi) this planet occupies in the sidereal zodiac."},"signLord":{"type":"string","example":"Moon","description":"Rashi lord (sign ruler). First level of the KP significator hierarchy. Its house ownership determines L4 significations."},"nakshatra":{"type":"string","example":"Pushya","description":"Nakshatra (lunar mansion) this planet occupies. One of 27 nakshatras, each spanning 13 degrees 20 minutes."},"nakshatraNumber":{"type":"number","example":8,"description":"Nakshatra sequence number (1-27). Ashwini=1 through Revati=27."},"nakshatraLord":{"type":"string","example":"Saturn","description":"Nakshatra lord (star ruler) from the Vimshottari dasha sequence. Determines the nature of results this planet delivers in KP."},"pada":{"type":"number","example":2,"description":"Nakshatra pada/quarter (1-4)"},"starLord":{"type":"string","example":"Saturn","description":"Star-lord (same as nakshatra lord in KP system)"},"subLord":{"type":"string","example":"Mercury","description":"Sub-lord based on 249-level KP subdivision"},"subSubLord":{"type":"string","example":"Venus","description":"Sub-sub lord (SSL) based on 2241-level KP subdivision. Third level of Vimshottari dasha proportions."},"kpNumber":{"type":"number","example":45,"description":"KP horary number (1-249)"},"retrograde":{"type":"boolean","example":false,"description":"Whether planet is in retrograde motion"}},"required":["planet","longitude","sign","signLord","nakshatra","nakshatraNumber","nakshatraLord","pada","starLord","subLord","subSubLord","kpNumber","retrograde"]}}},"required":["ayanamsa","planets"]},"KPPlanetsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST) for Vedic astrology.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula (most common for KP). \"kp-old\" uses the Krishnamurti original table. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa, about 1.45 degrees below Lahiri. \"custom\" allows providing your own value via ayanamsaValue. Defaults to \"kp-newcomb\"."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]},"KPCuspsResponse":{"type":"object","properties":{"ayanamsa":{"type":"number","example":24,"description":"Applied ayanamsa value in degrees"},"houseSystem":{"type":"string","example":"placidus","description":"House system used for calculations"},"cusps":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","example":1,"description":"House number (1-12)"},"longitude":{"type":"number","example":89.45,"description":"Cusp longitude in degrees (0-360)"},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign of the cusp"},"signLord":{"type":"string","example":"Moon","description":"Rashi lord (sign ruler) of this cusp. In KP, the cusp sign lord is a significator for this house."},"nakshatra":{"type":"string","example":"Ashlesha","description":"Nakshatra (lunar mansion) at this cusp degree. The cusp nakshatra lord and sublord together determine the houses complete significator chain."},"nakshatraLord":{"type":"string","example":"Mercury","description":"Nakshatra lord (star ruler) of the cusp. One of 9 Vimshottari dasha lords. Determines which planet activates this cusp in KP predictions."},"pada":{"type":"number","example":3,"description":"Nakshatra pada/quarter (1-4)"},"starLord":{"type":"string","example":"Mercury","description":"Star-lord (nakshatra lord)"},"subLord":{"type":"string","example":"Venus","description":"Sub-lord based on KP 249-level subdivision"},"subSubLord":{"type":"string","example":"Mars","description":"Sub-sub lord (SSL) based on 2241-level KP subdivision. Third level of Vimshottari dasha proportions."},"kpNumber":{"type":"number","example":32,"description":"KP horary number (1-249)"}},"required":["house","longitude","sign","signLord","nakshatra","nakshatraLord","pada","starLord","subLord","subSubLord","kpNumber"]}},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["ayanamsa","houseSystem","cusps","houseThemes","focus"]},"KPCuspsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST) for Vedic astrology.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula (most common for KP). \"kp-old\" uses the Krishnamurti original table. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa, about 1.45 degrees below Lahiri. \"custom\" allows providing your own value via ayanamsaValue. Defaults to \"kp-newcomb\"."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"KPChartResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format used for this KP chart calculation."},"time":{"type":"string","example":"10:12:00","description":"Birth time in HH:MM:SS format used for Lagna and Placidus cusp calculations."},"latitude":{"type":"number","example":28.6139,"description":"Birth location latitude in decimal degrees. Determines Placidus house cusps and Ascendant."},"longitude":{"type":"number","example":77.209,"description":"Birth location longitude in decimal degrees. Affects local sidereal time for house calculations."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in decimal hours used for time conversion."},"ayanamsa":{"type":"number","example":23.63165599,"description":"KP Newcomb ayanamsa value in degrees. Precession correction applied to convert tropical to sidereal positions."},"ayanamsaType":{"type":"string","example":"kp-newcomb","description":"Ayanamsa system used, echoing the ayanamsa field of the request: \"kp-newcomb\", \"kp-old\", \"lahiri\", \"raman\" or \"custom\"."},"houseSystem":{"type":"string","example":"placidus","description":"House system used (Placidus, standard for KP astrology)."}},"required":["date","time","latitude","longitude","timezone","ayanamsa","ayanamsaType","houseSystem"],"description":"Chart metadata including birth data, ayanamsa, and house system."},"ascendant":{"type":"object","properties":{"longitude":{"type":"number","example":138.4755,"description":"Sidereal longitude of Ascendant (Lagna) in degrees."},"sign":{"type":"string","example":"Leo","description":"Zodiac sign of the Ascendant."},"signLord":{"type":"string","example":"Sun","description":"Ruling planet of the Ascendant sign (the rashi lord). In KP this is the weakest of the four lords, ranked below the star lord and sub lord, but it still sets the broad temperament of the Lagna."},"nakshatra":{"type":"string","example":"Purva Phalguni","description":"Nakshatra (star) of the Ascendant."},"nakshatraLord":{"type":"string","example":"Venus","description":"Lord of the Ascendant nakshatra."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (1-4) of the Ascendant."},"starLord":{"type":"string","example":"Venus","description":"KP star lord of the Ascendant position."},"subLord":{"type":"string","example":"Rahu","description":"KP sub lord of the Ascendant. crucial for KP predictions. The Ascendant sub lord determines overall life promise."},"subSubLord":{"type":"string","example":"Jupiter","description":"KP sub-sub lord (SSL) of the Ascendant. Third level of the Vimshottari subdivision hierarchy, used for fine-tuning predictions."},"kpNumber":{"type":"number","example":95,"description":"KP number (1-249) for the Ascendant degree."}},"required":["longitude","sign","signLord","nakshatra","nakshatraLord","pada","starLord","subLord","subSubLord","kpNumber"],"description":"Ascendant (Lagna) details with full KP stellar hierarchy."},"cusps":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","example":7,"description":"House number (1-12)."},"longitude":{"type":"number","example":318.4755,"description":"Placidus cusp longitude in sidereal degrees."},"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign at the cusp."},"signLord":{"type":"string","example":"Saturn","description":"Lord of the zodiac sign at the cusp (house owner)."},"nakshatra":{"type":"string","example":"Shatabhisha","description":"Nakshatra at the cusp degree."},"nakshatraLord":{"type":"string","example":"Rahu","description":"Lord of the nakshatra at the cusp."},"pada":{"type":"number","example":4,"description":"Nakshatra pada (1-4) at the cusp."},"starLord":{"type":"string","example":"Rahu","description":"KP star lord of the cusp."},"subLord":{"type":"string","example":"Moon","description":"KP sub lord of the cusp. the deciding factor for house-level predictions in KP astrology."},"subSubLord":{"type":"string","example":"Jupiter","description":"KP sub-sub lord (SSL) of the cusp. Third level of Vimshottari subdivision for fine-grained cusp analysis."},"kpNumber":{"type":"number","example":215,"description":"KP number (1-249) for the cusp degree."}},"required":["house","longitude","sign","signLord","nakshatra","nakshatraLord","pada","starLord","subLord","subSubLord","kpNumber"]},"description":"All 12 Placidus house cusps with KP stellar hierarchy. Cusp sub lords are the primary predictive tool in KP astrology."},"planets":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Venus","description":"Planet name (Sun through Saturn, 7 visible planets)."},"longitude":{"type":"number","example":47.2732,"description":"Sidereal longitude in degrees (KP ayanamsa corrected)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign the planet occupies."},"house":{"type":"number","example":9,"description":"House number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","example":"Rohini","description":"Nakshatra the planet occupies."},"nakshatraLord":{"type":"string","example":"Moon","description":"Nakshatra lord (same as star lord)."},"pada":{"type":"number","example":3,"description":"Nakshatra pada (1-4)."},"starLord":{"type":"string","example":"Moon","description":"KP star lord, determines primary house signification."},"subLord":{"type":"string","example":"Saturn","description":"KP sub lord, the decisive factor. Planet gives results of the houses signified by its sub lord."},"subSubLord":{"type":"string","example":"Rahu","description":"KP sub-sub lord (SSL) of the planet. Third level of Vimshottari subdivision for precise timing analysis."},"kpNumber":{"type":"number","example":32,"description":"KP number (1-249)."},"retrograde":{"type":"boolean","example":false,"description":"True if planet is retrograde. Retrograde planets may delay or deny results in KP system."}},"required":["planet","longitude","sign","house","nakshatra","nakshatraLord","pada","starLord","subLord","subSubLord","kpNumber","retrograde"]},"description":"Positions of all 7 visible planets with complete KP stellar breakdown."},"nodes":{"type":"object","properties":{"rahu":{"type":"object","properties":{"longitude":{"type":"number","example":285.0726,"description":"Sidereal longitude of Rahu (North Node)."},"sign":{"type":"string","example":"Capricorn","description":"Zodiac sign Rahu occupies."},"house":{"type":"number","example":5,"description":"Occupied house number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","example":"Shravana","description":"Nakshatra of Rahu."},"starLord":{"type":"string","example":"Moon","description":"KP star lord of Rahu."},"subLord":{"type":"string","example":"Jupiter","description":"KP sub lord of Rahu."},"subSubLord":{"type":"string","example":"Sun","description":"KP sub-sub lord (SSL) of Rahu."},"kpNumber":{"type":"number","example":193,"description":"KP number (1-249) locating Rahu in the 249-division sub-lord scheme. Each of the 249 divisions maps to a unique sign, star lord and sub lord triple, so one integer pins the position precisely enough for KP event timing."}},"required":["longitude","sign","house","nakshatra","starLord","subLord","subSubLord","kpNumber"],"description":"Rahu (North Lunar Node), shadow planet, always retrograde, acts as agent of its sign lord and star lord."},"ketu":{"type":"object","properties":{"longitude":{"type":"number","example":105.0726,"description":"Sidereal longitude of Ketu (South Node). Always 180 degrees from Rahu."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign Ketu occupies."},"house":{"type":"number","example":11,"description":"Occupied house number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","example":"Pushya","description":"Nakshatra of Ketu."},"starLord":{"type":"string","example":"Saturn","description":"KP star lord of Ketu."},"subLord":{"type":"string","example":"Jupiter","description":"KP sub lord of Ketu."},"subSubLord":{"type":"string","example":"Jupiter","description":"KP sub-sub lord (SSL) of Ketu."},"kpNumber":{"type":"number","example":72,"description":"KP number (1-249) locating Ketu in the 249-division sub-lord scheme. Each of the 249 divisions maps to a unique sign, star lord and sub lord triple, so one integer pins the position precisely enough for KP event timing."}},"required":["longitude","sign","house","nakshatra","starLord","subLord","subSubLord","kpNumber"],"description":"Ketu (South Lunar Node), shadow planet, spiritual karmic indicator."}},"required":["rahu","ketu"],"description":"Lunar nodes (Rahu and Ketu) with KP stellar hierarchy. Nodes are powerful agents that amplify the significations of their dispositors."},"significators":{"type":"object","properties":{"houseWise":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","example":7,"description":"House number 1-12"},"significators":{"type":"array","items":{"type":"object","properties":{"level":{"type":"number","example":1,"description":"KP significator strength level (1-4). L1: planets in star of occupant (strongest). L2: occupant itself. L3: planets in star of owner. L4: sign owner. Lower number = stronger signification for this house."},"description":{"type":"string","example":"Planets in star of occupant","description":"Human-readable label for this KP significator level."},"planets":{"type":"array","items":{"type":"string"},"example":["Venus","Mars"],"description":"Planets signifying this house at this strength level."}},"required":["level","description","planets"]}},"all":{"type":"array","items":{"type":"string"},"example":["Venus","Mars","Jupiter"],"description":"All significators in order of strength"}},"required":["house","significators","all"]}},"planetWise":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Venus","description":"Vedic graha (planet) being analyzed for its house significations."},"signifies":{"type":"array","items":{"type":"object","properties":{"level":{"type":"number","example":1,"description":"KP significator strength level (1-4). L1 strongest, L4 weakest."},"houses":{"type":"array","items":{"type":"number"},"example":[7,2],"description":"House numbers this planet signifies at this strength level."}},"required":["level","houses"]}},"allHouses":{"type":"array","items":{"type":"number"},"example":[7,2,11],"description":"All houses signified in order of strength"}},"required":["planet","signifies","allHouses"]}}},"required":["houseWise","planetWise"],"description":"KP significators for event prediction and timing. Shows which planets signify each house (house-wise) and which houses each planet signifies (planet-wise). Strength order: Level 1 (planets in star of occupant) > Level 2 (occupants) > Level 3 (planets in star of owner) > Level 4 (house owner)."},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["meta","ascendant","cusps","planets","nodes","significators","houseThemes","focus"]},"KPChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. CRITICAL for accurate Lagna and house calculations."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST) for Vedic astrology.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula (most common for KP). \"kp-old\" uses the Krishnamurti original table. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa, about 1.45 degrees below Lahiri. \"custom\" allows providing your own value via ayanamsaValue. Defaults to \"kp-newcomb\"."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]},"KPRulingPlanetsResponse":{"type":"object","properties":{"datetime":{"type":"string","example":"2025-01-15T10:30:00.000Z","description":"Calculation datetime (ISO 8601)"},"location":{"type":"object","properties":{"latitude":{"type":"number","example":28.6139,"description":"Observer latitude in decimal degrees, echoed back from the request. Sets the local sidereal time behind the KP ascendant and therefore the Lagna sublord."},"longitude":{"type":"number","example":77.209,"description":"Observer longitude in decimal degrees, echoed back from the request. East is positive, west is negative."},"timezone":{"type":"number","example":5.5,"description":"Numeric UTC offset in decimal hours the calculation consumed. An IANA name sent on the request is resolved to its DST-correct offset upstream, so this is always a number."}},"required":["latitude","longitude","timezone"],"description":"Observer location coordinates"},"dayLord":{"type":"string","example":"Mercury","description":"Lord of the weekday (Sun=Sunday through Saturn=Saturday)"},"moonSignLord":{"type":"string","example":"Jupiter","description":"Lord of the zodiac sign where Moon is placed"},"moonStarLord":{"type":"string","example":"Saturn","description":"Lord of the nakshatra where Moon is placed"},"moonSublord":{"type":"string","example":"Mercury","description":"Sub-lord of the KP division where Moon is placed"},"moonSubSublord":{"type":"string","example":"Venus","description":"Sub-sub lord (SSL) of the KP division where Moon is placed"},"lagnaSignLord":{"type":"string","example":"Venus","description":"Lord of the rising zodiac sign (Ascendant)"},"lagnaStarLord":{"type":"string","example":"Mercury","description":"Lord of the nakshatra where Ascendant falls"},"lagnaSublord":{"type":"string","example":"Jupiter","description":"Sub-lord of the KP division where Ascendant falls"},"lagnaSubSublord":{"type":"string","example":"Saturn","description":"Sub-sub lord (SSL) of the KP division where Ascendant falls"},"rulingPlanets":{"type":"array","items":{"type":"string"},"example":["Mercury","Saturn","Jupiter","Venus"],"description":"Unique ruling planets in order of strength. Strongest planet appears first."},"significators":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mercury","description":"Planet abbreviation."},"signifies":{"type":"array","items":{"type":"number"},"example":[1,3,8,9],"description":"Houses this planet signifies, ordered by KP 4-level strength: L1 (planet in star of occupant, strongest), L2 (planet occupies), L3 (planet in star of owner), L4 (planet owns). First element is the strongest signification, not the occupied house."}},"required":["planet","signifies"]},"example":[{"planet":"Mercury","signifies":[1,3,8,9]},{"planet":"Saturn","signifies":[1,4,5,10]}],"description":"Houses signified by each ruling planet (only when birthDate and birthTime provided). Based on 4-level KP significator hierarchy from birth chart."},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["datetime","location","dayLord","moonSignLord","moonStarLord","moonSublord","moonSubSublord","lagnaSignLord","lagnaStarLord","lagnaSublord","lagnaSubSublord","rulingPlanets"]},"KPRulingPlanetsIntervalResponse":{"type":"object","properties":{"startDatetime":{"type":"string","example":"2026-02-03T00:00:00Z","description":"Start of the KP ruling planets interval range (ISO 8601)."},"endDatetime":{"type":"string","example":"2026-02-03T01:00:00Z","description":"End of the KP ruling planets interval range (ISO 8601)."},"intervalMinutes":{"type":"number","example":5,"description":"Time gap between consecutive ruling planet calculations in minutes."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":17.385044,"description":"Observer latitude used for Placidus house and Lagna (Ascendant) calculation."},"longitude":{"type":"number","example":78.486671,"description":"Observer longitude used for local sidereal time and Ascendant degree."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset applied to output times and sunrise-based Day Lord calculation."}},"required":["latitude","longitude","timezone"],"description":"Observer location coordinates used for erecting the Placidus prashna chart at each interval."},"totalIntervals":{"type":"number","example":13,"description":"Total number of intervals returned"},"intervals":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-02-03","description":"UTC date for this interval (YYYY-MM-DD)."},"time":{"type":"string","example":"00:00","description":"UTC time for this interval (HH:MM, 24-hour)."},"datetime":{"type":"string","example":"2026-02-03T00:00:00.000Z","description":"Full ISO 8601 timestamp for this interval."},"dayLord":{"type":"string","example":"Moon","description":"Ruling planet of the weekday based on Hindu sunrise Vara. Changes at local sunrise, not midnight."},"moonSignLord":{"type":"string","example":"Sun","description":"Lord of the zodiac sign (rashi) where Moon is placed at this moment."},"moonStarLord":{"type":"string","example":"Ketu","description":"Lord of the nakshatra (star, 1 of 27) where Moon is placed. Follows Vimshottari dasha sequence."},"moonSublord":{"type":"string","example":"Moon","description":"KP sublord of Moons exact position within the nakshatra subdivision (1 of 249)."},"moonSubSublord":{"type":"string","example":"Venus","description":"KP sub-sublord (SSL) of Moons position. Finest subdivision for precise timing."},"lagnaSignLord":{"type":"string","example":"Jupiter","description":"Lord of the Ascendant (Lagna) zodiac sign. Changes roughly every 2 hours as houses rotate."},"lagnaStarLord":{"type":"string","example":"Sun","description":"Lord of the nakshatra where the Ascendant degree falls."},"lagnaSublord":{"type":"string","example":"Venus","description":"KP sublord of the Ascendant degree. Changes every few minutes. key for birth time rectification."},"lagnaSubSublord":{"type":"string","example":"Rahu","description":"KP sub-sublord of the Ascendant. Most granular level for pinpointing exact moments."},"rulingPlanets":{"type":"array","items":{"type":"string"},"example":["Sun","Jupiter","Ketu","Moon"],"description":"Unique set of ruling planets derived from Day Lord, Moon Sign/Star Lords, and Lagna Sign/Star Lords. In KP astrology, events manifest when dasha/transit planets match these ruling planets."},"significators":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Ruling planet name."},"signifies":{"type":"array","items":{"type":"number"},"example":[3,1],"description":"Unique house numbers this planet signifies, ordered by strength. Uses 4-level KP hierarchy: Level 1 (strongest) planets in star of occupant, Level 2 occupants, Level 3 planets in star of owner, Level 4 owner."}},"required":["planet","signifies"]},"description":"KP significators for each ruling planet calculated from this moments Placidus chart. Shows which houses (1-12) each ruling planet signifies right now. Significators change as the Ascendant rotates through signs."},"moonSignLordSignifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown for the Moon Sign Lord planet. Shows which houses the Moon rashi lord activates at this moment, broken down by strength tier."},"moonStarLordSignifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown for the Moon Star Lord (nakshatra lord) planet. The star lord determines the nature of results Moon delivers."},"moonSublordSignifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown for the Moon Sub Lord planet. The sub lord determines whether Moon-related events will manifest."},"moonSignifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown for Moon itself. Shows which bhavas Moon directly activates based on its position and star lord in the current moment chart."}},"required":["date","time","datetime","dayLord","moonSignLord","moonStarLord","moonSublord","moonSubSublord","lagnaSignLord","lagnaStarLord","lagnaSublord","lagnaSubSublord","rulingPlanets","significators","moonSignLordSignifies","moonStarLordSignifies","moonSublordSignifies","moonSignifies"]},"description":"Ruling planets with significators at each interval"},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["startDatetime","endDatetime","intervalMinutes","location","totalIntervals","intervals","houseThemes","focus"]},"KPSublordChangesResponse":{"type":"object","properties":{"planet":{"type":"string","example":"Moon","description":"Vedic graha tracked for KP sublord transitions across the 249-division zodiac."},"startDate":{"type":"string","example":"2025-01-01","description":"Beginning of the sublord change search range (YYYY-MM-DD)."},"endDate":{"type":"string","example":"2025-01-31","description":"End of the sublord change search range (YYYY-MM-DD)."},"totalChanges":{"type":"number","example":42,"description":"Total Krishnamurti sublord transitions detected. Moon crosses ~14 sublords per day due to its fast motion."},"changes":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-01-15","description":"Date of the sublord boundary crossing (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"13:53","description":"Precise sublord transition time (HH:MM, 24-hour). Refined via binary search to ~1 minute accuracy. Adjusted to requested timezone."},"datetime":{"type":"string","example":"2025-01-15T13:53:00","description":"Full datetime of the KP sublord change. Adjusted to requested timezone for prashna kundali timing."},"fromKp":{"type":"number","example":45,"description":"Previous KP number (1-249) in the Vimshottari-based zodiac subdivision the planet occupied."},"toKp":{"type":"number","example":46,"description":"New KP number (1-249) the planet enters. Each number maps to a unique star lord and sublord combination."},"fromSublord":{"type":"string","example":"Mercury","description":"KP sublord planet before transition. The sublord determines whether an event signified by the star lord will manifest."},"toSublord":{"type":"string","example":"Ketu","description":"New KP sublord planet after transition. A change in sublord shifts the houses signified by the tracked planet."},"fromNakshatraLord":{"type":"string","example":"Mars","description":"Nakshatra lord (star lord) before transition. Follows the Vimshottari dasha sequence of 9 planets."},"toNakshatraLord":{"type":"string","example":"Mars","description":"Nakshatra lord after transition. Changes only when the planet crosses a nakshatra boundary (every 13d20m)."}},"required":["date","time","datetime","fromKp","toKp","fromSublord","toSublord","fromNakshatraLord","toNakshatraLord"]},"description":"Chronological list of KP sublord boundary crossings. Each entry marks when the tracked graha moves from one Krishnamurti subdivision to the next in the 249-part zodiac."}},"required":["planet","startDate","endDate","totalChanges","changes"]},"KPSublordChangesRequest":{"type":"object","properties":{"planet":{"type":"string","example":"Moon","description":"Planet to track (case-insensitive). Valid values: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn"},"startDate":{"type":"string","format":"date","example":"2025-01-01","description":"Start date for sublord change search (YYYY-MM-DD format)"},"endDate":{"type":"string","format":"date","example":"2025-01-31","description":"End date for sublord change search (YYYY-MM-DD format)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC. IANA resolved to the DST-correct offset for startDate. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, the most common choice for KP astrology. \"kp-old\" uses the Krishnamurti original table from KP Reader-1 with constant precession rate. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa, matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa from Hindu Predictive Astrology, a recognised traditional school that sits about 1.45 degrees below Lahiri. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["planet","startDate","endDate"]},"KPRasiChangesResponse":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Vedic graha being tracked for rasi parivartan (sign ingress) events."},"startDate":{"type":"string","example":"2025-01-01","description":"Beginning of the rasi change search range (YYYY-MM-DD)."},"endDate":{"type":"string","example":"2025-12-31","description":"End of the rasi change search range (YYYY-MM-DD)."},"totalChanges":{"type":"number","example":12,"description":"Total rasi parivartan events detected in the date range. Moon averages 12-13 per month, Sun once per month."},"changes":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-01-14","description":"Date of the rasi ingress event (YYYY-MM-DD). Adjusted to requested timezone for local panchang use."},"time":{"type":"string","example":"08:00","description":"Precise ingress time (HH:MM, 24-hour). Calculated via binary search refinement to ~1 minute accuracy. Adjusted to requested timezone."},"datetime":{"type":"string","example":"2025-01-14T08:00:00","description":"Full rasi parivartan datetime. Adjusted to requested timezone for transit calendar integration."},"fromSign":{"type":"string","example":"Sagittarius","description":"Zodiac sign (rashi) the planet is leaving. One of 12 sidereal signs using KP ayanamsa."},"fromSignLord":{"type":"string","example":"Jupiter","description":"Rashi lord (planetary ruler) of the departing sign. Determines the Vimshottari dasha connection."},"toSign":{"type":"string","example":"Capricorn","description":"New zodiac sign entered by the planet. Marks the beginning of a new transit phase in Vedic gochar analysis."},"toSignLord":{"type":"string","example":"Saturn","description":"Rashi lord of the newly entered sign. Key for KP significator analysis and dasha-transit matching."}},"required":["date","time","datetime","fromSign","fromSignLord","toSign","toSignLord"]},"description":"Chronological list of rasi parivartan (zodiac sign change) events with precise ingress timestamps. Each entry marks when the tracked graha crosses a 30-degree sign boundary."}},"required":["planet","startDate","endDate","totalChanges","changes"]},"KPRasiChangesRequest":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Planet to track (case-insensitive). Valid values: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn"},"startDate":{"type":"string","format":"date","example":"2025-01-01","description":"Start date for sign ingress search (YYYY-MM-DD format)"},"endDate":{"type":"string","format":"date","example":"2025-12-31","description":"End date for sign ingress search (YYYY-MM-DD format)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC. IANA resolved to the DST-correct offset for startDate. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, the most common choice for KP astrology. \"kp-old\" uses the Krishnamurti original table from KP Reader-1 with constant precession rate. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa, matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa from Hindu Predictive Astrology, a recognised traditional school that sits about 1.45 degrees below Lahiri. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["planet","startDate","endDate"]},"KPPlanetsIntervalResponse":{"type":"object","properties":{"startDatetime":{"type":"string","example":"2025-01-15T00:00:00Z","description":"Start of the KP ephemeris interval range (ISO 8601)."},"endDatetime":{"type":"string","example":"2025-01-15T23:59:00Z","description":"End of the KP ephemeris interval range (ISO 8601)."},"intervalMinutes":{"type":"number","example":60,"description":"Time gap between consecutive planetary snapshots in minutes. Determines the granularity of the KP transit table."},"totalIntervals":{"type":"number","example":24,"description":"Total number of time points calculated (inclusive of both start and end)."},"ayanamsa":{"type":"string","example":"kp-newcomb","description":"Ayanamsa system used for this calculation. \"kp-newcomb\" = KP-Newcomb (dynamic), \"kp-old\" = Krishnamurti original (constant rate), \"lahiri\" = Lahiri/Chitrapaksha."},"ayanamsaValue":{"type":"number","example":24.2223,"description":"Ayanamsa value in degrees used for sidereal conversion. Verify this against your reference source to confirm correct ayanamsa is applied."},"intervals":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-01-15","description":"Date for this data point (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"00:00","description":"Time for this data point (HH:MM). Adjusted to requested timezone."},"datetime":{"type":"string","example":"2025-01-15T00:00:00","description":"Full datetime for this data point. Adjusted to requested timezone."},"planets":{"type":"object","additionalProperties":{"type":"object","properties":{"longitude":{"type":"number","example":270.5432,"description":"Sidereal longitude in degrees (0-360) using KP ayanamsa. The primary coordinate for all KP sublord lookups."},"degreeInSign":{"type":"number","example":0.5432,"description":"Degree within the current rashi (0-30). Useful for gauging how far into a sign the planet has progressed."},"sign":{"type":"string","example":"Capricorn","description":"Sidereal zodiac sign (rashi) the planet occupies at this interval."},"signLord":{"type":"string","example":"Saturn","description":"Rashi lord (sign ruler). First level of the KP significator hierarchy. Its house ownership determines L4 significations for this planet."},"nakshatra":{"type":"string","example":"Shravana","description":"Nakshatra (lunar mansion) the planet occupies. One of 27 Vedic nakshatras spanning 13 degrees 20 minutes each."},"nakshatraLord":{"type":"string","example":"Moon","description":"Star lord (nakshatra ruler) from Vimshottari dasha sequence. Determines the nature of results this planet delivers. Its occupied and owned houses become L1 and L3 significations."},"sublord":{"type":"string","example":"Venus","description":"KP sublord within the 249-part zodiac division. The deciding factor in KP predictions. An event manifests only if the sublord signifies the relevant house."},"subSublord":{"type":"string","example":"Jupiter","description":"KP sub-sublord (SSL). Third level of Vimshottari subdivision (2,241 divisions). Refines timing within the sublord period for precise event prediction."},"kpNumber":{"type":"number","example":154,"description":"KP number (1-249) identifying the exact Vimshottari subdivision. Each number maps to a unique star lord and sublord combination."},"isRetrograde":{"type":"boolean","example":false,"description":"True if the planet is in retrograde (vakri) motion. Rahu and Ketu are always retrograde. Retrograde planets deliver results differently in KP analysis."}},"required":["longitude","degreeInSign","sign","signLord","nakshatra","nakshatraLord","sublord","subSublord","kpNumber","isRetrograde"]},"description":"Planet positions keyed by planet name (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu)"}},"required":["date","time","datetime","planets"]},"description":"Array of planetary snapshots at each time interval"}},"required":["startDatetime","endDatetime","intervalMinutes","totalIntervals","ayanamsa","ayanamsaValue","intervals"]},"KPPlanetsIntervalRequest":{"type":"object","properties":{"startDatetime":{"type":"string","format":"date-time","example":"2025-01-15T00:00:00Z","description":"Start datetime in ISO 8601 (YYYY-MM-DDTHH:MM:SS). Interpreted as local time when a non-zero timezone is provided (a trailing Z is accepted but ignored); with timezone 0 it is UTC."},"endDatetime":{"type":"string","format":"date-time","example":"2025-01-15T23:59:00Z","description":"End datetime in ISO 8601 (YYYY-MM-DDTHH:MM:SS). Maximum 7 days from start. Interpreted as local time when a non-zero timezone is provided (a trailing Z is accepted but ignored); with timezone 0 it is UTC."},"intervalMinutes":{"type":"number","minimum":15,"maximum":1440,"example":60,"description":"Time between calculations in minutes. Range: 15 (quarter-hourly) to 1440 (daily)."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Observer latitude in decimal degrees (for future Lagna calculations)"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Observer longitude in decimal degrees (for future Lagna calculations)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC. IANA resolved to the DST-correct offset for the startDatetime date. When non-zero, all datetimes are treated as local time in this timezone (Z suffix is ignored). Defaults to 0 (UTC).","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, the most common choice for KP astrology. \"kp-old\" uses the Krishnamurti original table from KP Reader-1 with constant precession rate. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa, matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa from Hindu Predictive Astrology, a recognised traditional school that sits about 1.45 degrees below Lahiri. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["startDatetime","endDatetime","intervalMinutes","latitude","longitude"]},"KPHoraryResponse":{"type":"object","properties":{"horaryNumber":{"type":"integer","example":108,"description":"The number that was asked for, echoed so a stored chart is self describing."},"questionTime":{"type":"string","example":"2026-03-08T09:00:00.000Z","description":"UTC instant the chart was cast for, resolved from the date, time and timezone."},"ayanamsaType":{"type":"string","example":"kp-newcomb","description":"Sidereal frame used, echoed back."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees subtracted from every tropical longitude to produce this chart. Compare it against your reference software before treating a placement difference as a disagreement."},"ascendant":{"type":"object","properties":{"longitude":{"type":"number","example":154,"description":"Sidereal longitude of the horary Ascendant, taken as the MIDPOINT of the sub division the number names."},"degreeInSign":{"type":"number","example":4,"description":"Degrees into the sign, 0 to 30, which is what a chart displays."},"sign":{"type":"string","example":"Virgo","description":"Zodiac sign (rashi) of this point."},"star":{"type":"string","example":"Uttara Phalguni","description":"Nakshatra (star) this point falls in."},"starLord":{"type":"string","example":"Sun","description":"Nakshatra lord (star lord), the second level of the KP hierarchy."},"subLord":{"type":"string","example":"Saturn","description":"Sub lord, the decisive level in KP. A cusp sub lord is what answers the question: it is read for whether the matter is promised, before any timing is attempted."},"kpNumber":{"type":"integer","example":108,"description":"KP horary number 1 to 249 of the sub division holding this point. Matches the standard published KP table."},"spanFrom":{"type":"number","example":153,"description":"Sidereal longitude where this numbered sub division begins."},"spanTo":{"type":"number","example":155.1111,"description":"Sidereal longitude where it ends. The Ascendant sits midway between this and spanFrom."}},"required":["longitude","degreeInSign","sign","star","starLord","subLord","kpNumber","spanFrom","spanTo"],"description":"The Ascendant the horary number produced. This is the ONLY part of the chart that comes from the number; everything else comes from the sky at the moment of the question."},"cusps":{"type":"array","items":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House (bhava) number 1 to 12."},"longitude":{"type":"number","example":210.44,"description":"Sidereal longitude of the cusp."},"sign":{"type":"string","example":"Virgo","description":"Zodiac sign (rashi) of this point."},"star":{"type":"string","example":"Uttara Phalguni","description":"Nakshatra (star) this point falls in."},"starLord":{"type":"string","example":"Sun","description":"Nakshatra lord (star lord), the second level of the KP hierarchy."},"subLord":{"type":"string","example":"Saturn","description":"Sub lord, the decisive level in KP. A cusp sub lord is what answers the question: it is read for whether the matter is promised, before any timing is attempted."},"kpNumber":{"type":"integer","example":108,"description":"KP horary number 1 to 249 of the sub division holding this point. Matches the standard published KP table."}},"required":["house","longitude","sign","star","starLord","subLord","kpNumber"],"description":"One Placidus cusp with its KP lords. The sub lord of the cusp relevant to the question is the value a KP practitioner reads first."},"description":"Twelve Placidus cusps, house 1 first. House 1 is the horary Ascendant; the other eleven follow from the house frame that Ascendant implies at this latitude."},"planets":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Graha name."},"longitude":{"type":"number","example":95.31,"description":"Sidereal longitude at the moment of the question."},"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"Placidus house the graha occupies in this horary chart, counted against the cusps above rather than by whole sign."},"isRetrograde":{"type":"boolean","example":false,"description":"Retrograde motion flag."},"subSubLord":{"type":"string","example":"Venus","description":"Sub-sub lord, the fourth KP level, used to refine timing."},"sign":{"type":"string","example":"Virgo","description":"Zodiac sign (rashi) of this point."},"star":{"type":"string","example":"Uttara Phalguni","description":"Nakshatra (star) this point falls in."},"starLord":{"type":"string","example":"Sun","description":"Nakshatra lord (star lord), the second level of the KP hierarchy."},"subLord":{"type":"string","example":"Saturn","description":"Sub lord, the decisive level in KP. A cusp sub lord is what answers the question: it is read for whether the matter is promised, before any timing is attempted."},"kpNumber":{"type":"integer","example":108,"description":"KP horary number 1 to 249 of the sub division holding this point. Matches the standard published KP table."}},"required":["planet","longitude","house","isRetrograde","subSubLord","sign","star","starLord","subLord","kpNumber"],"description":"One graha at the moment of the question, with its full KP hierarchy."},"description":"The nine grahas at the moment of the question, placed against the horary cusps. These come from the real sky, not from the number."},"rulingPlanets":{"type":"object","properties":{"dayLord":{"type":"string","example":"Sun","description":"Lord of the Hindu weekday, counted from sunrise."},"moonSignLord":{"type":"string","example":"Venus","description":"Sign lord of the Moon."},"moonStarLord":{"type":"string","example":"Rahu","description":"Star lord of the Moon."},"moonSublord":{"type":"string","example":"Jupiter","description":"Sub lord of the Moon."},"moonSubSublord":{"type":"string","example":"Saturn","description":"Sub-sub lord of the Moon."},"lagnaSignLord":{"type":"string","example":"Mercury","description":"Sign lord of the ascendant at the question moment."},"lagnaStarLord":{"type":"string","example":"Sun","description":"Star lord of that ascendant."},"lagnaSublord":{"type":"string","example":"Venus","description":"Sub lord of that ascendant."},"lagnaSubSublord":{"type":"string","example":"Mars","description":"Sub-sub lord of that ascendant."},"rulingPlanets":{"type":"array","items":{"type":"string"},"example":["Sun","Venus","Rahu","Mercury"],"description":"The distinct ruling planets in KP order of strength. They validate the chart: when they repeat the significators of the houses the question needs, the judgment is considered reliable."}},"required":["dayLord","moonSignLord","moonStarLord","moonSublord","moonSubSublord","lagnaSignLord","lagnaStarLord","lagnaSublord","lagnaSubSublord","rulingPlanets"],"description":"Ruling planets at the moment of the question. NOTE the lagna values here are from the TIME-based ascendant, which is the classical ruling-planet definition, not from the horary number."},"significators":{"type":"object","properties":{"houseWise":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","example":7,"description":"House number 1-12"},"significators":{"type":"array","items":{"type":"object","properties":{"level":{"type":"number","example":1,"description":"KP significator strength level (1-4). L1: planets in star of occupant (strongest). L2: occupant itself. L3: planets in star of owner. L4: sign owner. Lower number = stronger signification for this house."},"description":{"type":"string","example":"Planets in star of occupant","description":"Human-readable label for this KP significator level."},"planets":{"type":"array","items":{"type":"string"},"example":["Venus","Mars"],"description":"Planets signifying this house at this strength level."}},"required":["level","description","planets"]}},"all":{"type":"array","items":{"type":"string"},"example":["Venus","Mars","Jupiter"],"description":"All significators in order of strength"}},"required":["house","significators","all"]}},"planetWise":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Venus","description":"Vedic graha (planet) being analyzed for its house significations."},"signifies":{"type":"array","items":{"type":"object","properties":{"level":{"type":"number","example":1,"description":"KP significator strength level (1-4). L1 strongest, L4 weakest."},"houses":{"type":"array","items":{"type":"number"},"example":[7,2],"description":"House numbers this planet signifies at this strength level."}},"required":["level","houses"]}},"allHouses":{"type":"array","items":{"type":"number"},"example":[7,2,11],"description":"All houses signified in order of strength"}},"required":["planet","signifies","allHouses"]}}},"required":["houseWise","planetWise"],"description":"KP significators for event prediction and timing. Shows which planets signify each house (house-wise) and which houses each planet signifies (planet-wise). Strength order: Level 1 (planets in star of occupant) > Level 2 (occupants) > Level 3 (planets in star of owner) > Level 4 (house owner)."},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["horaryNumber","questionTime","ayanamsaType","ayanamsaDegrees","ascendant","cusps","planets","rulingPlanets","significators","houseThemes","focus"],"description":"A complete KP horary (Prashna) chart: the Ascendant from the number, the cusps and planets from the moment of the question, plus ruling planets and four-level significators."},"KPHoraryRequest":{"type":"object","properties":{"horaryNumber":{"type":"integer","minimum":1,"maximum":249,"example":108,"description":"Horary number from 1 to 249, given by the querent while focused on their question. It maps to one of the 249 KP sub divisions of the zodiac, and that division sets the Ascendant of the chart. The querent should give the first number that comes to mind and use it once for that question; the astrologer never chooses it. Numbers outside 1 to 249 are rejected rather than wrapped, because a wrapped number would silently answer a different question."},"date":{"type":"string","format":"date","example":"2026-03-08","description":"Date the question was taken up for judgment, YYYY-MM-DD. Not a birth date: a horary chart needs no birth details at all, which is the point of the method."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Time the question was taken up for judgment, 24-hour HH:MM:SS. In KP practice this is the moment the astrologer receives and understands the question, not the moment the querent first thought of it. It sets every planetary position and all twelve cusps except the Ascendant."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":19.076,"description":"Latitude where the question is judged, decimal degrees. The house cusps are Placidus and therefore latitude dependent, so this is the place of judgment, not the querent birthplace."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":72.8777,"description":"Longitude where the question is judged, decimal degrees."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"Asia/Kolkata\") OR decimal hours from UTC. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula (most common for KP). \"kp-old\" uses the Krishnamurti original table. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa, about 1.45 degrees below Lahiri. \"custom\" allows providing your own value via ayanamsaValue. Defaults to \"kp-newcomb\"."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["horaryNumber","date","time","latitude","longitude"]},"RashiListResponse":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mesha","description":"Unique slug identifier for the rashi. Used in URL paths and cross-references."},"name":{"type":"string","example":"Aries","description":"Western zodiac sign name corresponding to this Vedic rashi."},"vedicName":{"type":"string","example":"Mesha","description":"Sanskrit name of the rashi as used in Vedic astrology (Jyotish)."},"dateRange":{"type":"string","example":"Apr 14th - May 14th","description":"Approximate sidereal date range when the Sun transits this rashi."},"symbol":{"type":"string","example":"Ram","description":"Traditional symbol associated with this zodiac sign."},"energy":{"type":"string","example":"Dhatr Aditya","description":"Aditya (solar deity) governing this rashi in Vedic tradition."},"characteristics":{"type":"string","example":"Creative, idealistic in nature, headstrong, good leader","description":"Key personality traits and behavioral tendencies of natives born under this rashi."}},"required":["id","name","vedicName","dateRange","symbol","energy","characteristics"]}},"RashiResponse":{"type":"object","properties":{"id":{"type":"string","example":"mesha","description":"Unique slug identifier for the rashi. Used in URL paths and cross-references."},"name":{"type":"string","example":"Aries","description":"Western zodiac sign name corresponding to this Vedic rashi."},"vedicName":{"type":"string","example":"Mesha","description":"Sanskrit name of the rashi as used in Vedic astrology (Jyotish)."},"dateRange":{"type":"string","example":"Apr 14th - May 14th","description":"Approximate sidereal date range when the Sun transits this rashi."},"symbol":{"type":"string","example":"Ram","description":"Traditional symbol associated with this zodiac sign."},"energy":{"type":"string","example":"Dhatr Aditya","description":"Aditya (solar deity) governing this rashi in Vedic tradition."},"characteristics":{"type":"string","example":"Creative, idealistic in nature, headstrong, good leader","description":"Key personality traits and behavioral tendencies of natives born under this rashi."}},"required":["id","name","vedicName","dateRange","symbol","energy","characteristics"]},"NakshatraListResponse":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ashwini","description":"Unique slug identifier for the nakshatra. Used in URL paths and cross-references."},"name":{"type":"string","example":"Ashwini","description":"Nakshatra name as used in Vedic astrology. One of 27 lunar mansions spanning 13 degrees 20 minutes each."},"number":{"type":"number","example":1,"description":"Sequential number (1-27) of this nakshatra in the zodiac starting from 0 degrees Aries."},"range":{"type":"string","example":"0 to 13 degrees 20 minutes Aries","description":"Sidereal longitude range this nakshatra occupies within its zodiac sign."},"lord":{"type":"string","example":"Ketu","description":"Ruling planet (nakshatra lord) used in Vimshottari dasha calculations. Determines the planetary period sequence."},"deity":{"type":"string","example":"Ashwini Kumaras (celestial healers)","description":"Presiding deity of the nakshatra. Influences the spiritual qualities and mythology associated with natives."},"symbol":{"type":"string","example":"Horse's Head","description":"Traditional symbol representing this nakshatra. Reflects its core nature and energy."},"characteristics":{"type":"string","example":"Energetic, pioneering, natural problem-solvers.","description":"Personality traits, behavioral tendencies, and life themes for natives born under this nakshatra."},"remedies":{"type":"object","properties":{"mantras":{"type":"string","example":"Chanting mantras dedicated to the Ashwini Kumaras can boost healing and vitality.","description":"Recommended mantras for this nakshatra to enhance positive qualities."},"gemstones":{"type":"string","example":"Cat's eye or garnet to harness Ketu's energy.","description":"Recommended gemstones aligned with the ruling planet of this nakshatra."},"rituals":{"type":"string","example":"Early morning meditation and engaging in acts of charity.","description":"Spiritual practices and daily rituals beneficial for natives of this nakshatra."}},"required":["mantras","gemstones","rituals"],"description":"Traditional Vedic remedies including mantras, gemstones, and rituals for this nakshatra."}},"required":["id","name","number","range","lord","deity","symbol","characteristics","remedies"]}},"NakshatraResponse":{"type":"object","properties":{"id":{"type":"string","example":"ashwini","description":"Unique slug identifier for the nakshatra. Used in URL paths and cross-references."},"name":{"type":"string","example":"Ashwini","description":"Nakshatra name as used in Vedic astrology. One of 27 lunar mansions spanning 13 degrees 20 minutes each."},"number":{"type":"number","example":1,"description":"Sequential number (1-27) of this nakshatra in the zodiac starting from 0 degrees Aries."},"range":{"type":"string","example":"0 to 13 degrees 20 minutes Aries","description":"Sidereal longitude range this nakshatra occupies within its zodiac sign."},"lord":{"type":"string","example":"Ketu","description":"Ruling planet (nakshatra lord) used in Vimshottari dasha calculations. Determines the planetary period sequence."},"deity":{"type":"string","example":"Ashwini Kumaras (celestial healers)","description":"Presiding deity of the nakshatra. Influences the spiritual qualities and mythology associated with natives."},"symbol":{"type":"string","example":"Horse's Head","description":"Traditional symbol representing this nakshatra. Reflects its core nature and energy."},"characteristics":{"type":"string","example":"Energetic, pioneering, natural problem-solvers.","description":"Personality traits, behavioral tendencies, and life themes for natives born under this nakshatra."},"remedies":{"type":"object","properties":{"mantras":{"type":"string","example":"Chanting mantras dedicated to the Ashwini Kumaras can boost healing and vitality.","description":"Recommended mantras for this nakshatra to enhance positive qualities."},"gemstones":{"type":"string","example":"Cat's eye or garnet to harness Ketu's energy.","description":"Recommended gemstones aligned with the ruling planet of this nakshatra."},"rituals":{"type":"string","example":"Early morning meditation and engaging in acts of charity.","description":"Spiritual practices and daily rituals beneficial for natives of this nakshatra."}},"required":["mantras","gemstones","rituals"],"description":"Traditional Vedic remedies including mantras, gemstones, and rituals for this nakshatra."}},"required":["id","name","number","range","lord","deity","symbol","characteristics","remedies"]},"UpagrahaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"timeBased":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Upagraha name. Time-based: Gulika, Mandi, Kala, Mrityu, Ardhaprahara, Yamaghantaka. Sun-based: Dhuma, Vyatipata, Parivesha, Indra Chapa, Upaketu.","example":"Gulika"},"longitude":{"type":"number","description":"Sidereal longitude in degrees (0 to 360). Used for house placement and aspect analysis.","example":168.13},"rashi":{"type":"string","description":"Zodiac sign (rashi) the upagraha occupies. One of 12 Vedic rashis from Aries to Pisces.","example":"Virgo"},"degreeInSign":{"type":"number","description":"Degree position within the occupied rashi (0 to 30).","example":18.13},"nakshatra":{"type":"string","description":"Nakshatra (lunar mansion) the upagraha occupies. One of 27 Vedic nakshatras.","example":"Chitra"},"nakshatraIndex":{"type":"number","description":"Nakshatra number (1 to 27). Ashwini = 1, Bharani = 2, through Revati = 27.","example":14},"nakshatraPada":{"type":"number","description":"Pada (quarter) within the nakshatra (1 to 4). Each pada spans 3 degrees 20 minutes.","example":3}},"required":["name","longitude","rashi","degreeInSign","nakshatra","nakshatraIndex","nakshatraPada"],"description":"Position details for a single upagraha (sub-planet)"},"description":"Time-based upagrahas derived from the 8-part division of day or night. Gulika and Mandi are from Saturn segment, others from Sun, Mars, Mercury, Jupiter segments. Positions depend on birth time, location, and weekday."},"sunBased":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Upagraha name. Time-based: Gulika, Mandi, Kala, Mrityu, Ardhaprahara, Yamaghantaka. Sun-based: Dhuma, Vyatipata, Parivesha, Indra Chapa, Upaketu.","example":"Gulika"},"longitude":{"type":"number","description":"Sidereal longitude in degrees (0 to 360). Used for house placement and aspect analysis.","example":168.13},"rashi":{"type":"string","description":"Zodiac sign (rashi) the upagraha occupies. One of 12 Vedic rashis from Aries to Pisces.","example":"Virgo"},"degreeInSign":{"type":"number","description":"Degree position within the occupied rashi (0 to 30).","example":18.13},"nakshatra":{"type":"string","description":"Nakshatra (lunar mansion) the upagraha occupies. One of 27 Vedic nakshatras.","example":"Chitra"},"nakshatraIndex":{"type":"number","description":"Nakshatra number (1 to 27). Ashwini = 1, Bharani = 2, through Revati = 27.","example":14},"nakshatraPada":{"type":"number","description":"Pada (quarter) within the nakshatra (1 to 4). Each pada spans 3 degrees 20 minutes.","example":3}},"required":["name","longitude","rashi","degreeInSign","nakshatra","nakshatraIndex","nakshatraPada"],"description":"Position details for a single upagraha (sub-planet)"},"description":"Sun-longitude-based upagrahas (Dhuma group). Pure arithmetic from the Sun sidereal position. Dhuma = Sun + 133d20m, then each derived from the previous."}},"required":["frame","timeBased","sunBased"],"description":"Complete upagraha positions for a birth chart"},"UpagrahaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"AshtakavargaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"bhinnashtakavarga":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","description":"Planet or Lagna name. Seven classical planets (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn) plus Lagna (Ascendant). Rahu and Ketu are excluded from Ashtakavarga per BPHS.","example":"Sun"},"bindus":{"type":"array","items":{"type":"number"},"description":"Benefic points (bindus) for each of the 12 signs, ordered Aries through Pisces (index 0 = Aries, index 11 = Pisces). Each value ranges from 0 to 8, representing how many of the 8 contributors (7 planets + Lagna) provide a benefic point for this planet in that sign. Higher bindus indicate stronger planetary support.","example":[4,3,2,1,4,6,6,6,4,3,5,4]},"total":{"type":"number","description":"Sum of bindus across all 12 signs. This total is constant per planet regardless of birth chart: Sun = 48, Moon = 49, Mars = 39, Mercury = 54, Jupiter = 56, Venus = 52, Saturn = 39, Lagna = 49. Useful as a validation checksum.","example":48}},"required":["planet","bindus","total"],"description":"Bhinnashtakavarga for a single planet or Lagna"},"description":"Individual planetary strength grids (Bhinnashtakavarga). Eight entries: one for each of the 7 classical planets plus Lagna. Each entry shows how many of the 8 contributors (7 planets + Lagna) give benefic points to that planet in each of the 12 signs."},"sarvashtakavarga":{"type":"object","properties":{"bindus":{"type":"array","items":{"type":"number"},"description":"Combined benefic points per sign from all 7 planets (Lagna excluded from SAV), ordered Aries through Pisces. Higher values indicate stronger signs for transit predictions and house strength analysis. Average is approximately 28 per sign.","example":[28,31,25,30,27,33,29,26,32,24,27,25]},"total":{"type":"number","description":"Sum of all SAV bindus across 12 signs. Always equals 337 for every birth chart. This mathematical constant serves as a validation checksum for the calculation.","example":337}},"required":["bindus","total"],"description":"Sarvashtakavarga (SAV) combining all 7 planetary Bhinnashtakavarga scores per sign. Total is always 337."},"reducedBhinnashtakavarga":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","description":"Planet or Lagna name. Seven classical planets (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn) plus Lagna (Ascendant). Rahu and Ketu are excluded from Ashtakavarga per BPHS.","example":"Sun"},"bindus":{"type":"array","items":{"type":"number"},"description":"Benefic points (bindus) for each of the 12 signs, ordered Aries through Pisces (index 0 = Aries, index 11 = Pisces). Each value ranges from 0 to 8, representing how many of the 8 contributors (7 planets + Lagna) provide a benefic point for this planet in that sign. Higher bindus indicate stronger planetary support.","example":[4,3,2,1,4,6,6,6,4,3,5,4]},"total":{"type":"number","description":"Sum of bindus across all 12 signs. This total is constant per planet regardless of birth chart: Sun = 48, Moon = 49, Mars = 39, Mercury = 54, Jupiter = 56, Venus = 52, Saturn = 39, Lagna = 49. Useful as a validation checksum.","example":48}},"required":["planet","bindus","total"],"description":"Bhinnashtakavarga for a single planet or Lagna"},"description":"Reduced Bhinnashtakavarga after two-step Shodhana (purification) per BPHS Ch. 67-68. Step 1: Trikona Shodhana subtracts minimum bindu among trine groups (1-5-9, 2-6-10, 3-7-11, 4-8-12). Step 2: Ekadipati Shodhana adjusts dual-lordship sign pairs (Mars: Aries/Scorpio, Venus: Taurus/Libra, Mercury: Gemini/Virgo, Jupiter: Sagittarius/Pisces, Saturn: Capricorn/Aquarius). Used as input for Shodhya Pinda planetary strength."},"reducedSarvashtakavarga":{"type":"object","properties":{"bindus":{"type":"array","items":{"type":"number"},"description":"Combined benefic points per sign from all 7 planets (Lagna excluded from SAV), ordered Aries through Pisces. Higher values indicate stronger signs for transit predictions and house strength analysis. Average is approximately 28 per sign.","example":[28,31,25,30,27,33,29,26,32,24,27,25]},"total":{"type":"number","description":"Sum of all SAV bindus across 12 signs. Always equals 337 for every birth chart. This mathematical constant serves as a validation checksum for the calculation.","example":337}},"required":["bindus","total"],"description":"Reduced Sarvashtakavarga. Sum of the 7 reduced planetary Bhinnashtakavarga values per sign (Lagna excluded). Indicates relative sign strength after Shodhana purification."},"shodhyaPinda":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","description":"Planet or Lagna name. Shodhya Pinda is calculated for all 7 classical planets plus Lagna.","example":"Sun"},"rashiPinda":{"type":"number","description":"Rashi Pinda component. Weighted sum of reduced Bhinnashtakavarga bindus per sign multiplied by Rashi Gunakar weights per BPHS Ch. 69. Higher values indicate stronger sign-based planetary strength.","example":123},"grahaPinda":{"type":"number","description":"Graha Pinda component. Weighted sum of reduced Bhinnashtakavarga bindus per sign multiplied by the Graha Gunakar of planets occupying each sign (Sun=5, Moon=5, Mars=8, Mercury=5, Jupiter=10, Venus=7, Saturn=5). Reflects planetary association strength.","example":79},"shodhyaPinda":{"type":"number","description":"Total Shodhya Pinda (Rashi Pinda + Graha Pinda). Primary planetary strength score derived from Ashtakavarga reduction. Used for comparing relative strength of planets in a birth chart and predicting dasha period results.","example":202}},"required":["planet","rashiPinda","grahaPinda","shodhyaPinda"],"description":"Shodhya Pinda strength values for a single planet, derived from Reduced Ashtakavarga per BPHS Ch. 69."},"description":"Shodhya Pinda planetary strength scores per BPHS Ch. 69. Derived from Reduced Ashtakavarga. Each entry contains Rashi Pinda (sign-weighted strength), Graha Pinda (planet-association-weighted strength), and total Shodhya Pinda. Used for comparing planetary strength, predicting dasha results, and transit analysis."},"signs":{"type":"array","items":{"type":"string","enum":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]},"description":"Sign names in order, for mapping bindus array indices to zodiac signs. Index 0 = Aries through index 11 = Pisces.","example":["Aries","Taurus","Gemini","Cancer","Leo","Virgo","Libra","Scorpio","Sagittarius","Capricorn","Aquarius","Pisces"]}},"required":["frame","bhinnashtakavarga","sarvashtakavarga","reducedBhinnashtakavarga","reducedSarvashtakavarga","shodhyaPinda","signs"],"description":"Complete Ashtakavarga analysis for a birth chart"},"AshtakavargaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"ShadbalaResponse":{"type":"object","properties":{"balaThemes":{"type":"object","properties":{"sthanaBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."},"digBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."},"kalaBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."},"chestaBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."},"naisargikaBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."},"drikBala":{"type":"object","properties":{"name":{"type":"string","example":"Positional strength","description":"Localized name of this Shadbala component, suitable for a table header or a bar label."},"meaning":{"type":"string","example":"Strength from the sign, divisional chart and house the graha occupies. Usually the largest of the six.","description":"One-line localized explanation of what this component measures."}},"required":["name","meaning"],"description":"Localized label and meaning for one Shadbala component."}},"required":["sthanaBala","digBala","kalaBala","chestaBala","naisargikaBala","drikBala"],"description":"Localized name and one-line meaning for each of the six Shadbala components, keyed by the same field names each planet entry uses. Join it to render a readable strength breakdown in any of the eight supported languages instead of showing six untranslated Sanskrit terms."},"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"planets":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","description":"Planet name. One of the 7 classical Vedic planets (Saptgraha): Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn. Rahu and Ketu are excluded from Shadbala per BPHS.","example":"Sun"},"sthanaBala":{"type":"number","description":"Sthana Bala (Positional Strength) in virupas. Sum of 5 sub-components: Uchcha Bala (exaltation strength), Saptavargaja Bala (7-divisional friendship), Ojayugma Bala (odd/even sign placement), Kendradi Bala (angular house strength), and Drekkana Bala (decanate gender match). Higher values indicate stronger positional placement.","example":168.4},"digBala":{"type":"number","description":"Dig Bala (Directional Strength) in virupas. Based on angular distance from the planets directional strength house. Sun and Mars are strong at MC (10th), Moon and Venus at IC (4th), Mercury and Jupiter at ASC (1st), Saturn at DSC (7th). Range 0 to 60.","example":6.43},"kalaBala":{"type":"number","description":"Kala Bala (Temporal Strength) in virupas. Sum of 8 sub-components: Nathonnatha (day/night strength), Paksha (lunar phase), Tribhaga (third of day/night), Vara (weekday lord), Hora (planetary hour), Abda (year lord), Masa (month lord), and Ayana (declination-based seasonal strength).","example":116.58},"chestaBala":{"type":"number","description":"Chesta Bala (Motional Strength) in virupas. Based on planetary motion, so a retrograde graha scores higher because it is closer to Earth and working hardest. The Sun uses its Ayana Bala and the Moon its elongation from the Sun, per BPHS. Mars, Mercury, Jupiter, Venus and Saturn use the Sheeghra Kendra, the arc between the sheeghrochcha and the mean of the true and mean longitudes, with the roles of the mean Sun and the graha swapped for Mercury and Venus. Range 0 to 60.","example":26.06},"naisargikaBala":{"type":"number","description":"Naisargika Bala (Natural Strength) in virupas. Fixed luminosity-based values per BPHS: Sun 60.00, Moon 51.43, Venus 42.86, Jupiter 34.29, Mercury 25.71, Mars 17.14, Saturn 8.57. Invariant across all charts.","example":60},"drikBala":{"type":"number","description":"Drik Bala (Aspectual Strength) in virupas. Strength gained or lost from the aspects a graha receives. Benefic aspects add strength and malefic aspects reduce it, so this value is negative when malefics dominate. Mercury counts as benefic or malefic by the company it keeps in its own sign, decided by count with the nearest graha breaking a tie, and the Moon by its paksha. Uses the graded Sputa Drishti curve of BPHS Ch. 26 with the Vishesha (special) aspects of Mars, Jupiter and Saturn applied at their precise DEGREE ranges rather than by whole sign.","example":6.98},"totalVirupas":{"type":"number","description":"Total Shadbala in virupas (Shashtiamsas). Sum of all 6 strength components. Higher total indicates a stronger planet in the birth chart. Used for comparing relative planetary strength and evaluating dasha period potential.","example":384.45},"totalRupas":{"type":"number","description":"Total Shadbala in Rupas (totalVirupas / 60). 1 Rupa equals 60 virupas. Rupas are the standard unit for comparing planetary strength against minimum required thresholds.","example":6.41},"minRequired":{"type":"number","description":"Minimum required strength in Rupas per BPHS. Sun 5.0, Moon 6.0, Mars 5.0, Mercury 7.0, Jupiter 6.5, Venus 5.5, Saturn 5.0. A planet below its minimum is considered weak and may underperform in its dasha periods.","example":5},"strengthRatio":{"type":"number","description":"Ratio of actual Rupas to minimum required (totalRupas / minRequired). Values above 1.0 indicate sufficient strength. Higher ratios mean proportionally stronger planets. Used for ranking planets by relative strength.","example":1.2814},"ishtaPhala":{"type":"number","description":"Ishta Phala (auspicious strength) in virupas. Derived from Uchcha Bala and Chesta Bala: sqrt(ucchaBala * chestaBala). Indicates the planets capacity to produce favorable results during its dasha and transit periods.","example":34.11},"kashtaPhala":{"type":"number","description":"Kashta Phala (malefic strength) in virupas. Derived from complements of Uchcha and Chesta Bala: sqrt((60 - ucchaBala) * (60 - chestaBala)). Indicates the planets capacity to produce unfavorable results. Zero when both Uchcha and Chesta exceed 60.","example":22.83},"relativeRank":{"type":"number","description":"Relative strength rank among the 7 planets (1 = strongest, 7 = weakest). Ranked by strengthRatio (actual/required), not raw virupas, so each planet is compared fairly against its own BPHS threshold.","example":2}},"required":["planet","sthanaBala","digBala","kalaBala","chestaBala","naisargikaBala","drikBala","totalVirupas","totalRupas","minRequired","strengthRatio","ishtaPhala","kashtaPhala","relativeRank"],"description":"Shadbala (six-fold strength) analysis for a single planet with all components, totals, Ishta/Kashta Phala, and relative ranking."},"description":"Shadbala analysis for all 7 classical planets. Ordered: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn. Each entry contains all 6 strength components, total strength in virupas and Rupas, Ishta/Kashta Phala, minimum required threshold, strength ratio, and relative rank."}},"required":["balaThemes","frame","planets"],"description":"Complete Shadbala (six-fold planetary strength) analysis for a birth chart per Brihat Parashara Hora Shastra (BPHS)."},"ShadbalaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"ArudhaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"lagnaRashi":{"type":"string","example":"Libra","description":"Zodiac sign of the Ascendant (Lagna), which anchors the twelve bhavas the padas are derived from."},"arudhaLagna":{"type":"string","example":"Leo","description":"Zodiac sign of the Arudha Lagna (AL), the pada of the first house and the single most used value in this response. Repeated at the top level so a client rendering only the AL does not have to search the array."},"upapada":{"type":"string","example":"Cancer","description":"Zodiac sign of the Upapada (UL), the pada of the twelfth house, read for marriage and its durability. The second most used value, so it is also lifted to the top level."},"padas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"a1","description":"Pada identifier, a1 through a12, matching the bhava it belongs to. a1 is the Arudha Lagna and a12 the Upapada."},"abbreviation":{"type":"string","example":"AL","description":"Practitioner shorthand written on a chart: AL for the Arudha Lagna, A2 through A11, and UL for the Upapada."},"name":{"type":"string","example":"Arudha Lagna","description":"Classical Sanskrit name of the pada, for example Arudha Lagna, Dhana Pada, Dara Pada, Upapada."},"house":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"Bhava (house) number 1-12 whose pada this is. The pada is the perceived, outward form of that bhava."},"bhavaRashi":{"type":"string","example":"Libra","description":"Zodiac sign (rashi) occupying that bhava, counted whole-sign from the Lagna. The count to the pada starts here."},"lord":{"type":"string","example":"Venus","description":"Lord of the bhava sign. The pada is found by counting to this graha and then the same distance again."},"lordRashi":{"type":"string","example":"Pisces","description":"Zodiac sign the bhava lord occupies, which sets the length of the count."},"rashi":{"type":"string","example":"Leo","description":"Zodiac sign the pada falls in, after the classical exception is applied. This is the answer most readings start from."},"houseFromLagna":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"Which house from the Lagna the pada sits in, counted inclusively 1-12. Reading a pada against the natal Lagna is how its strength is judged."},"exceptionApplied":{"type":"boolean","example":false,"description":"True when the raw pada landed in the same bhava or the seventh from it and was moved to the tenth from there, as the classical rule requires. Surfaced so a reader can see exactly why a pada sits where it does, which is the step implementations most often skip."},"meaning":{"type":"string","example":"Public image","description":"Short label for what this pada is read for, sized for a table cell."},"significations":{"type":"string","example":"How the world sees the native: status, reputation and the persona others react to, rather than the self behind it.","description":"What this pada governs. Padas describe how a matter is PERCEIVED, which is what separates them from the bhava significations of the same house."}},"required":["id","abbreviation","name","house","bhavaRashi","lord","lordRashi","rashi","houseFromLagna","exceptionApplied","meaning","significations"],"description":"One Arudha pada: the bhava it belongs to, the lord and count that produced it, the sign it lands in, and what it is read for."},"description":"All twelve Arudha padas in bhava order, a1 through a12. Each carries the lord and the count it came from, so the derivation can be checked by hand."}},"required":["frame","lagnaRashi","arudhaLagna","upapada","padas"],"description":"The twelve Arudha padas of a birth chart, computed per the Jaimini rule with the classical exception applied."},"ArudhaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"CharaKarakaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"scheme":{"type":"string","enum":["seven","eight"],"example":"eight","description":"Scheme the ranking used, echoed back so a cached or logged response is self describing."},"atmakaraka":{"type":"string","example":"Moon","description":"Graha holding the Atmakaraka office, the most consequential single value in Jaimini analysis. Lifted to the top level so a client reading only the Atmakaraka does not have to search the array."},"darakaraka":{"type":"string","example":"Saturn","description":"Graha holding the Darakaraka office, read for the spouse. The second most requested value, so it is also lifted to the top level."},"karakas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"atmakaraka","description":"Karaka office identifier: atmakaraka, amatyakaraka, bhratrikaraka, matrikaraka, pitrikaraka, putrakaraka, gnatikaraka, darakaraka. Returned in descending rank, so the first entry is always the Atmakaraka."},"name":{"type":"string","example":"Atmakaraka","description":"Classical Sanskrit name of the karaka office."},"abbreviation":{"type":"string","example":"AK","description":"Practitioner shorthand: AK, AmK, BK, MK, PiK, PK, GK, DK, in descending rank order."},"graha":{"type":"string","example":"Moon","description":"Graha holding this office in this chart."},"rashi":{"type":"string","example":"Libra","description":"Zodiac sign (rashi) the graha occupies."},"degreeInRashi":{"type":"number","example":24.4808,"description":"Degree the graha has advanced into its sign, 0 to 30. This is the figure a chart displays."},"rankingDegree":{"type":"number","example":24.4808,"description":"The degree actually ranked. Identical to degreeInRashi for every graha except Rahu, where it is 30 minus that value because Rahu advances backward through the sign. Returned so the ordering can be checked without knowing the rule."},"isReversed":{"type":"boolean","example":false,"description":"True only for Rahu, flagging that its degree was measured from the end of the sign rather than the start."},"meaning":{"type":"string","example":"Soul and self","description":"Short label for what this karaka is read for, sized for a table cell."},"significations":{"type":"string","example":"The desire that brought the soul to this birth, and the single strongest influence in the chart, ruling the native above every other graha.","description":"What this karaka office governs in a reading."}},"required":["id","name","abbreviation","graha","rashi","degreeInRashi","rankingDegree","isReversed","meaning","significations"],"description":"One Chara Karaka: the office, the graha holding it, the degree that earned it, and what the office is read for."},"description":"Karaka offices in descending rank, Atmakaraka first. Eight entries in the eight-karaka scheme, seven in the seven-karaka scheme."}},"required":["frame","scheme","atmakaraka","darakaraka","karakas"],"description":"Chara Karakas for a birth chart: the movable significators of Jaimini astrology, ranked by how far each graha has advanced into its sign."},"CharaKarakaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"scheme":{"type":"string","enum":["seven","eight"],"default":"eight","example":"eight","description":"Which Chara Karaka scheme to rank. \"eight\" includes Rahu, counting its degree in reverse because it moves retrograde, and returns eight offices including Pitrikaraka. \"seven\" ranks only the seven classical grahas and drops Pitrikaraka. Ketu is excluded from both, since it always mirrors the Rahu degree exactly. The two schemes can produce a different Atmakaraka for the same chart, so select the one your reference software uses. Defaults to \"eight\"."}},"required":["date","time","latitude","longitude"]},"BhavaBalaResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"houseSystem":{"type":"string","description":"House frame the bhavas were built on. Always sripati: Bhava Bala is defined on unequal bhava madhyas, not on whole signs.","example":"sripati"},"bhavas":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","description":"Bhava (house) number 1 to 12, counted from the Lagna. House 1 is the Ascendant bhava, house 10 the career bhava, house 7 the partnership bhava.","example":1},"rashi":{"type":"string","description":"Zodiac sign holding this bhavas madhya (mid-cusp). Under the Sripati house system the bhavas are unequal, so this is NOT always the nth sign from the Lagna, and two bhavas can share a sign while another sign holds none.","example":"Libra"},"madhya":{"type":"number","description":"Bhava madhya (mid-cusp) longitude in degrees, sidereal Lahiri. The point every strength component below is measured at. Bhavas 1, 4, 7 and 10 sit on the Ascendant, IC, Descendant and Midheaven; the rest trisect the quadrants between them.","example":196.4541},"lord":{"type":"string","description":"Bhavadhipati (house lord), the ruler of the sign holding the madhya. Its Shadbala is what this bhava inherits, so a house ruled by a strong graha starts strong.","example":"Venus"},"bhavadhipatiBala":{"type":"number","description":"Bhavadhipati Bala in virupas: the total Shadbala of the house lord, carried across unchanged. The dominant term of the three, typically 250 to 650. Two bhavas ruled by the same graha therefore share this value exactly.","example":548.54},"digBala":{"type":"number","description":"Bhava Digbala (directional strength) in virupas, 0 to 60 in steps of 10. Each rashi class is strongest in one cardinal bhava (human signs at the Lagna, quadruped at the 10th, watery at the 4th, Scorpio at the 7th) and loses 10 virupas per bhava of separation, reaching 0 at the seventh from it.","example":60},"drishtiBala":{"type":"number","description":"Bhava Drishti Bala (aspectual strength) in virupas, computed on the bhava madhya exactly as Graha Drik Bala is computed on a graha. Benefic aspects add and malefic aspects subtract, so this term is often negative.","example":-7.7},"totalVirupas":{"type":"number","description":"Total Bhava Bala in virupas, the sum of the three components above. Use it to compare houses within one chart: the strongest bhavas are the life areas that unfold with least resistance.","example":600.84},"totalRupas":{"type":"number","description":"Total Bhava Bala in rupas (totalVirupas / 60). 1 rupa equals 60 virupas. Rupas are the conventional unit in classical tables.","example":10.01},"rank":{"type":"number","description":"Strength rank among the twelve bhavas, 1 = strongest. Ranked on totalVirupas, so it never disagrees with the published totals.","example":1}},"required":["house","rashi","madhya","lord","bhavadhipatiBala","digBala","drishtiBala","totalVirupas","totalRupas","rank"],"description":"Bhava Bala for a single house, with the three classical components, the madhya it was measured at, and its rank."},"description":"Bhava Bala for all twelve houses in order, house 1 first. Each entry carries its own components so a client can explain a score rather than just display it."},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["frame","houseSystem","bhavas","houseThemes","focus"],"description":"Complete Bhava Bala (house strength) analysis per Brihat Parashara Hora Shastra, with a localized house-meaning legend."},"BhavaBalaRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"BhavChalitResponse":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The sidereal frame this response was computed in, so a cached or forwarded payload is self describing."},"houseSystem":{"type":"string","description":"House frame used to build the bhavas. Always sripati for the Chalit chart.","example":"sripati"},"ascendant":{"type":"number","description":"Sidereal Lahiri Ascendant in degrees. The madhya of bhava 1.","example":196.4541},"midheaven":{"type":"number","description":"Sidereal Lahiri Midheaven in degrees. The madhya of bhava 10.","example":106.9045},"bhavas":{"type":"array","items":{"type":"object","properties":{"house":{"type":"number","description":"Bhava number 1 to 12.","example":1},"start":{"type":"number","description":"Bhava sandhi (junction) opening this bhava, in degrees. The midpoint between this madhya and the previous one. A graha exactly on a sandhi belongs to the bhava it opens.","example":181.4593},"madhya":{"type":"number","description":"Bhava madhya (mid-cusp) in degrees. Bhavas 1, 4, 7 and 10 sit exactly on the Ascendant, IC, Descendant and Midheaven; the other eight trisect the quadrant arcs between them.","example":196.4541},"end":{"type":"number","description":"Bhava sandhi closing this bhava. Identical to the next bhavas start, so the twelve bhavas tile the zodiac with no gap.","example":211.5292},"span":{"type":"number","description":"Width of the bhava in degrees. Rarely 30: the Ascendant and Midheaven are only 90 degrees apart by coincidence of latitude and epoch, so quadrants stretch and squeeze and the bhavas with them.","example":30.07},"rashi":{"type":"string","description":"Sign holding the madhya. Because bhavas are unequal, two bhavas can share a sign while another sign holds no madhya at all.","example":"Libra"},"grahas":{"type":"array","items":{"type":"string"},"description":"Grahas falling inside this bhava. Empty when the bhava is unoccupied.","example":["Moon"]}},"required":["house","start","madhya","end","span","rashi","grahas"],"description":"One Sripati bhava with its boundaries and occupants."},"description":"The twelve Sripati bhavas in order with their boundaries and occupants."},"grahas":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","description":"Graha name. All nine are placed, the seven classical grahas plus the lunar nodes Rahu and Ketu.","example":"Sun"},"longitude":{"type":"number","description":"Sidereal Lahiri longitude in degrees.","example":35.9692},"rashi":{"type":"string","description":"Zodiac sign the graha occupies. Identical to the Rashi (D1) chart.","example":"Taurus"},"bhava":{"type":"number","description":"Bhava the graha falls in under the unequal Sripati cusps. This is the Bhav Chalit placement and the reason the chart exists.","example":5},"rashiHouse":{"type":"number","description":"House the same graha occupies in the whole-sign Rashi chart, counted from the Lagna sign. Returned alongside bhava so the difference is visible without a second request.","example":6},"moved":{"type":"boolean","description":"True when bhava and rashiHouse disagree, i.e. the graha changes house between the Rashi chart and the Chalit chart. These are the placements a practitioner opens this chart to check.","example":true}},"required":["graha","longitude","rashi","bhava","rashiHouse","moved"],"description":"One graha placed in both frames, with a flag marking the placements that move."},"description":"All nine grahas with both their Chalit bhava and their whole-sign Rashi house, plus a moved flag."},"movedCount":{"type":"number","description":"How many of the nine grahas change house between the Rashi chart and the Chalit chart. Zero is a perfectly normal result and means the two charts agree for this nativity.","example":3},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["frame","houseSystem","ascendant","midheaven","bhavas","grahas","movedCount","houseThemes","focus"],"description":"Bhav Chalit (Chalit Kundli): every graha placed by unequal Sripati bhava, with the whole-sign placement beside it for comparison."},"BhavChalitRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Sidereal frame (ayanamsa) the chart is cast in. \"lahiri\" is Lahiri/Chitrapaksha, the traditional Vedic standard used by most software, and is the default. \"raman\" is the B.V. Raman ayanamsa from Hindu Predictive Astrology, about 1.45 degrees below Lahiri. \"kp-newcomb\" and \"kp-old\" are the two Krishnamurti Paddhati frames. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. The frame rotates the whole zodiac, so a graha sitting within 1.45 degrees of a boundary can change rashi or nakshatra when you switch: pick the one your reference software uses and keep it."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."}},"required":["date","time","latitude","longitude"]},"HeliacalResponse":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-25","description":"Local calendar date the verdicts were read for, echoed from the request."},"grahas":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Jupiter","description":"Graha name. Only the six with a visible body appear: Moon, Mars, Mercury, Jupiter, Venus and Saturn. The Sun cannot be lost in his own glare, and Rahu and Ketu are computed points with nothing to see."},"visible":{"type":"boolean","example":false,"description":"Whether the graha clears the Sun glare on this day. False is the state a practitioner calls asta or combust, during which classical muhurta withholds auspicious ceremonies, most strictly marriage while Jupiter or Venus is invisible."},"horizon":{"type":"string","enum":["east","west"],"example":"west","description":"Horizon this graha is currently judged at. West means it sets after the Sun and is an evening object, east that it rises before him and is a morning one."},"timeDegrees":{"type":"number","example":3.01,"description":"Separation from the Sun in degrees of TIME (kalamsa), measured along the equator between the two bodies horizon crossings. This is the quantity Surya Siddhanta actually compares against the limit, and it is not the same as the difference of ecliptic longitudes: the two diverge by roughly 3 degrees at Mumbai and by more than 15 further north, because it accounts for the angle the ecliptic makes with the local horizon."},"kalamsa":{"type":"number","example":11,"description":"The limit in degrees of time this graha must clear to be seen, per Surya Siddhanta ch. IX vv.6-8 and ch. X.1: Moon 12, Jupiter 11, Saturn 15, Mars 17, Venus 10 or 8, Mercury 14 or 12. Larger means the graha is fainter and needs more distance from the Sun."},"retrograde":{"type":"boolean","example":false,"description":"Whether the graha is retrograde, which for Mercury and Venus tightens the limit (Venus 10 to 8, Mercury 14 to 12). Retrograde puts them near inferior conjunction where they are far closer to Earth, so the larger brighter disk survives closer to the Sun."},"longitudeSeparation":{"type":"number","example":2.89,"description":"Plain angular separation of the two ecliptic longitudes, in degrees. Returned beside timeDegrees so the two measures can be compared: this is what a combustion flag on a birth chart uses, and the gap between them is precisely what a location-aware heliacal calculation adds."},"lastEvent":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["udaya","asta"],"example":"udaya","description":"Udaya is heliacal rising, the graha re-emerging from the Sun rays and becoming visible again. Asta (also called lopa, moudhya or moudyami) is heliacal setting, the graha disappearing into them. Stable Sanskrit keys, never translated."},"horizon":{"type":"string","enum":["east","west"],"example":"east","description":"Horizon the event happens at. East means it is read before sunrise, so the graha is a morning object; west means after sunset, an evening object. A graha crosses to the other horizon as it passes the Sun, which is why an asta and the udaya that follows it are usually on opposite horizons."},"datetime":{"type":"string","example":"2026-08-12T05:35:22","description":"Local civil datetime of the event (YYYY-MM-DDTHH:MM:SS), being the moment the graha itself crosses the horizon on the day its verdict changes. That instant, rather than sunrise or sunset, is what published Asta tables print."},"timeDegrees":{"type":"number","example":11.09,"description":"Separation from the Sun in degrees of time on the event day, measured the way the classical rule requires. Sits just either side of kalamsa, since that crossing is what defines the event."},"kalamsa":{"type":"number","example":11,"description":"The limit that was crossed. Can differ from the current reading limit for Mercury and Venus, whose limit tightens when they are retrograde, so an asta entered while retrograde may be left at a different threshold."}},"required":["type","horizon","datetime","timeDegrees","kalamsa"],"description":"The event that produced the current state, or null when none falls inside the search horizon (up to about one synodic period, so Mars can legitimately have none)."},"nextEvent":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["udaya","asta"],"example":"udaya","description":"Udaya is heliacal rising, the graha re-emerging from the Sun rays and becoming visible again. Asta (also called lopa, moudhya or moudyami) is heliacal setting, the graha disappearing into them. Stable Sanskrit keys, never translated."},"horizon":{"type":"string","enum":["east","west"],"example":"east","description":"Horizon the event happens at. East means it is read before sunrise, so the graha is a morning object; west means after sunset, an evening object. A graha crosses to the other horizon as it passes the Sun, which is why an asta and the udaya that follows it are usually on opposite horizons."},"datetime":{"type":"string","example":"2026-08-12T05:35:22","description":"Local civil datetime of the event (YYYY-MM-DDTHH:MM:SS), being the moment the graha itself crosses the horizon on the day its verdict changes. That instant, rather than sunrise or sunset, is what published Asta tables print."},"timeDegrees":{"type":"number","example":11.09,"description":"Separation from the Sun in degrees of time on the event day, measured the way the classical rule requires. Sits just either side of kalamsa, since that crossing is what defines the event."},"kalamsa":{"type":"number","example":11,"description":"The limit that was crossed. Can differ from the current reading limit for Mercury and Venus, whose limit tightens when they are retrograde, so an asta entered while retrograde may be left at a different threshold."}},"required":["type","horizon","datetime","timeDegrees","kalamsa"],"description":"The event that will end the current state, or null when none falls inside the search horizon. For an invisible graha this is the udaya a practitioner is waiting for, so it answers when Guru Asta or Shukra Asta lifts."}},"required":["graha","visible","horizon","timeDegrees","kalamsa","retrograde","longitudeSeparation","lastEvent","nextEvent"],"description":"Heliacal visibility of one graha on the requested day."},"description":"One entry per visible graha, in classical order. A graha is omitted only when no horizon crossing exists for it at this latitude on this day."}},"required":["date","grahas"],"description":"Heliacal rising and setting status of the six visible grahas."},"HeliacalRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-07-25","description":"Local calendar date to judge, in YYYY-MM-DD format. There is deliberately no time field: heliacal visibility is a once-a-day verdict read at that day sunrise or sunset, so a clock time could only pick a different day."},"latitude":{"type":"number","minimum":-60,"maximum":60,"example":19.076,"description":"Observer latitude in decimal degrees, restricted to -60 to 60. Visibility depends on the observer, unlike the longitude orb every chart API reports, because the angle the ecliptic makes with the horizon decides how long a graha lingers after the Sun. Beyond this band the classical rule stops describing solar glare and starts describing polar horizon geometry, so it is declined rather than answered wrongly."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":72.8777,"description":"Observer longitude in decimal degrees. Sets local sunrise and sunset, which are the instants the verdict is read at. Example: Mumbai 72.8777, Delhi 77.2090, London -0.1278."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"Asia/Kolkata\", \"Europe/London\") OR decimal hours from UTC. Fixes which local day the date refers to, and every datetime in the response is returned in it. Defaults to 5.5.","example":5.5}},"required":["date","latitude","longitude"]},"BasicCard":{"type":"object","properties":{"id":{"type":"string","example":"fool","description":"Unique card identifier in kebab-case (e.g. fool, ace-of-cups, queen-of-swords)."},"name":{"type":"string","example":"The Fool","description":"Display name of the tarot card as it appears in the Rider-Waite-Smith tradition."},"arcana":{"type":"string","enum":["major","minor"],"example":"major","description":"Whether this card belongs to the Major Arcana (22 trump cards representing major life themes) or Minor Arcana (56 suit cards for daily situations)."},"suit":{"type":"string","enum":["cups","wands","swords","pentacles"],"example":"cups","description":"Suit of the card (Minor Arcana only). Cups=emotions, Wands=creativity, Swords=intellect, Pentacles=material. Null for Major Arcana cards."},"number":{"type":"number","example":0,"description":"Card number within its arcana. Major Arcana: 0 (Fool) through 21 (World). Minor Arcana: 1 (Ace) through 14 (King)."},"imageUrl":{"type":"string","example":"https://roxyapi.com/img/tarot/major/fool.jpg","description":"URL to the tarot card artwork image in the Rider-Waite-Smith style."}},"required":["id","name","arcana","number","imageUrl"]},"Card":{"type":"object","properties":{"id":{"type":"string","example":"fool","description":"Unique card identifier in kebab-case (e.g. fool, ace-of-cups, queen-of-swords)."},"name":{"type":"string","example":"The Fool","description":"Display name of the tarot card as it appears in the Rider-Waite-Smith tradition."},"arcana":{"type":"string","enum":["major","minor"],"example":"major","description":"Whether this card belongs to the Major Arcana (22 trump cards representing major life themes) or Minor Arcana (56 suit cards for daily situations)."},"suit":{"type":"string","enum":["cups","wands","swords","pentacles"],"example":"cups","description":"Suit of the card (Minor Arcana only). Cups=emotions, Wands=creativity, Swords=intellect, Pentacles=material. Null for Major Arcana cards."},"number":{"type":"number","example":0,"description":"Card number within its arcana. Major Arcana: 0 (Fool) through 21 (World). Minor Arcana: 1 (Ace) through 14 (King)."},"keywords":{"type":"object","properties":{"upright":{"type":"array","items":{"type":"string"},"example":["new beginnings","innocence","spontaneity","free spirit","potential"],"description":"Key themes when the card is drawn upright. Used for quick tarot reference and reading summaries."},"reversed":{"type":"array","items":{"type":"string"},"example":["recklessness","hesitation","naivety","fear of the unknown"],"description":"Key themes when the card is drawn reversed (inverted). Reversed meanings often indicate blocked or internalized energy."}},"required":["upright","reversed"],"description":"Keywords for both upright and reversed orientations of this tarot card, useful for quick divination reference.","example":{"upright":["new beginnings","innocence","spontaneity","free spirit","potential"],"reversed":["recklessness","hesitation","naivety","fear of the unknown"]}},"upright":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"example":["new beginnings","innocence","spontaneity","free spirit","potential"],"description":"Key themes and concepts for this card in the given orientation (upright or reversed). Used for quick tarot reference and divination summaries."},"description":{"type":"string","example":"Numbered zero, The Fool stands at the threshold of the Major Arcana as pure, unwritten potential. In the Rider-Waite-Smith image, a young traveller pauses at the edge of a high cliff, gazing into the open sky rather than the drop below, a white rose of innocence in one hand and a light bag of belongings slung from a wand over the shoulder.","description":"Full narrative interpretation of the card in this orientation. Covers symbolism, life lessons, and guidance for the querent."},"love":{"type":"string","example":"A new romance or a fresh chapter in an existing bond is opening. The card favours openness to unexpected connection and a spirit of play over caution.","description":"Love and relationship interpretation for this orientation. Covers romantic partnerships, dating, emotional connections, and matters of the heart."},"career":{"type":"string","example":"This is a threshold moment for work: a new role, a new venture, or a bold pivot into unfamiliar territory. The Fool rewards initiative and original thinking, and it can breathe fresh energy into stale projects.","description":"Career and professional interpretation for this orientation. Covers workplace dynamics, job transitions, ambition, and vocational purpose."},"finances":{"type":"string","example":"Financial openings appear, sometimes from unexpected directions, and the mood is expansive and exploratory. Spending tends toward experience, learning, and adventure.","description":"Financial interpretation for this orientation. Covers money management, investments, material prosperity, and abundance mindset."},"health":{"type":"string","example":"Renewed vitality and a fresh start are indicated, well suited to a new routine, an unfamiliar sport, or simply more time outdoors and in motion.","description":"Health and wellbeing interpretation for this orientation. Covers physical vitality, mental health, energy levels, and self-care guidance."},"spirituality":{"type":"string","example":"A spiritual journey is beginning, marked by openness, wonder, and a beginners willingness to learn.","description":"Spiritual interpretation for this orientation. Covers personal growth, inner wisdom, soul purpose, and metaphysical development."}},"required":["keywords","description"],"description":"Complete upright interpretation including description, keywords, and guidance across love, career, finances, health, and spirituality domains."},"reversed":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"example":["recklessness","hesitation","naivety","fear of the unknown"],"description":"Key themes and concepts for this card in the given orientation (upright or reversed). Used for quick tarot reference and divination summaries."},"description":{"type":"string","example":"Reversed, The Fool turns its open potential in two opposite directions, and the surrounding cards usually reveal which one applies. In the first, the leap becomes recklessness. The traveller ignores the dog at the heels and the cliff at the toe, acting on impulse without regard for consequence and mistaking carelessness for freedom.","description":"Full narrative interpretation of the card in this orientation. Covers symbolism, life lessons, and guidance for the querent."},"love":{"type":"string","example":"Hesitation or carelessness is unsettling matters of the heart. There may be a reluctance to commit and open up for fear of being hurt, or a tendency to rush in without seeing a partner clearly.","description":"Love and relationship interpretation for this orientation. Covers romantic partnerships, dating, emotional connections, and matters of the heart."},"career":{"type":"string","example":"Fear of the unknown may be keeping you fixed in an unfulfilling role, or impulsive moves may be made at work without thinking them through.","description":"Career and professional interpretation for this orientation. Covers workplace dynamics, job transitions, ambition, and vocational purpose."},"finances":{"type":"string","example":"Impulsive spending, unrealistic optimism, or schemes that sound too good to be true are the hazards here.","description":"Financial interpretation for this orientation. Covers money management, investments, material prosperity, and abundance mindset."},"health":{"type":"string","example":"Carelessness or risky habits may be catching up with the body, or anxiety may be holding back a needed change.","description":"Health and wellbeing interpretation for this orientation. Covers physical vitality, mental health, energy levels, and self-care guidance."},"spirituality":{"type":"string","example":"Spiritual momentum has either scattered into undiscerning enthusiasm or stalled into hesitation.","description":"Spiritual interpretation for this orientation. Covers personal growth, inner wisdom, soul purpose, and metaphysical development."}},"required":["keywords","description"],"description":"Complete reversed (inverted) interpretation including description, keywords, and guidance across love, career, finances, health, and spirituality domains. Reversed cards carry modified or blocked energy."},"imageUrl":{"type":"string","example":"https://roxyapi.com/img/tarot/major/fool.jpg","description":"URL to the tarot card artwork image in the Rider-Waite-Smith style."}},"required":["id","name","arcana","number","keywords","upright","reversed","imageUrl"]},"DrawnCard":{"type":"object","properties":{"id":{"type":"string","example":"fool","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","example":"The Fool","description":"Display name of the tarot card."},"arcana":{"type":"string","enum":["major","minor"],"description":"Whether this card belongs to the Major Arcana (22 trump cards, major life themes) or Minor Arcana (56 suit cards, daily situations)."},"suit":{"type":"string","enum":["cups","wands","swords","pentacles"],"description":"Suit of the card (Minor Arcana only). Cups=emotions, Wands=creativity, Swords=intellect, Pentacles=material. Null for Major Arcana cards."},"number":{"type":"number","example":0,"description":"Card number within its arcana. Major Arcana: 0 (Fool) through 21 (World). Minor Arcana: 1 (Ace) through 14 (King). Null when not applicable."},"position":{"type":"number","example":1,"description":"Position index of this card in the draw sequence (1-based). Useful for mapping cards to spread positions."},"reversed":{"type":"boolean","example":false,"description":"True if the card was drawn reversed (upside down). Reversed cards carry modified or blocked energy compared to upright position."},"keywords":{"type":"array","items":{"type":"string"},"example":["new beginnings","innocence","spontaneity","free spirit","potential"],"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","example":"Numbered zero, The Fool stands at the threshold of the Major Arcana as pure, unwritten potential. In the Rider-Waite-Smith image, a young traveller pauses at the edge of a high cliff, gazing into the open sky rather than the drop below, a white rose of innocence in one hand and a light bag of belongings slung from a wand over the shoulder.","description":"Full interpretation of this card in its current orientation, providing detailed divination guidance."},"love":{"type":"string","example":"A new romance or a fresh chapter in an existing bond is opening. The card favours openness to unexpected connection and a spirit of play over caution.","description":"Love and relationship interpretation for the drawn orientation. Covers romantic partnerships, dating, emotional connections, and matters of the heart."},"career":{"type":"string","example":"This is a threshold moment for work: a new role, a new venture, or a bold pivot into unfamiliar territory. The Fool rewards initiative and original thinking, and it can breathe fresh energy into stale projects.","description":"Career and professional interpretation for the drawn orientation. Covers workplace dynamics, job transitions, ambition, and vocational purpose."},"finances":{"type":"string","example":"Financial openings appear, sometimes from unexpected directions, and the mood is expansive and exploratory. Spending tends toward experience, learning, and adventure.","description":"Financial interpretation for the drawn orientation. Covers money management, investments, material prosperity, and abundance mindset."},"health":{"type":"string","example":"Renewed vitality and a fresh start are indicated, well suited to a new routine, an unfamiliar sport, or simply more time outdoors and in motion.","description":"Health and wellbeing interpretation for the drawn orientation. Covers physical vitality, mental health, energy levels, and self-care guidance."},"spirituality":{"type":"string","example":"A spiritual journey is beginning, marked by openness, wonder, and a beginners willingness to learn.","description":"Spiritual interpretation for the drawn orientation. Covers personal growth, inner wisdom, soul purpose, and metaphysical development."},"imageUrl":{"type":"string","example":"https://roxyapi.com/img/tarot/major/fool.jpg","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","position","reversed","keywords","meaning","imageUrl"]},"ChangingLine":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Line position (1-6, bottom to top). In I-Ching, each hexagram has six lines (yao) read from bottom upward."},"text":{"type":"string","example":"The dragon is still hidden below the surface, so it does not act.","description":"The oracle statement for this line. It applies when this specific line comes up changing (old yin or old yang) in a casting, and it speaks in the concrete imagery of the tradition."},"meaning":{"type":"string","example":"The first line is the beginning, still underground and unrecognized. Strength is present but untested, and showing it now invites resistance it cannot yet survive. Stay hidden and build.","description":"What the line statement asks of the querent, read from its position in the hexagram (1 is the hidden beginning, 3 is the exposed threshold, 5 is the ruling line, 6 is past the peak) and from whether the line is yin or yang. This is the meaning behind the image, so a consuming agent does not have to invent one."}},"required":["position","text"]},"BasicHexagram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hexagram number in King Wen sequence (1-64)."},"symbol":{"type":"string","example":"䷀","description":"Unicode hexagram symbol for display."},"chinese":{"type":"string","example":"乾","description":"Original Chinese name of the hexagram."},"english":{"type":"string","example":"The Creative","description":"English translation of the hexagram name."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization of the Chinese name with tone marks."},"upperTrigram":{"type":"string","example":"Heaven","description":"Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake."},"lowerTrigram":{"type":"string","example":"Heaven","description":"Lower trigram (lines 1-3). Combines with upper trigram to form the hexagram."}},"required":["number","symbol","chinese","english","pinyin","upperTrigram","lowerTrigram"]},"Hexagram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hexagram number in the traditional King Wen sequence (1-64), the standard ordering used in I-Ching divination for over 3,000 years."},"symbol":{"type":"string","example":"䷀","description":"Unicode hexagram symbol (U+4DC0 block) representing all six lines. Use for visual display in I-Ching apps and divination interfaces."},"chinese":{"type":"string","example":"乾","description":"Original Chinese character name of the hexagram in traditional script."},"english":{"type":"string","example":"The Creative","description":"English translation of the hexagram name, conveying the core concept and life situation it represents."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization of the Chinese name with tone marks for correct pronunciation."},"binary":{"type":"string","example":"111111","description":"Binary line pattern (6 digits, bottom to top). 1 = yang (solid line), 0 = yin (broken line). Lines 1-3 form the lower trigram, lines 4-6 form the upper trigram."},"upperTrigram":{"type":"string","example":"Heaven","description":"Upper trigram (lines 4-6). One of 8 trigrams: Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake."},"lowerTrigram":{"type":"string","example":"Heaven","description":"Lower trigram (lines 1-3). Combines with the upper trigram to form the hexagram and its meaning."},"judgment":{"type":"string","example":"Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome."},"image":{"type":"string","example":"Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal attitude and action."},"interpretation":{"$ref":"#/components/schemas/Interpretation"},"changingLines":{"type":"array","items":{"$ref":"#/components/schemas/ChangingLine"},"description":"Changing line interpretations for all 6 lines"}},"required":["number","symbol","chinese","english","pinyin","binary","upperTrigram","lowerTrigram","judgment","image","interpretation","changingLines"]},"Interpretation":{"type":"object","properties":{"general":{"type":"string","example":"This hexagram represents the primal power of creation and the energy of pure initiative.","description":"General life situation interpretation of this hexagram."},"love":{"type":"string","example":"A time of strong attraction and passionate connection. Take the initiative in expressing your feelings.","description":"Love and relationship guidance from this hexagram."},"career":{"type":"string","example":"Exceptional opportunities for advancement and recognition. Your creative ideas are at their peak.","description":"Career and professional life interpretation."},"decision":{"type":"string","example":"The time is right for bold action. Trust your instincts and move forward with confidence.","description":"Decision-making guidance for whether to act, wait, retreat, or advance based on this hexagram."},"advice":{"type":"string","example":"Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort.","description":"Practical wisdom and actionable advice from this hexagram for daily life application."}},"required":["general","love","career","decision","advice"]},"BasicTrigram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Trigram number (1-8)"},"symbol":{"type":"string","example":"☰","description":"Unicode trigram symbol"},"chinese":{"type":"string","example":"乾","description":"Chinese name"},"english":{"type":"string","example":"Heaven","description":"English name"},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization"},"binary":{"type":"string","example":"111","description":"Binary representation (1=Yang solid, 0=Yin broken)"},"attribute":{"type":"string","example":"Creative","description":"Core attribute/quality"}},"required":["number","symbol","chinese","english","pinyin","binary","attribute"]},"Trigram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Stable identifier for the trigram, 1 to 8. This is our lookup key, not a canonical sequence: the tradition has several orderings (King Wen, Fu Xi, Earlier and Later Heaven) and they disagree, so do not read ranking or precedence into it."},"symbol":{"type":"string","example":"☰","description":"Unicode trigram symbol (three lines) for visual display in I-Ching interfaces and Bagua diagrams."},"chinese":{"type":"string","example":"乾","description":"Original Chinese character name of the trigram in traditional script."},"english":{"type":"string","example":"Heaven","description":"English name representing the natural force or element this trigram embodies."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization of the Chinese name with tone marks for correct pronunciation."},"binary":{"type":"string","example":"111","description":"Three-digit binary representation of the trigram lines (bottom to top). 1 = yang (solid), 0 = yin (broken)."},"element":{"type":"string","example":"Metal","description":"Five element (Wu Xing) correspondence: Metal, Wood, Water, Fire, or Earth. Used in Chinese metaphysics and feng shui analysis."},"attribute":{"type":"string","example":"Creative","description":"Core attribute or quality this trigram represents in I-Ching philosophy (e.g., Creative, Receptive, Arousing)."},"familyMember":{"type":"string","example":"Father","description":"Family archetype in the Bagua system. Each trigram corresponds to a family role (Father, Mother, First Son, First Daughter, etc.)."},"direction":{"type":"string","example":"Northwest","description":"Compass direction in the King Wen (Later Heaven) Bagua arrangement. Used in feng shui spatial analysis."},"bodyPart":{"type":"string","example":"Head","description":"Body part associated with this trigram in traditional Chinese medicine and I-Ching body mapping."},"animal":{"type":"string","example":"Horse","description":"Animal symbol associated with this trigram in classical I-Ching imagery and divination."},"season":{"type":"string","example":"Late Autumn","description":"Season or time period associated with this trigram in the annual cycle of Chinese cosmology."},"quality":{"type":"string","example":"Strong","description":"Energetic quality describing the dynamic nature of this trigram (e.g., Strong, Devoted, Joyous, Gentle)."},"meaning":{"type":"string","example":"The Creative force representing pure yang energy, strength, leadership, and the power of initiative.","description":"Concise interpretation of the trigram covering its symbolic meaning, key associations, and guidance for understanding hexagrams containing this trigram."}},"required":["number","symbol","chinese","english","pinyin","binary","element","attribute","familyMember","direction","bodyPart","animal","season","quality","meaning"]},"BasicDreamSymbol":{"type":"object","properties":{"id":{"type":"string","example":"snake","description":"Unique symbol identifier in kebab-case."},"name":{"type":"string","example":"Snake","description":"Display name of the dream symbol."},"letter":{"type":"string","example":"s","description":"Starting letter for alphabetical filtering."}},"required":["id","name","letter"]},"DreamSymbol":{"type":"object","properties":{"id":{"type":"string","example":"snake","description":"Unique symbol identifier in kebab-case. Use this to fetch full interpretation via /symbols/{id}."},"name":{"type":"string","example":"Snake","description":"Display name of the dream symbol."},"letter":{"type":"string","example":"s","description":"Starting letter (a-z) for alphabetical dream dictionary navigation."},"meaning":{"type":"string","example":"To see a snake in your dream signifies hidden fears and worries that are threatening you. Your dream may be alerting you to something in your waking life that you are not aware of or that has not yet surfaced.","description":"Full psychological dream interpretation explaining the subconscious symbolism, emotional significance, and waking-life connections of this dream symbol."}},"required":["id","name","letter","meaning"]}},"parameters":{}},"paths":{"/languages/field-labels":{"get":{"operationId":"getFieldLabels","tags":["Languages"],"summary":"Get field labels for a language","description":"Returns the display label for every request field name and every selectable option across the API, in the requested language. Use this to build a birth-data form, a chart widget, or an admin picker that reads in your customer language without hardcoding a word: look a field name up in `fields`, and an option up in `enums` under `{fieldName}.{value}`. Values a caller sends stay the canonical English identifier, so a translated form still submits a valid request. Labels a language has not been translated into yet return English, and the whole payload is stable enough to cache for a day.","parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Form labels resolved for the requested language","content":{"application/json":{"schema":{"type":"object","properties":{"lang":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"example":"es","description":"Language these labels resolved to. Echoes the `lang` query parameter, or `en` when it is omitted."},"fields":{"type":"object","additionalProperties":{"type":"string","example":"Fecha de nacimiento","description":"Label to display for that field name."},"description":"Label per request field or parameter name. Keys are the wire names used in request bodies and query parameters, such as `birthDate`, `timezone` or `houseSystem`."},"enums":{"type":"object","additionalProperties":{"type":"string","example":"Nodo medio","description":"Label to display for that option, beside the unchanged value."},"description":"Label per selectable option, keyed `{fieldName}.{value}` so the same value can read differently under different fields. For example `nodeType.mean` and `houseSystem.whole-sign`. Split on the first dot: the field name is before it, and everything after it is the value you send back unchanged."}},"required":["lang","fields","enums"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/signs":{"get":{"operationId":"listZodiacSigns","tags":["Western Astrology"],"summary":"Get all zodiac signs - Complete zodiac signs list with dates and elements","description":"Returns all 12 tropical zodiac signs (Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, Pisces) with essential information: name, symbol, element (fire, earth, air, water), date ranges, and short descriptions. Perfect for zodiac sign lists, horoscope widgets, birth chart calculators, astrology apps, star sign selectors, and zodiac reference tools. Use GET /signs/{id} for complete zodiac sign profiles with personality traits, compatibility, and detailed characteristics.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved all 12 zodiac signs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"aries","description":"Lowercase sign identifier (e.g., aries, taurus, gemini)."},"name":{"type":"string","example":"Aries","description":"Display name of the zodiac sign."},"symbol":{"type":"string","example":"♈","description":"Unicode zodiac symbol for this sign."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"fire","description":"Elemental classification: fire, earth, air, or water. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dates":{"type":"object","properties":{"start":{"type":"string","example":"Mar 21","description":"Start date of this sign in the tropical zodiac."},"end":{"type":"string","example":"Apr 19","description":"End date of this sign in the tropical zodiac."}},"required":["start","end"],"description":"Tropical zodiac date range for this sign."},"description":{"type":"string","example":"Ambitious, independent, impatient","description":"Brief overview of this zodiac sign personality and themes."}},"required":["id","name","element","dates","description"]},"description":"All 12 tropical zodiac signs with names, symbols, elements, date ranges, and descriptions."}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/signs/{id}":{"get":{"operationId":"getZodiacSign","tags":["Western Astrology"],"summary":"Get zodiac sign details - Complete astrology sign profile with personality traits","description":"Retrieve comprehensive zodiac sign information for any astrological sign using lowercase ID (e.g., \"aries\") or case-insensitive name (e.g., \"Aries\", \"ARIES\"). Returns complete astrology profile including: element (fire, earth, air, water), modality (cardinal, fixed, mutable), ruling planet, birth date ranges, personality traits (positive, negative, keywords), zodiac sign descriptions, famous people with this sign, key strengths and qualities, sign motto, greatest gifts, challenges, and secret weapon. Perfect for horoscope readings, zodiac compatibility checks, birth chart interpretations, astrology blogs, star sign personality analysis, and zodiac meaning databases.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"aries","description":"Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS)."},"required":true,"description":"Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved zodiac sign","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"aries","description":"Lowercase sign identifier."},"name":{"type":"string","example":"Aries","description":"Display name of the zodiac sign."},"symbol":{"type":"string","example":"♈","description":"Unicode zodiac symbol."},"symbolName":{"type":"string","example":"The Ram","description":"Symbol name or mascot associated with this sign."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"fire","description":"Elemental classification: fire, earth, air, or water. Determines temperament and compatibility group. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Quality/modality: cardinal (initiating), fixed (sustaining), or mutable (adapting). Always one of these three English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use modalityLocalized for anything a reader sees."},"modalityLocalized":{"type":"string","example":"Cardinal","description":"Modality name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"rulingPlanet":{"type":"string","example":"Mars","description":"Traditional ruling planet that governs this sign. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use rulingPlanetLocalized for anything a reader sees."},"rulingPlanetLocalized":{"type":"string","example":"Marte","description":"Ruling planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dates":{"type":"object","properties":{"start":{"type":"string","example":"Mar 21","description":"Start date of this sign season."},"end":{"type":"string","example":"Apr 19","description":"End date of this sign season."}},"required":["start","end"],"description":"Tropical zodiac date range for this sign."},"keywords":{"type":"array","items":{"type":"string"},"example":["ambitious","courageous","energetic"],"description":"Key personality traits and descriptive words for this sign."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Ambitious, independent, impatient","description":"Brief 1-2 sentence personality overview."},"long":{"type":"string","example":"Aries, the first sign in the zodiac, belongs to those born between March 21 and April 19. Aries are the trailblazers. Passionate and independent, an Aries will never do something just because everyone else is doing it. Competitive to the max, the best way to motivate an Aries is to turn something into a contest.","description":"Detailed multi-paragraph sign profile with personality analysis."}},"required":["short","long"],"description":"Sign description in short and long form."},"famous":{"type":"array","items":{"type":"string"},"example":["Leonardo da Vinci","Lady Gaga"],"description":"Notable people born under this zodiac sign."},"strengths":{"type":"array","items":{"type":"string"},"example":["You are the most courageous and ambitious sign, the leader of every pack.","Your determination is unmatched when it comes to getting what you want.","You work hard but also play hard, and you are the life of every party."],"description":"Key strengths and lovable qualities of this sign."},"motto":{"type":"string","example":"I am.","description":"Signature motto or tagline for this sign."},"gifts":{"type":"string","example":"Whether it is backpacking around the world, launching a business, or training for a marathon, once an Aries sets a goal they will achieve it. Rams never need a plus one: they love their own company.","description":"Greatest gifts and natural talents of this sign."},"challenges":{"type":"string","example":"The world according to an Aries makes so much sense that they have a hard time accepting alternative viewpoints. Slowing down is also tough, and to maintain relationships an Aries must learn to adapt to other ways of doing and seeing.","description":"Greatest challenges and growth areas for this sign."},"weapon":{"type":"string","example":"Strong, adamant, and forged in fire, it is fitting that the Aries secret weapon is iron, one of the strongest elements. Weld it, cast it, or temper it, and iron takes on a seemingly limitless range of shapes.","description":"Secret weapon or superpower of this sign."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element, 120 degrees apart) listed first, followed by a sextile partner (complementary element, 60 degrees apart). Use for compatibility widgets, dating app onboarding, sign profile cards, and zodiac matchmaking."}},"required":["id","name","symbolName","element","modality","rulingPlanet","dates","keywords","description","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Zodiac sign not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/planet-meanings":{"get":{"operationId":"listPlanetMeanings","tags":["Western Astrology"],"summary":"Get all planet meanings - Complete astrology planet interpretations list","description":"Returns all 14 astrological bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) with essential meanings: name, symbol, tagline, category (personal/social/generational), ruling sign, and short descriptions. Perfect for astrology reference apps, planet meaning widgets, birth chart interpretation tools, astrology learning platforms, planetary keywords reference, and zodiac planet guides. Use GET /planet-meanings/{id} for complete profiles with detailed interpretations, keywords, temperature, and dignities (rulership/detriment/exaltation/fall).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved all 14 body meanings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sun","description":"Lowercase planet identifier (e.g., sun, moon, mercury)."},"name":{"type":"string","example":"Sun","description":"Display name of the planet."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this planet."},"tagline":{"type":"string","example":"Self-awareness and ego","description":"Short tagline summarizing this planet in astrology."},"category":{"type":"string","example":"personal","description":"Planet classification: personal (Sun-Mars), social (Jupiter-Saturn), or generational (Uranus-Pluto)."},"rulership":{"type":"string","example":"Leo","description":"Zodiac sign this planet rules. The sign where the planet operates most naturally. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"description":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart.","description":"Brief overview of the planet and its astrological significance."}},"required":["id","name","symbol","tagline","description"]},"description":"All 14 astrological bodies with names, symbols, taglines, categories, and brief descriptions."}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/planet-meanings/{id}":{"get":{"operationId":"getPlanetMeaning","tags":["Western Astrology"],"summary":"Get planet meaning details - Complete astrology planet interpretation","description":"Retrieve comprehensive planet interpretation for any astrological planet using lowercase ID (e.g., \"sun\", \"moon\") or case-insensitive name (e.g., \"Sun\", \"MOON\"). Returns complete astrology meaning including: symbol, tagline, category (personal/social/generational), temperature, orbital period, retrograde status, dignities (rulership/detriment/exaltation/fall), positive and negative keywords, and short/long descriptions. Perfect for birth chart readings, planet meaning lookups, astrology education, natal chart interpretation, transit meanings, planetary symbolism reference, and keyword-based interpretations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"sun","description":"Planet ID (lowercase, e.g., sun, moon, mercury) or display name (case-insensitive, e.g., Sun, MOON)."},"required":true,"description":"Planet ID (lowercase, e.g., sun, moon, mercury) or display name (case-insensitive, e.g., Sun, MOON).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved planet meaning","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"sun","description":"Lowercase planet identifier."},"name":{"type":"string","example":"Sun","description":"Display name of the planet."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol."},"tagline":{"type":"string","example":"Self-awareness and ego","description":"Short tagline summarizing this planet."},"category":{"type":"string","example":"personal","description":"Planet classification: personal (Sun-Mars), social (Jupiter-Saturn), or generational (Uranus-Pluto)."},"temperature":{"type":"string","example":"Hot","description":"Traditional planet temperature (Hot, Cold, or Neutral)."},"orbit":{"type":"string","example":"365.25 days","description":"Orbital period around the Sun or zodiac cycle length."},"retrograde":{"type":"boolean","example":false,"description":"Whether this planet can appear retrograde. Always false for Sun and Moon."},"rulership":{"type":"string","example":"Leo","description":"Zodiac sign this planet rules (domicile). Where the planet operates most naturally. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"detriment":{"type":"string","example":"Aquarius","description":"Sign of detriment. Opposite the rulership sign, where the planet struggles. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"exaltation":{"type":"string","example":"Aries","description":"Sign of exaltation. Where the planet is honored and amplified. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"exultation":{"type":"string","example":"Aries","description":"Deprecated: use exaltation. Retained for backward compatibility, scheduled for removal in v3. Sign of exaltation, carrying the same value as the exaltation field."},"fall":{"type":"string","example":"Libra","description":"Sign of fall. Opposite the exaltation sign, where the planet is weakened. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"keywords":{"type":"object","properties":{"positive":{"type":"array","items":{"type":"string"},"example":["Vitality","Confidence","Leadership"],"description":"Positive traits and keywords when this planet is well-aspected."},"negative":{"type":"array","items":{"type":"string"},"example":["Ego","Arrogance","Domineering"],"description":"Shadow traits when this planet is challenged or afflicted."}},"required":["positive","negative"],"description":"Positive and negative keyword associations for this planet."},"description":{"type":"object","properties":{"short":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart, shaping how you assert yourself and pursue your goals.","description":"Brief 1-2 sentence overview of the planet."},"long":{"type":"string","example":"The Sun traveling through the zodiac creates what we think of as our astrological year. In the natal chart, the Sun represents who we are and who we strive to be. Unlike the Moon, which represents our emotional responses, the Sun stands for our most rational selves and the way we interact with the world on a daily basis. Approximately every 30 days the Sun transits to a new sign and brings a fresh sense of perspective.","description":"Detailed multi-paragraph description of the planet, its symbolism, and astrological meaning."}},"required":["short","long"],"description":"Planet description in short and long form."}},"required":["id","name","symbol","tagline","temperature","orbit","keywords","description"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Planet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/natal-chart":{"post":{"operationId":"generateNatalChart","tags":["Western Astrology"],"summary":"Generate natal chart - Birth chart calculator API with houses and aspects","description":"Calculate complete Western astrology natal chart (birth chart) with tropical zodiac. Returns all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith), 12 house cusps with customizable house systems (Placidus, Whole Sign, Equal, Koch), major and minor aspects, Ascendant, Midheaven, dominant elements and modalities. Perfect for astrology apps, birth chart generators, horoscope websites, and astrological consultation tools. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartRequest"}}}},"responses":{"200":{"description":"Successful natal chart calculation with complete astrological data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/planets":{"post":{"operationId":"getPlanetaryPositions","tags":["Western Astrology"],"summary":"Get planetary positions - Ephemeris calculator for all planets","description":"Calculate accurate tropical zodiac positions for all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for any date, time, and location. Returns longitude, latitude, zodiac sign, degree within sign, daily motion speed, and retrograde status. Perfect for transit tracking, ephemeris tables, astrology apps, and planetary position widgets. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-12-18","description":"Target date for planetary positions in YYYY-MM-DD format. Use current date for transit positions, or any historical/future date for research. Planets move daily, so this date determines their zodiac positions."},"time":{"type":"string","format":"time","example":"12:00:00","description":"Time in 24-hour HH:MM:SS format for precise calculations. Moon moves ~13° per day, so time matters for accurate lunar position. Use 12:00:00 (noon) as default if exact time not needed."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Observer latitude in decimal degrees (-90 to 90). While planetary longitudes are geocentric (same worldwide), this is needed for house calculations if extending functionality. For basic ephemeris, use 0 as default."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Observer longitude in decimal degrees (-180 to 180). Used for precise local time conversion. For basic planetary positions, this has minimal impact but ensures accuracy."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST, 5.75 for NPT) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the chart date.","example":-5}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Planetary positions calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"longitude":{"type":"number","example":267.45,"description":"Tropical ecliptic longitude in degrees (0-360)."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees."},"sign":{"type":"string","example":"Sagittarius","description":"Tropical zodiac sign this planet occupies."},"degree":{"type":"number","example":27.45,"description":"Degree within the zodiac sign (0-29.999)."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in apparent retrograde motion."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this planet."},"tagline":{"type":"string","example":"Self-awareness & ego","description":"Short tagline summarizing what this planet governs."},"description":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose.","description":"Brief description of this planet in astrological context."},"keywords":{"type":"array","items":{"type":"string"},"example":["Identity","Vitality","Purpose"],"description":"Key themes and traits associated with this planet."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of self-awareness and ego. This placement gives your Sun expression a distinctly Sagittarius character, shaping how you navigate these areas of life.","description":"Interpretation of this planet in its current zodiac sign."},"planetMeaning":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose.","description":"General meaning of this planet in astrology."},"signExpression":{"type":"string","example":"Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius is not afraid to step away from the pack, and is a natural born leader who goes after what they want, regardless of what other people think.","description":"How this planet expresses through the current sign."},"keywords":{"type":"array","items":{"type":"string"},"example":["active","awareness","bright","confidence","consciousness","adventurous","optimistic","independent"],"description":"Keywords for this specific planet-in-sign combination."}},"required":["summary","planetMeaning","signExpression","keywords"],"description":"Planet-in-sign interpretation. How this planet expresses through the zodiac sign it currently occupies."}},"required":["name","longitude","latitude","sign","degree","speed","isRetrograde"]},"description":"All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, speeds, retrograde status, meanings, and interpretations."}},"required":["planets"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/planets/monthly":{"post":{"operationId":"getMonthlyTropicalEphemeris","tags":["Western Astrology"],"summary":"Monthly Ephemeris - Daily tropical planetary positions for a month","description":"Get daily tropical ecliptic positions for all 14 Western bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for an entire month. Returns longitude, zodiac sign, degree within sign, and retrograde status for each body on each day, calculated at noon UTC. Omit year and month to get the month in progress, so a published ephemeris page stays current without a redeploy. Essential for ephemeris tables, transit tracking, retrograde calendars, and planetary movement charts. Monthly ephemeris API, tropical position table, daily planet transit positions, ecliptic longitude calculator. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for the monthly ephemeris (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"Month number (1-12) for the ephemeris. Defaults to the current month (UTC)."}}}}}},"responses":{"200":{"description":"Monthly ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the ephemeris. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":8,"description":"Month of the ephemeris. Echoes the month that was requested, or the current UTC month when it was omitted."},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-08-01","description":"Date in YYYY-MM-DD format."},"positions":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Body name, one of the 14 bodies Western astrology reads: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Marte","description":"Body name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet exactly."},"longitude":{"type":"number","example":83.4062,"description":"Tropical ecliptic longitude in degrees (0-360), measured from the vernal equinox. This is the Western zodiac, not the sidereal one, so the two differ by the ayanamsa of roughly 24 degrees."},"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign the body occupies on this date. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Geminis","description":"Zodiac sign name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat sign exactly."},"degreeInSign":{"type":"number","example":23.4062,"description":"Degrees traversed within the current sign (0-30). Useful for precise transit tracking and for printing a position as sign plus degree."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the body is in apparent retrograde motion on this date. The lunar nodes are always retrograde and Black Moon Lilith is always direct."}},"required":["planet","longitude","sign","degreeInSign","isRetrograde"]},"description":"Tropical positions of all 14 Western bodies on this date at noon UTC."}},"required":["date","positions"]},"description":"Daily planetary position entries for the entire month."}},"required":["year","month","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/moon-phase/current":{"get":{"operationId":"getCurrentMoonPhase","tags":["Western Astrology"],"summary":"Get current moon phase - Lunar phase calculator with zodiac sign","description":"Get current moon phase with illumination percentage, lunar age (days since new moon), zodiac sign, and distance from Earth. Returns phase name (New Moon, Waxing Crescent Moon, First Quarter Moon, Waxing Gibbous Moon, Full Moon, Waning Gibbous Moon, Last Quarter Moon, Waning Crescent Moon) plus exact lunar position. Perfect for moon tracking apps, lunar calendars, astrology widgets, and gardening by moon phase tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2025-12-18","description":"Date in YYYY-MM-DD format. Defaults to today if omitted."},"required":false,"description":"Date in YYYY-MM-DD format. Defaults to today if omitted.","name":"date","in":"query"},{"schema":{"type":"string","format":"time","example":"12:00:00","description":"Time in 24-hour HH:MM:SS format. Defaults to 12:00:00 (noon). Moon moves ~13 degrees per day so time affects phase precision."},"required":false,"description":"Time in 24-hour HH:MM:SS format. Defaults to 12:00:00 (noon). Moon moves ~13 degrees per day so time affects phase precision.","name":"time","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"IANA name (e.g. \"America/New_York\", \"Europe/London\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC)."},"required":false,"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC).","name":"timezone","in":"query"}],"responses":{"200":{"description":"Moon phase calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-18","description":"Date of this moon phase calculation (YYYY-MM-DD)."},"phase":{"type":"string","example":"Waxing Gibbous Moon","description":"Current lunar phase name. One of: New Moon, Waxing Crescent Moon, First Quarter Moon, Waxing Gibbous Moon, Full Moon, Waning Gibbous Moon, Last Quarter Moon, Waning Crescent Moon."},"illumination":{"type":"number","example":78.5,"description":"Moon illumination percentage (0-100). 0 = New Moon, 100 = Full Moon."},"age":{"type":"number","example":10.25,"description":"Lunar age in days since the last New Moon. Full lunation cycle is ~29.53 days."},"sign":{"type":"string","example":"Pisces","description":"Tropical zodiac sign the Moon currently occupies."},"degree":{"type":"number","example":15.42,"description":"Degree of the Moon within its current zodiac sign (0-29.999)."},"distance":{"type":"number","example":384400,"description":"Distance from Earth to the Moon in kilometers."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Waxing Gibbous Moon","description":"Moon phase display name."},"symbol":{"type":"string","example":"🌔","description":"Moon phase emoji symbol."},"description":{"type":"string","description":"Astrological interpretation of this lunar phase and its influence on activities, emotions, and intentions.","example":"The waxing gibbous moon is there when we are close to our goals..."},"keywords":{"type":"array","items":{"type":"string"},"example":["assess","refine","perfect"],"description":"Key themes and activities aligned with this moon phase."},"energy":{"type":"string","enum":["waxing","waning","new","full"],"example":"waxing","description":"Lunar energy direction: waxing (building), waning (releasing), new (beginning), or full (culmination)."},"illumination":{"type":"string","example":"50-100% (Nearly Full)","description":"Illumination range description for this phase."}},"required":["name","symbol","description","keywords","energy","illumination"],"description":"Moon phase meaning and astrological interpretation. Includes energy direction, keywords, and guidance for this lunar phase."}},"required":["date","phase","illumination","age","sign","degree","distance"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/moon-phase/upcoming":{"get":{"operationId":"getUpcomingMoonPhases","tags":["Western Astrology"],"summary":"Get upcoming moon phases - Next new moon, full moon, quarters","description":"Get upcoming moon phase transitions (New Moon, First Quarter, Full Moon, Last Quarter) for the next weeks/months. Returns dates and phase names for each lunar quarter. Perfect for lunar event calendars, moon phase widgets, and astrology planning tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2025-12-18","description":"Start date in YYYY-MM-DD format. Defaults to today if omitted."},"required":false,"description":"Start date in YYYY-MM-DD format. Defaults to today if omitted.","name":"startDate","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":20,"default":8,"example":8,"description":"Number of upcoming moon phase transitions to return (1-20). Defaults to 8."},"required":false,"description":"Number of upcoming moon phase transitions to return (1-20). Defaults to 8.","name":"count","in":"query"}],"responses":{"200":{"description":"Upcoming moon phases retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"phases":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-26","description":"Date of this moon phase transition (YYYY-MM-DD)."},"phase":{"type":"string","example":"New Moon","description":"Lunar phase name (New Moon, First Quarter, Full Moon, Last Quarter)."}},"required":["date","phase"]},"description":"Upcoming moon phase transition dates in chronological order."}},"required":["phases"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/moon-phase/calendar/{year}/{month}":{"get":{"operationId":"getMoonCalendar","tags":["Western Astrology"],"summary":"Get lunar calendar - Moon phases for entire month","description":"Get complete lunar calendar showing moon phase and illumination for every day of a specific month. Perfect for creating moon phase calendars, lunar planners, and astrology event schedules.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","minimum":1900,"maximum":2100,"example":2026,"description":"Calendar year (1900-2100)."},"required":true,"description":"Calendar year (1900-2100).","name":"year","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":12,"example":3,"description":"Calendar month (1-12). 1 = January, 12 = December."},"required":true,"description":"Calendar month (1-12). 1 = January, 12 = December.","name":"month","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Lunar calendar generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2025,"description":"Calendar year for this lunar calendar."},"month":{"type":"number","example":12,"description":"Calendar month for this lunar calendar."},"monthName":{"type":"string","example":"December","description":"Month name, localized to the requested language. Saves the caller a lookup table when labelling a calendar heading, since the numeric month alone cannot be rendered without one."},"calendar":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-01","description":"Calendar date (YYYY-MM-DD)."},"phase":{"type":"string","example":"Waxing Crescent Moon","description":"Lunar phase name for this date."},"illumination":{"type":"number","example":5.2,"description":"Moon illumination percentage (0-100) at noon on this date."}},"required":["date","phase","illumination"]},"description":"Daily moon phase and illumination for every day of the month."}},"required":["year","month","monthName","calendar"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/synastry":{"post":{"operationId":"calculateSynastry","tags":["Western Astrology"],"summary":"Calculate synastry - Relationship compatibility analysis API","description":"Calculate complete synastry (relationship compatibility) between two natal charts using Western tropical astrology. Analyzes inter-chart aspects between all planets to determine romantic, friendship, and karmic compatibility. Returns compatibility score (0-100), detailed inter-aspects with strength ratings, harmonious vs challenging aspect counts, and relationship dynamics analysis. Perfect for dating apps, matrimonial sites, relationship counseling tools, and astrology compatibility features. Based on professional astrological techniques.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"name":{"type":"string","example":"Alex","description":"Optional display name for this person. Included in the response for easy identification."}},"required":["date","time","latitude","longitude","timezone"]},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"name":{"type":"string","example":"Alex","description":"Optional display name for this person. Included in the response for easy identification."}},"required":["date","time","latitude","longitude","timezone"]},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for both natal charts. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["person1","person2"]}}}},"responses":{"200":{"description":"Synastry calculated successfully with compatibility analysis","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"name":{"type":"string","example":"Alex","description":"Display name if provided in the request."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Ascendant (rising sign) of this person. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."}},"required":["sign","degree"],"description":"Ascendant position for person 1. Determines first house cusp and outward personality."},"sunSign":{"type":"string","example":"Cancer","description":"Sun sign (zodiac sign) of this person. Core identity and ego expression. Always English, whatever the lang parameter says. Use sunSignLocalized for anything a reader sees."},"sunSignLocalized":{"type":"string","example":"Cáncer","description":"Sun sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"moonSign":{"type":"string","example":"Pisces","description":"Moon sign of this person. Emotional nature and inner needs. Always English, whatever the lang parameter says. Use moonSignLocalized for anything a reader sees."},"moonSignLocalized":{"type":"string","example":"Piscis","description":"Moon sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name. Matches the names used in interAspects. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":114.52,"description":"Ecliptic longitude in degrees (0-360) measured from 0 Aries. This is the value a wheel plots."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign containing the planet. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":24.52,"description":"Degree within the sign (0-29.999)."},"house":{"type":"number","example":3,"description":"House this planet occupies in the person 1 chart (1-12)."},"isRetrograde":{"type":"boolean","example":false,"description":"True when the planet is retrograde at this moment."}},"required":["name","longitude","sign","degree","house","isRetrograde"]},"description":"Planet positions for person 1, enough to render this side of a dual wheel without a second request. Per-planet interpretations are not repeated here; call the natal chart endpoint for an individual reading."}},"required":["ascendant","sunSign","moonSign","planets"],"description":"Person 1 chart highlights: Ascendant, Sun sign, Moon sign, and plotting positions."},"person2":{"type":"object","properties":{"name":{"type":"string","example":"Jordan","description":"Display name if provided in the request."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Ascendant (rising sign) of this person. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Virgo","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":22.18,"description":"Degree within the Ascendant sign (0-29.999)."}},"required":["sign","degree"],"description":"Ascendant position for person 2. Determines first house cusp and outward personality."},"sunSign":{"type":"string","example":"Pisces","description":"Sun sign (zodiac sign) of this person. Core identity and ego expression. Always English, whatever the lang parameter says. Use sunSignLocalized for anything a reader sees."},"sunSignLocalized":{"type":"string","example":"Piscis","description":"Sun sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"moonSign":{"type":"string","example":"Scorpio","description":"Moon sign of this person. Emotional nature and inner needs. Always English, whatever the lang parameter says. Use moonSignLocalized for anything a reader sees."},"moonSignLocalized":{"type":"string","example":"Escorpio","description":"Moon sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name. Matches the names used in interAspects. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":114.52,"description":"Ecliptic longitude in degrees (0-360) measured from 0 Aries. This is the value a wheel plots."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign containing the planet. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":24.52,"description":"Degree within the sign (0-29.999)."},"house":{"type":"number","example":3,"description":"House this planet occupies in the person 2 chart (1-12)."},"isRetrograde":{"type":"boolean","example":false,"description":"True when the planet is retrograde at this moment."}},"required":["name","longitude","sign","degree","house","isRetrograde"]},"description":"Planet positions for person 2, enough to render this side of a dual wheel without a second request. Per-planet interpretations are not repeated here; call the natal chart endpoint for an individual reading."}},"required":["ascendant","sunSign","moonSign","planets"],"description":"Person 2 chart highlights: Ascendant, Sun sign, Moon sign, and plotting positions."},"compatibilityScore":{"type":"number","example":78,"description":"Overall compatibility score (0-100). Calculated from the balance of harmonious vs challenging inter-chart aspects weighted by planet importance."},"interAspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"Planet from person 1 chart. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Venus","description":"Person 1 planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Mars","description":"Planet from person 2 chart. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Marte","description":"Person 2 planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"strength":{"type":"number","example":75,"description":"Aspect strength percentage (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature: harmonious, challenging, or neutral."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Trine","description":"Aspect display name."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Planets in trine support each other. Trines, by nature, are accepting. They allow us to accept others, ourselves, and situations. The talents that trines offer a native are so natural that they are almost unconscious.","description":"Brief aspect description."},"long":{"type":"string","example":"These talents are second nature and completely natural. So, for example, if a chart has Venus trine Neptune, the native may be poetic, romantic, or artistic, and may easily accept a romantic partner for who they are.","description":"Detailed aspect description."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"How this aspect type is characterised in its reference card, in the requested language, exactly like the name, description and keywords beside it. Branch on the aspect-level interpretation field instead, which is always English."},"relationshipContext":{"type":"string","example":"Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","description":"How this specific planetary pair aspect manifests in relationships."}},"required":["name","description","keywords","nature","relationshipContext"],"description":"Aspect meaning with relationship-specific context for this planet pair."}},"required":["planet1","planet2","type","angle","orb","strength","interpretation"]},"description":"All inter-chart (synastry) aspects between person 1 and person 2 planets. Each aspect reveals a specific dynamic in the relationship."},"summary":{"type":"object","properties":{"total":{"type":"number","example":24,"description":"Total number of inter-chart aspects found."},"harmonious":{"type":"number","example":12,"description":"Count of harmonious aspects (trine, sextile). Natural ease and flow."},"challenging":{"type":"number","example":8,"description":"Count of challenging aspects (square, opposition). Dynamic tension and growth."},"neutral":{"type":"number","example":4,"description":"Count of neutral aspects (conjunction). Outcome depends on planets involved."},"byType":{"type":"object","additionalProperties":{"type":"number","example":5,"description":"Number of cross chart aspects of this type between the two charts. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"TRINE":5,"SEXTILE":7,"SQUARE":6,"OPPOSITION":2},"description":"Aspect count grouped by type. Shows which aspect patterns dominate the relationship."}},"required":["total","harmonious","challenging","neutral","byType"],"description":"Synastry aspect summary showing the balance of harmonious vs challenging inter-chart connections."},"analysis":{"type":"object","properties":{"overall":{"type":"string","example":"This relationship shows strong compatibility with genuine potential for lasting partnership. Most interactions feel natural and supportive, with a healthy mix of comfort and growth. Where challenges arise, both partners have the tools to work through them constructively.","description":"Overall relationship analysis narrative based on aspect patterns."},"strengths":{"type":"array","items":{"type":"string"},"example":["More harmonious aspects than challenging ones create a supportive foundation.","Harmonious Moon aspects indicate emotional understanding and nurturing.","Favorable Venus aspects bring affection, appreciation, and romantic chemistry."],"description":"Areas where the relationship naturally thrives based on harmonious aspects."},"challenges":{"type":"array","items":{"type":"string"},"example":["Challenging Sun aspects may create ego conflicts or competing life directions.","Challenging Mars aspects may bring tension, arguments, or competing desires."],"description":"Potential friction points and growth opportunities from challenging aspects."}},"required":["overall","strengths","challenges"],"description":"Relationship analysis with strengths, challenges, and overall assessment."}},"required":["person1","person2","compatibilityScore","interAspects","summary","analysis"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/houses":{"post":{"operationId":"calculateHouses","tags":["Western Astrology"],"summary":"Calculate house cusps - House system calculator with comparison","description":"Calculate astrological house cusps using Placidus, Whole Sign, Equal, or Koch house systems. Returns all 12 house cusps with zodiac signs, degrees, Ascendant, and Midheaven. Use \"all\" parameter to compare all 4 house systems side-by-side. Perfect for astrology charts, house cusp tables, and educational tools showing house system differences. Includes accurate Ascendant and MC calculations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Date is critical for house cusp calculations as it determines planetary positions used in some house systems."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Time is ESSENTIAL for accurate house cusps - even minutes matter. The Ascendant (1st house cusp) changes roughly every 4 minutes. Without accurate time, house placements will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Location determines the local horizon and meridian, which are fundamental to house division. Higher latitudes cause more distortion in time-based systems like Placidus."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Affects local time and horizon calculations for house cusps."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the chart date.","example":-5},"houseSystem":{"anyOf":[{"type":"string","enum":["placidus","whole-sign","equal","koch"]},{"type":"string","enum":["all"]}],"default":"placidus","example":"placidus","description":"House system for dividing ecliptic into 12 houses. Placidus (most popular) uses time, Whole Sign (ancient) uses signs, Equal divides from Ascendant. Use \"all\" to compare all 4 systems side-by-side for educational purposes."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"House cusps calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HousesResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/aspects":{"post":{"operationId":"calculateAspects","tags":["Western Astrology"],"summary":"Calculate planetary aspects - Aspect finder for any date and time","description":"Calculate all major and minor aspects between planets for any date and time. Finds conjunctions (0°), oppositions (180°), trines (120°), squares (90°), sextiles (60°), and minor aspects. Returns aspect type, exact angle, orb, applying/separating status, and strength (0-100). Filter by specific planets or aspect types. Perfect for aspect tables, transit analysis, and aspect pattern detection. Uses standard Western astrology orbs.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectsRequest"}}}},"responses":{"200":{"description":"Aspects calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/aspect-patterns":{"post":{"operationId":"detectAspectPatterns","tags":["Western Astrology"],"summary":"Detect aspect patterns - Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium","description":"Identify classical Western astrology multi-planet configurations in a birth chart. Returns Grand Trines (with element), Kites (with apex), T-Squares (with apex and modality), Grand Crosses (with modality), Yods (Finger of Fate, with apex), Mystic Rectangles, and Stelliums. Each pattern carries a tightness score (0-100), dissociate flag for out-of-sign configurations, and a one-line interpretation suitable for chart reports. Disambiguation is built in: a Grand Cross suppresses its contained T-Squares, a Kite suppresses its underlying Grand Trine. Useful for personalized natal report engines, astrology chatbots, AI agents that interpret chart geometry, and editorial chart-pattern callouts.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"false","description":"Use tighter orbs (Pontopia \"optimal\" recommendations). Truthy values (true, 1, yes, on; case-insensitive) narrow trine to 5, square to 5, sextile to 4, quincunx to 2. Defaults to false (industry-standard orbs)."},"required":false,"description":"Use tighter orbs (Pontopia \"optimal\" recommendations). Truthy values (true, 1, yes, on; case-insensitive) narrow trine to 5, square to 5, sextile to 4, quincunx to 2. Defaults to false (industry-standard orbs).","name":"strictOrbs","in":"query"},{"schema":{"type":"string","example":"","description":"Comma-separated list of optional bodies to include beyond the classical 10 planets. Valid tokens (case-insensitive): chiron, northNode (also accepts north_node, north-node, northnode). Empty by default."},"required":false,"description":"Comma-separated list of optional bodies to include beyond the classical 10 planets. Valid tokens (case-insensitive): chiron, northNode (also accepts north_node, north-node, northnode). Empty by default.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectPatternsRequest"}}}},"responses":{"200":{"description":"Aspect patterns detected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectPatternsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/transits":{"post":{"operationId":"calculateTransits","tags":["Western Astrology"],"summary":"Calculate planetary transits - Current transits with natal chart comparison","description":"Calculate current or future planetary transits (positions of all bodies now). Optionally compare transits to natal chart to find transit-to-natal aspects. Returns all 14 celestial bodies (the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith) with signs, degrees, and speeds. When natal chart provided, includes transit aspects (transiting Sun conjunct natal Mars, etc.) with orbs and applying/separating status. Perfect for daily transit forecasts, aspect alerts, and personalized transit reports.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitsRequest"}}}},"responses":{"200":{"description":"Transits calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/transit-aspects":{"post":{"operationId":"calculateTransitAspects","tags":["Western Astrology"],"summary":"Transit Aspects - Detailed transit-to-natal aspect analysis with interpretations","description":"Calculate all transit-to-natal aspects with detailed interpretations, strength ratings, and timing guidance. Compares current (or future) planetary positions against your natal chart to identify active transits. Returns aspect type, orb, applying/separating status, narrative interpretation, impact rating, and practical guidance for each transit. Supports planet and aspect-type filtering. More detailed than the /transits endpoint — includes AI-friendly interpretation fields. Transit aspects API, transit-to-natal analysis, predictive astrology, personalized transit forecast.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"natalChart":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Natal chart birth details (date, time, location, timezone). Used to calculate natal planetary positions that transits are compared against."},"transitDate":{"type":"string","format":"date","example":"2026-02-03","description":"Transit date in YYYY-MM-DD format. Defaults to current date if omitted. Use future dates for predictive transit analysis."},"transitTime":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS format. Defaults to 12:00:00 (noon) if omitted."},"planets":{"type":"array","items":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"]},"example":["Jupiter","Saturn","Pluto"],"description":"Filter to specific transiting planets. Omit to include all planets. Useful for focusing on slow-moving outer planet transits (Saturn, Jupiter, Pluto)."},"aspectTypes":{"type":"array","items":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"]},"example":["CONJUNCTION","OPPOSITION","TRINE","SQUARE"],"description":"Filter to specific aspect types (conjunction, opposition, trine, square, sextile, etc.). Omit to include all aspect types."},"minStrength":{"type":"number","minimum":0,"maximum":100,"example":50,"description":"Minimum aspect strength threshold (0-100). Higher values return only tighter, more potent aspects. Useful for filtering out wide-orb aspects."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to divide the natal chart into 12 houses. Every house number in the response is read against these natal cusps, for the natal bodies and the transiting bodies alike. Placidus (default) is time sensitive and the most widely used in Western astrology. Whole Sign assigns one sign per house. Equal divides into 30 degree segments from the Ascendant. Koch emphasizes higher latitudes. Quadrant systems fall back to Whole Sign above the polar circle."}},"required":["natalChart"]}}}},"responses":{"200":{"description":"Transit aspects calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transitDate":{"type":"string","example":"2026-02-03 12:00:00","description":"Date and time of the transit calculation."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system actually used for the natal cusps behind every house number in this response. Differs from the requested system only above the polar circle, where quadrant systems fall back to Whole Sign."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["number","longitude","sign","degree"]},"description":"The twelve NATAL house cusps that every house number in this response is read against, in the house system named by houseSystem. Same shape as the natal-chart houses array, so a bi-wheel can be drawn with real house sectors from this one response instead of pairing it with a second call."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Tropical zodiac sign on the natal Ascendant. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Absolute ecliptic longitude of the natal Ascendant in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"The natal Ascendant (rising sign): the eastern horizon at birth, and the left-hand horizon a chart wheel is oriented to. Reported alongside the cusps because the two are not the same longitude in every house system: Whole Sign puts the first cusp at 0 degrees of the rising sign, which can sit most of a sign away from the Ascendant itself."},"transitPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":10,"description":"Natal house (1-12) this transiting body is currently passing through, read against the natal house cusps. This is the life area the transit activates, so it is driven by the natal birth time and location rather than by the transit moment."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Current transiting positions in the tropical zodiac, each placed in the natal house it is passing through. All 14 celestial bodies: the 10 classical planets (Sun through Pluto), the lunar nodes, Chiron, and Black Moon Lilith."},"natalPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Natal (birth chart) planetary positions used as the baseline for transit aspect comparison, each placed in its natal house."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"transitInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun supports your natal Moon harmoniously","description":"Narrative interpretation of this transit aspect and its life impact."},"timing":{"type":"string","example":"Active for a few days","description":"When this transit is most active and how long its influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego flows easily with Inner emotional life. Opportunities arise naturally in this area.","description":"Strength and nature of this transit effect — constructive, challenging, or neutral."},"guidance":{"type":"string","example":"Take advantage of this supportive energy. Things flow easily, so act on opportunities.","description":"Practical advice for working with this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect: narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","transitInterpretation"]},"description":"Transit-to-natal aspects with interpretations, strength ratings, and guidance. Each aspect represents a transiting planet forming a geometric angle to a natal planet."},"summary":{"type":"object","properties":{"total":{"type":"number","example":12,"description":"Total number of transit-to-natal aspects found."},"harmonious":{"type":"number","example":5,"description":"Count of harmonious aspects (trine, sextile). These transits bring ease, flow, and opportunity."},"challenging":{"type":"number","example":4,"description":"Count of challenging aspects (square, opposition, semi-square, sesquiquadrate). These transits bring tension, growth pressure, and action."},"neutral":{"type":"number","example":3,"description":"Count of neutral aspects (conjunction, minor aspects). Conjunctions blend energies — the outcome depends on the planets involved."},"strongest":{"type":["object","null"],"properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"transitInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun supports your natal Moon harmoniously","description":"Narrative interpretation of this transit aspect and its life impact."},"timing":{"type":"string","example":"Active for a few days","description":"When this transit is most active and how long its influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego flows easily with Inner emotional life. Opportunities arise naturally in this area.","description":"Strength and nature of this transit effect — constructive, challenging, or neutral."},"guidance":{"type":"string","example":"Take advantage of this supportive energy. Things flow easily, so act on opportunities.","description":"Practical advice for working with this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect: narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","transitInterpretation"],"description":"The tightest aspect by orb. This is the most potent transit currently active — the one most likely to be felt."},"byType":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of transit to natal aspects of this type in the window. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"CONJUNCTION":2,"TRINE":3,"SQUARE":2,"SEXTILE":1},"description":"Transit aspect counts grouped by aspect type (conjunction, trine, square, opposition, sextile, etc.). Useful for quickly assessing the transit weather."}},"required":["total","harmonious","challenging","neutral","strongest","byType"],"description":"Statistical summary of all transit aspects. The harmonious-to-challenging ratio reveals the overall transit weather — whether the current period favors ease or demands effort."}},"required":["transitDate","houseSystem","houses","ascendant","transitPlanets","natalPlanets","aspects","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/solar-return":{"post":{"operationId":"generateSolarReturn","tags":["Western Astrology"],"summary":"Solar Return Chart - Annual birthday forecast with relocated chart","description":"Generate a solar return chart for any year, the foundational technique for annual astrological forecasting. The chart is cast for the exact moment the transiting Sun returns to its natal ecliptic longitude (your astrological birthday). Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Location-sensitive: relocating your solar return chart to a different city changes the houses and Ascendant. Solar return chart API, annual horoscope forecast, birthday chart calculator, yearly astrology prediction, relocated solar return.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine natal Sun longitude for the solar return calculation."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal Sun position for annual return timing."},"returnYear":{"type":"integer","example":2026,"description":"Year for which to cast the solar return chart. The chart is erected for the exact moment the transiting Sun conjuncts the natal Sun longitude in this year."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the solar return location in decimal degrees (-90 to 90). Use current residence or travel location at time of birthday. Solar return charts are location-sensitive."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the solar return location in decimal degrees (-180 to 180). Affects house cusps and Ascendant of the return chart."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the solar return chart. Placidus (default) is most common in Western astrology. Whole Sign, Equal, and Koch also supported."}},"required":["birthDate","birthTime","returnYear","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","returnYear":2024,"latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Solar return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal Sun longitude calculation."},"solarReturnDate":{"type":"string","example":"2026-07-15T08:42:00","description":"Exact solar return moment, when the transiting Sun conjuncts the natal Sun longitude. Adjusted to requested timezone. This is your astrological birthday for the year."},"solarReturnYear":{"type":"number","example":2026,"description":"Year of this solar return chart. Covers the period from this birthday to the next."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for Placidus house cusp and Ascendant calculation in the solar return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time and Midheaven calculation in the solar return chart."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the solar return chart. The Ascendant and house cusps change based on where you are at your birthday, a key technique in relocated solar returns."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full natal-style chart erected for the solar return moment. Contains all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith), 12 house cusps, aspects, Ascendant, and Midheaven in the tropical zodiac."},"natalSunPosition":{"type":"object","properties":{"longitude":{"type":"number","example":112.45,"description":"Natal Sun ecliptic longitude in degrees (0-360). The transiting Sun returns to this exact degree each year."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign of the natal Sun (your Sun sign)."},"degree":{"type":"number","example":22.45,"description":"Degree within the zodiac sign (0-29.999). The precise position the Sun returns to."}},"required":["longitude","sign","degree"],"description":"Original natal Sun position that the transiting Sun returns to. This conjunction defines the solar return moment."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Solar Return chart for your 2026 birthday year. This chart is cast for the exact moment the Sun returns to its natal position, symbolizing a new solar year.","description":"Narrative overview of the solar return year themes and energy."},"purpose":{"type":"string","example":"Solar return charts are used for annual forecasting. The chart reveals themes, opportunities, and challenges for the year ahead from birthday to birthday. Focus on the Ascendant sign, angular planets, and aspects to natal positions.","description":"Explanation of how to use solar return charts for annual forecasting, identifying yearly themes, and timing predictions."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Annual themes and life direction","Career and public life developments","Relationships and partnerships","Personal growth and self-expression","Home and family matters"],"description":"Key life areas and themes highlighted by this solar return chart. Focus on these for the birthday year."}},"required":["summary","purpose","keyThemes"],"description":"Solar return interpretation with annual forecast themes. Solar returns are the primary technique in Western astrology for year-ahead predictions."}},"required":["birthDate","solarReturnDate","solarReturnYear","location","chart","natalSunPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/lunar-return":{"post":{"operationId":"generateLunarReturn","tags":["Western Astrology"],"summary":"Lunar Return Chart - Monthly emotional forecast with Moon cycle chart","description":"Generate a lunar return chart for any month, cast for the exact moment the transiting Moon returns to its natal ecliptic longitude. The Moon completes one sidereal orbit every ~27.3 days, making this the primary technique for monthly astrological forecasting. Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Reveals emotional patterns, domestic focus, and intuitive themes for the coming month. Lunar return chart API, monthly horoscope forecast, Moon cycle chart, emotional astrology prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine natal Moon longitude for the lunar return calculation."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal Moon position for monthly return timing."},"returnDate":{"type":"string","format":"date","example":"2026-02-12","description":"Approximate date near the desired lunar return (YYYY-MM-DD). The Moon returns to its natal position every ~27.3 days, so provide a date within a few days of the expected return."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the lunar return location in decimal degrees (-90 to 90). Affects the Ascendant and house cusps of the return chart."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the lunar return location in decimal degrees (-180 to 180). Determines local sidereal time for house calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the lunar return chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["birthDate","birthTime","returnDate","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","returnDate":"2024-08-12","latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Lunar return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal Moon longitude calculation."},"lunarReturnDate":{"type":"string","example":"2026-02-13T19:22:00","description":"Exact lunar return moment, when the transiting Moon conjuncts the natal Moon longitude. Adjusted to requested timezone. Occurs approximately every 27.3 days (one sidereal month)."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for house cusp calculation in the lunar return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time and Midheaven in the return chart."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the lunar return chart house and Ascendant calculations."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full tropical zodiac chart erected for the lunar return moment. Contains planetary positions, house cusps, aspects, Ascendant, and Midheaven."},"natalMoonPosition":{"type":"object","properties":{"longitude":{"type":"number","example":228.72,"description":"Natal Moon ecliptic longitude in degrees (0-360). The transiting Moon returns to this position each month."},"sign":{"type":"string","example":"Scorpio","description":"Tropical zodiac sign of the natal Moon."},"degree":{"type":"number","example":18.72,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["longitude","sign","degree"],"description":"Original natal Moon position that the transiting Moon returns to. This conjunction defines the lunar return moment."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Lunar Return chart for this month. This chart is cast for the exact moment the Moon returns to its natal position, occurring approximately every 27-28 days.","description":"Narrative overview of the monthly emotional themes and lunar cycle focus areas."},"purpose":{"type":"string","example":"Lunar return charts are used for monthly forecasting. The chart reveals themes, emotional patterns, and focus areas for the coming month. Pay attention to the Moon house position and aspects to other planets for emotional tone and priorities.","description":"Explanation of how to use lunar return charts for monthly emotional forecasting and self-care planning."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Emotional patterns and inner needs","Domestic and family matters","Daily routines and habits","Intuition and subconscious patterns","Self-care and nurturing"],"description":"Key emotional patterns, domestic themes, and self-care priorities for this lunar month."}},"required":["summary","purpose","keyThemes"],"description":"Lunar return interpretation with monthly forecast. Lunar returns reveal emotional patterns, domestic focus, and intuitive themes for the upcoming ~27-day cycle."}},"required":["birthDate","lunarReturnDate","location","chart","natalMoonPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/composite-chart":{"post":{"operationId":"generateCompositeChart","tags":["Western Astrology"],"summary":"Composite Chart - Midpoint relationship chart with interpretations","description":"Generate a composite chart by calculating midpoints between two natal charts. The composite chart represents the relationship as a single entity, showing its core identity, emotional bond, communication style, and growth direction. Uses the midpoint method: planets, angles and house cusps are each the midpoint of the two natal values, so the Ascendant always sits on the first cusp. Returns composite planetary positions, house cusps, Ascendant, Midheaven, aspects, and relationship interpretation. Composite chart API, midpoint chart calculator, relationship astrology, couple chart analysis.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details (date, time, location, timezone)."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details (date, time, location, timezone)."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the composite chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["person1","person2"]},"example":{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5},"person2":{"date":"1992-03-20","time":"09:15:00","latitude":34.0522,"longitude":-118.2437,"timezone":-8},"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Composite chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details."},"compositePlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"compositeInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of self-awareness and ego. This placement gives your Sun expression a distinctly Cancer character, shaping how you navigate these areas of life.","description":"Narrative interpretation of this composite planet placement."},"relationshipMeaning":{"type":"string","example":"The composite Sun in cancer represents the core identity and purpose of your relationship. This is what you create together and how others see you as a couple.","description":"What this planet represents in the context of the relationship."},"keywords":{"type":"array","items":{"type":"string"},"example":["active","awareness","bright","confidence","consciousness","intuitive","nurturing","protective"],"description":"Key themes associated with this composite placement."}},"required":["summary","relationshipMeaning","keywords"],"description":"Composite interpretation for this planet in the relationship chart."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Composite planetary positions calculated as midpoints between both charts. Each planet represents a shared energy in the relationship."},"compositeHouses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12) in the composite chart."},"sign":{"type":"string","example":"Gemini","description":"Zodiac sign on the composite house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign (0-29.999)."},"longitude":{"type":"number","example":75.32,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["number","sign","degree","longitude"]},"description":"Composite house cusps, each the midpoint of the two natal cusps. Each house represents shared life areas in the relationship."},"compositeAscendant":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Zodiac sign on the composite Ascendant."},"degree":{"type":"number","example":15.32,"description":"Degree within the sign (0-29.999)."},"longitude":{"type":"number","example":75.32,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Composite Ascendant. Represents how the relationship presents itself to the outside world."},"compositeMidheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the composite Midheaven."},"degree":{"type":"number","example":8.76,"description":"Degree within the sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Composite Midheaven (MC). Represents shared goals, public image, and the direction the relationship grows toward."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"Aspects between composite planets. Reveals the internal dynamics and energy patterns within the relationship."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"This relationship has strong harmonious energy with natural flow and compatibility.","description":"Overall relationship interpretation based on composite chart analysis."},"strengths":{"type":"array","items":{"type":"string"},"example":["The composite Sun in cancer represents the core identity and purpose of your relationship. This is what you create together and how others see you as a couple.","The composite Moon in aquarius shows your emotional bond and how you nurture each other. This reveals your shared feelings and domestic life together.","The composite Venus in taurus reveals what you value together and how you express affection. This is the love language of your relationship."],"description":"Areas where the relationship naturally thrives."},"challenges":{"type":"array","items":{"type":"string"},"example":["More challenging aspects than harmonious - requires work and understanding."],"description":"Potential friction points and growth opportunities in the relationship."}},"required":["summary","strengths","challenges"],"description":"Composite chart interpretation with relationship strengths, challenges, and overall assessment."}},"required":["person1","person2","compositePlanets","compositeHouses","compositeAscendant","compositeMidheaven","aspects","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/compatibility-score":{"post":{"operationId":"calculateCompatibility","tags":["Western Astrology"],"summary":"Compatibility Score. Relationship compatibility analysis with category breakdown","description":"Calculate a detailed compatibility score between two birth charts using Western synastry (inter-chart aspects). Returns overall score (0-100) plus category breakdowns for romantic, emotional, intellectual, physical, and spiritual compatibility. Each category analyzes specific planetary pairs: Venus-Mars for romance, Moon-Moon for emotions, Mercury-Mercury for intellect. Includes Sun, Moon, Venus, and Mars sign compatibility narratives, element balance analysis, relationship archetype classification, and the most significant inter-chart aspects with relationship-specific interpretations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details (date, time, location, timezone). Required for calculating natal planetary positions."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details. Compared against person1 to evaluate inter-chart aspects and compatibility."}},"required":["person1","person2"]},"example":{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5},"person2":{"date":"1992-03-20","time":"09:15:00","latitude":34.0522,"longitude":-118.2437,"timezone":-8}}}}},"responses":{"200":{"description":"Compatibility score calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"overallScore":{"type":"number","minimum":0,"maximum":100,"example":72,"description":"Overall compatibility score (0-100). Weighted average across romantic, emotional, intellectual, physical, and spiritual categories."},"categories":{"type":"object","properties":{"romantic":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Romantic compatibility score based on Sun-Moon, Venus-Mars, and Sun-Venus inter-aspects."},"emotional":{"type":"number","minimum":0,"maximum":100,"example":65,"description":"Emotional compatibility score based on Moon-Moon and Moon-Venus inter-aspects."},"intellectual":{"type":"number","minimum":0,"maximum":100,"example":70,"description":"Intellectual compatibility score based on Mercury-Mercury and Sun-Mercury inter-aspects."},"physical":{"type":"number","minimum":0,"maximum":100,"example":80,"description":"Physical compatibility score based on Mars-Mars and Mars-Sun inter-aspects."},"spiritual":{"type":"number","minimum":0,"maximum":100,"example":60,"description":"Spiritual compatibility score based on Jupiter-Sun and Jupiter-Jupiter inter-aspects."}},"required":["romantic","emotional","intellectual","physical","spiritual"],"description":"Compatibility breakdown by life area. Each category evaluates specific planetary pair interactions that govern that domain."},"persons":{"type":"object","properties":{"person1":{"type":"object","properties":{"sun":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Sun sign position. Core identity and ego."},"moon":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Moon sign position. Emotional nature and instincts."},"venus":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Venus sign position. Love language and relationship style."},"mars":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Mars sign position. Passion, desire, and conflict style."}},"required":["sun","moon","venus","mars"],"description":"Key planet positions for person 1. Sun, Moon, Venus, and Mars sign placements."},"person2":{"type":"object","properties":{"sun":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Sun sign position. Core identity and ego."},"moon":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Moon sign position. Emotional nature and instincts."},"venus":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Venus sign position. Love language and relationship style."},"mars":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Mars sign position. Passion, desire, and conflict style."}},"required":["sun","moon","venus","mars"],"description":"Key planet positions for person 2. Sun, Moon, Venus, and Mars sign placements."}},"required":["person1","person2"],"description":"Summary of key planetary positions for both people. Includes the four planets most relevant to relationship compatibility."},"signCompatibility":{"type":"object","properties":{"sun":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Taurus","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Scorpio","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Taurus and Scorpio combine earth and water core energy. Naturally nurturing and fertile. Water nourishes steady growth while Earth provides a stable container. This combination creates deep security and emotional safety. Your modalities (fixed and fixed) add another layer: Deeply committed and determined. Shared resolve can move mountains, though finding room for compromise keeps the relationship from becoming a standoff.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Sun sign compatibility. Reveals core personality dynamic as a couple."},"moon":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Aquarius","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Aquarius Moon and Pisces Moon bring together air and water emotional natures. Thought meets feeling. Air brings objectivity and perspective while Water brings emotional depth and intuition. Honoring both rational and emotional ways of knowing strengthens this bond.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Moon sign compatibility. Reveals how you process emotions and nurture each other."},"venus":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Aries","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Scorpio","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Venus in Aries and Venus in Scorpio blend fire and water love styles. Passion meets emotional depth. This powerful chemistry creates transformation when balanced. Directness and sensitivity learn from each other, forging a connection that is both warm and soulful.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Venus sign compatibility. Reveals love languages and what you find beautiful together."},"mars":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Gemini","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Sagittarius","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Mars in Gemini and Mars in Sagittarius combine air and fire approaches to desire and conflict. Highly energizing and dynamic. Air fuels Fire with ideas and enthusiasm, creating an intellectually stimulating and active connection full of momentum.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Mars sign compatibility. Reveals how you handle passion, conflict, and desire."}},"required":["sun","moon","venus","mars"],"description":"Sign-by-sign compatibility analysis for the four key relationship planets. Each entry describes how the two signs interact through that planetary lens."},"elementBalance":{"type":"object","properties":{"person1":{"type":"object","properties":{"fire":{"type":"number","example":3,"description":"Count of planets in fire signs (Aries, Leo, Sagittarius)."},"earth":{"type":"number","example":2,"description":"Count of planets in earth signs (Taurus, Virgo, Capricorn)."},"air":{"type":"number","example":4,"description":"Count of planets in air signs (Gemini, Libra, Aquarius)."},"water":{"type":"number","example":3,"description":"Count of planets in water signs (Cancer, Scorpio, Pisces)."}},"required":["fire","earth","air","water"],"description":"Element distribution across person 1 natal planets."},"person2":{"type":"object","properties":{"fire":{"type":"number","example":3,"description":"Count of planets in fire signs (Aries, Leo, Sagittarius)."},"earth":{"type":"number","example":2,"description":"Count of planets in earth signs (Taurus, Virgo, Capricorn)."},"air":{"type":"number","example":4,"description":"Count of planets in air signs (Gemini, Libra, Aquarius)."},"water":{"type":"number","example":3,"description":"Count of planets in water signs (Cancer, Scorpio, Pisces)."}},"required":["fire","earth","air","water"],"description":"Element distribution across person 2 natal planets."},"sharedElement":{"type":["string","null"],"example":"water","description":"Dominant element shared by both charts, or null if dominant elements differ."},"description":{"type":"string","example":"Both charts share a dominant water element, creating natural resonance and instinctive understanding in how you approach life together.","description":"How the elemental balance between charts shapes the relationship dynamic."}},"required":["person1","person2","sharedElement","description"],"description":"Elemental balance comparison. Shows how fire, earth, air, and water energy is distributed across both charts."},"archetype":{"type":"object","properties":{"label":{"type":"string","example":"Kindred Spirits","description":"Relationship archetype label. A headline-friendly label for the dynamic."},"description":{"type":"string","example":"A natural understanding flows between you. Similar values and rhythms create a relationship that feels effortless and deeply familiar.","description":"Narrative description of the relationship archetype and what it means."}},"required":["label","description"],"description":"Relationship archetype based on score pattern, category strengths, and elemental balance. One of eight archetypes: Kindred Spirits, Opposites Attract, The Power Couple, The Nurturers, The Adventurers, Growth Partners, The Balancers, The Mystics."},"strengths":{"type":"array","items":{"type":"string"},"example":["Venus-Mars Trine: Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","Sun-Pluto Trine: Sun and Pluto connect harmoniously, creating natural ease in how self-awareness and ego blends with sex, death, and transformation.","Chiron-Moon Trine: Chiron and Moon connect harmoniously, creating natural ease in how healing and inner wounds blends with inner emotional life."],"description":"Top relationship strengths based on harmonious inter-chart aspects. Each includes the planet pair, aspect type, and relationship-specific interpretation."},"challenges":{"type":"array","items":{"type":"string"},"example":["Pluto-Saturn Square: Pluto and Saturn create dynamic tension between sex, death, and transformation and responsibility, time, and routine. Conscious effort transforms this friction into growth.","Chiron-Neptune Opposition: Chiron and Neptune create dynamic tension between healing and inner wounds and dreams, healing, and intuition. Conscious effort transforms this friction into growth."],"description":"Potential friction points based on challenging inter-chart aspects. Each includes specific guidance for navigating the tension."},"summary":{"type":"string","example":"Compatibility score: 72/100 (very good). The 18 aspects between your charts reveal 8 harmonious connections and 6 challenging dynamics.","description":"Narrative overview of the relationship compatibility, highlighting the dominant themes."},"interpretation":{"type":"string","example":"This relationship shows strong compatibility with genuine potential for lasting partnership. Most interactions feel natural and supportive, with a healthy mix of comfort and growth. Where challenges arise, both partners have the tools to work through them constructively. The overall energy favors building something meaningful together.","description":"Detailed compatibility interpretation analyzing the synastry aspect patterns between both charts."},"aspectBreakdown":{"type":"object","properties":{"total":{"type":"number","example":18,"description":"Total number of inter-chart aspects found between the two natal charts."},"harmonious":{"type":"number","example":8,"description":"Count of harmonious aspects (trine, sextile). These indicate natural ease and flow."},"challenging":{"type":"number","example":6,"description":"Count of challenging aspects (square, opposition). These create dynamic tension and growth."},"neutral":{"type":"number","example":4,"description":"Count of neutral aspects (conjunction). Outcome depends on the planets involved."}},"required":["total","harmonious","challenging","neutral"],"description":"Synastry aspect breakdown showing the balance of harmonious, challenging, and neutral inter-chart aspects."},"keyAspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"First planet in the aspect."},"planet2":{"type":"string","example":"Mars","description":"Second planet in the aspect."},"type":{"type":"string","example":"TRINE","description":"Aspect type (conjunction, trine, square, etc.)."},"orb":{"type":"number","example":2.3,"description":"Deviation from exact aspect in degrees. Tighter orb = stronger influence."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious flows easily. Challenging creates growth-oriented tension."},"description":{"type":"string","example":"Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","description":"Relationship-specific interpretation of this aspect between the two charts."}},"required":["planet1","planet2","type","orb","interpretation","description"]},"description":"The most significant inter-chart aspects involving personal planets (Sun through Saturn), sorted by strength. Each includes a relationship-specific interpretation."}},"required":["overallScore","categories","persons","signCompatibility","elementBalance","archetype","strengths","challenges","summary","interpretation","aspectBreakdown","keyAspects"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/horoscope/{sign}/daily":{"get":{"operationId":"getDailyHoroscope","tags":["Western Astrology"],"summary":"Daily horoscope by zodiac sign - Transit-based forecast with house activations","description":"Get the daily horoscope for any zodiac sign. Forecast is generated from real-time planetary transits using whole-sign house positions, so every sign receives unique content. Returns love, career, health, finance, overview with active transits, Moon sign, Moon phase, energy rating, lucky number, lucky color, and compatible signs. Content is fixed for a given date and rolls over at midnight, by default UTC. Pass date for editorial scheduling, or timezone to roll over on a local clock. Daily horoscope API, zodiac forecast, sun sign horoscope, astrology prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Forecast date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current period in the timezone parameter."},"required":false,"description":"Forecast date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Daily horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"date":{"type":"string","example":"2026-04-03","description":"Date of this daily horoscope (YYYY-MM-DD)."},"overview":{"type":"string","example":"Saturn teaches Aries through focused effort today. What feels heavy now becomes your greatest strength later. Trust the process of mastery and keep showing up.","description":"General daily overview based on Moon house activation and planetary transits. Unique per sign based on whole-sign house positions."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Love and relationship forecast. Based on Venus house position relative to this sign, providing unique guidance per sign."},"career":{"type":"string","example":"Take responsibility seriously at work. Hard work brings lasting results, even when progress feels invisible. Your reliability earns respect.","description":"Career and professional outlook. Based on Mars house position relative to this sign, with Saturn and Jupiter influences."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Health, energy, and wellness guidance for the day."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Financial outlook and money-related guidance."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable daily advice based on the dominant transit energy."},"luckyNumber":{"type":"number","example":7,"description":"Lucky number for the day."},"luckyColor":{"type":"string","example":"Gold","description":"Lucky color for the day, derived from the sign element."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element). Use for compatibility widgets, dating app onboarding, and horoscope cards."},"activeTransits":{"type":"array","items":{"type":"string"},"example":["Moon in Libra (7th house of partnerships and relationships)","Venus in Taurus (2nd house of finances and personal values)"],"description":"Active planetary transits affecting this sign today, with house activations. Each transit shows the planet, its current sign, and which house it activates for the queried sign."},"moonSign":{"type":"string","example":"Libra","description":"Current Moon sign. Changes every 2-3 days, sets the emotional tone for all signs."},"moonPhase":{"type":"string","example":"Waxing Gibbous Moon","description":"Current lunar phase (New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent)."},"energyRating":{"type":"number","minimum":1,"maximum":10,"example":7,"description":"Overall energy intensity for this sign today (1-10). Higher when more transits activate this sign directly. Useful for content widgets and visual indicators."}},"required":["sign","date","overview","love","career","health","finance","advice","luckyNumber","luckyColor","compatibleSigns","activeTransits","moonSign","moonPhase","energyRating"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/horoscope/{sign}/weekly":{"get":{"operationId":"getWeeklyHoroscope","tags":["Western Astrology"],"summary":"Weekly horoscope by zodiac sign - 7-day transit forecast","description":"Get weekly horoscope for any zodiac sign. Forecast covers a full Monday to Sunday period based on planetary transits with house-based content unique to each sign, with love, career, health, finance guidance plus lucky days, lucky numbers, and compatible signs. Pass any date inside a week to retrieve that week, or timezone to roll over on a local clock. Weekly horoscope API, zodiac weekly forecast, astrology weekly prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Any date inside the target week, in YYYY-MM-DD format. The forecast covers the Monday to Sunday week containing it. Defaults to the current period in the timezone parameter."},"required":false,"description":"Any date inside the target week, in YYYY-MM-DD format. The forecast covers the Monday to Sunday week containing it. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each Monday. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each Monday. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Weekly horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"week":{"type":"string","example":"2026-03-30","description":"Start date of the forecast week (Monday)."},"overview":{"type":"string","example":"This week features Jupiter in Leo, influencing your broader life direction. Saturn presence in Aries demands maturity and hard work, but builds lasting foundations.","description":"Weekly overview highlighting the dominant planetary transits through the sign."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Weekly love and relationship forecast."},"career":{"type":"string","example":"Focus on long-term goals and responsibilities. Hard work pays off, though progress feels slow.","description":"Weekly career and professional outlook."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Weekly health, energy, and wellness guidance."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Weekly financial outlook."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable weekly guidance based on transit patterns."},"luckyDays":{"type":"array","items":{"type":"string"},"example":["Wednesday","Friday","Sunday"],"description":"Favorable days this week, based on planetary rulership."},"luckyNumbers":{"type":"array","items":{"type":"number"},"example":[1,4,8],"description":"Lucky numbers for the week."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element)."}},"required":["sign","week","overview","love","career","health","finance","advice","luckyDays","luckyNumbers","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/horoscope/{sign}/monthly":{"get":{"operationId":"getMonthlyHoroscope","tags":["Western Astrology"],"summary":"Monthly horoscope by zodiac sign - 30-day transit forecast with key dates","description":"Get monthly horoscope for any zodiac sign with sign-specific week-by-week breakdown and real lunar phase key dates. Based on planetary transits with house activations unique to each sign, covering love, career, health, and finance for the entire month. Key dates include actual New Moon, Full Moon, and retrograde dates from ephemeris calculations. Pass any date inside a month to retrieve that month, or timezone to roll over on a local clock. Monthly horoscope API, zodiac monthly forecast, astrology monthly prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Any date inside the target month, in YYYY-MM-DD format. The forecast covers the whole calendar month containing it. Defaults to the current period in the timezone parameter."},"required":false,"description":"Any date inside the target month, in YYYY-MM-DD format. The forecast covers the whole calendar month containing it. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on the 1st. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on the 1st. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Monthly horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"month":{"type":"string","example":"2026-04","description":"Month of this forecast (YYYY-MM)."},"overview":{"type":"string","example":"April brings Jupiter influence through Leo, encouraging growth and expansion. For you, this activates your 5th house of romance, creativity, and joy. Saturn in Aries reminds you to build solid foundations.","description":"Monthly overview covering the major planetary transits and their impact on the sign."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Monthly love and relationship forecast."},"career":{"type":"string","example":"Focus on long-term career goals. Patience and persistence bring lasting success.","description":"Monthly career and professional outlook."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Monthly health and wellness guidance."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Monthly financial outlook and guidance."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable guidance for the month as a whole, derived from the Mercury house activation for this sign. Distinct from the per-week advice inside weekByWeek: this is the single takeaway for the month."},"weekByWeek":{"type":"array","items":{"type":"object","properties":{"week":{"type":"number","example":1,"description":"Week number within the month (1-4)."},"focus":{"type":"string","example":"Solitude and inner reflection","description":"Primary focus area for this week, derived from planetary house activations for this sign."},"advice":{"type":"string","example":"Focus on solitude and inner reflection this week for best results.","description":"Specific guidance for this week."}},"required":["week","focus","advice"]},"description":"Week-by-week breakdown with sign-specific focus areas based on transit house positions."},"keyDates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-15","description":"Date of the astrological event (YYYY-MM-DD)."},"event":{"type":"string","example":"New Moon. Set intentions and plant seeds for new beginnings.","description":"Astrological event active on this date (lunar phases, retrogrades, sign ingresses)."}},"required":["date","event"]},"description":"Key astrological dates this month with actual New Moon, Full Moon, and retrograde dates calculated from ephemeris data."},"luckyNumbers":{"type":"array","items":{"type":"number"},"example":[1,4,8,12],"description":"Lucky numbers for the month."},"luckyColor":{"type":"string","example":"Gold","description":"Lucky color for the month."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element)."}},"required":["sign","month","overview","love","career","health","finance","advice","weekByWeek","keyDates","luckyNumbers","luckyColor","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/planetary-returns":{"post":{"operationId":"generatePlanetaryReturn","tags":["Western Astrology"],"summary":"Planetary Return Chart - Saturn return, Jupiter return, and inner planet cycles","description":"Generate a planetary return chart for Mercury, Venus, Mars, Jupiter, or Saturn. A planetary return occurs when a transiting planet conjuncts its natal longitude, marking the beginning of a new cycle. Saturn return (~29 years) is the most significant life milestone in Western astrology. Jupiter return (~12 years) signals expansion and growth phases. Mars return (~2 years) resets energy and drive. Returns full tropical zodiac chart with all planetary positions, house cusps, and aspects. Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine the natal longitude of the selected planet."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal planet position for return timing."},"planet":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn"],"example":"Jupiter","description":"Planet for the return calculation. Supports Mercury (~88 days), Venus (~225 days), Mars (~687 days), Jupiter (~12 years), and Saturn (~29 years). Saturn return is a major life milestone in Western astrology."},"approximateDate":{"type":"string","format":"date","example":"2026-08-15","description":"Approximate date near the expected planetary return (YYYY-MM-DD). Provide a date within the expected return window. The algorithm searches from this starting point."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the return location in decimal degrees (-90 to 90). Affects house cusps and Ascendant of the return chart."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the return location in decimal degrees (-180 to 180)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the return chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["birthDate","birthTime","planet","approximateDate","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","planet":"Jupiter","approximateDate":"2024-08-15","latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Planetary return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal planet longitude calculation."},"planet":{"type":"string","example":"Jupiter","description":"Planet whose return was calculated. Each planet has a different orbital period and return significance."},"returnDate":{"type":"string","example":"2026-08-22T14:15:00","description":"Exact planetary return moment, when the transiting planet conjuncts its natal longitude. Adjusted to requested timezone. Marks the beginning of a new cycle for that planet in your life."},"approximateCycle":{"type":"string","example":"~12 years","description":"Approximate orbital period for this planet. Mercury ~88 days, Venus ~225 days, Mars ~687 days (~1.9 years), Jupiter ~12 years, Saturn ~29 years."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for house cusp calculation in the return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for Midheaven and local sidereal time."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the planetary return chart house and Ascendant calculations."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full tropical zodiac chart erected for the planetary return moment. Contains planetary positions, house cusps, aspects, Ascendant, and Midheaven."},"natalPlanetPosition":{"type":"object","properties":{"longitude":{"type":"number","example":135.33,"description":"Natal planet ecliptic longitude in degrees (0-360). The transiting planet returns to this exact degree."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign of the natal planet position."},"degree":{"type":"number","example":15.33,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["longitude","sign","degree"],"description":"Original natal planet position that defines the return. The transiting planet conjuncts this longitude to trigger the return."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"This Jupiter return marks a new cycle in the themes governed by Jupiter. The chart shows how this cycle will unfold in your life.","description":"Narrative overview of this planetary return cycle and its significance for personal development."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Growth and expansion opportunities","Wisdom and philosophical outlook","Luck and abundance","Travel and higher learning"],"description":"Key life themes activated during this return cycle. Focus areas vary by planet — Jupiter brings expansion, Saturn brings structure and responsibility."}},"required":["summary","keyThemes"],"description":"Planetary return interpretation. Saturn returns (~29 years) mark major life milestones. Jupiter returns (~12 years) signal growth cycles. Inner planet returns offer shorter-term insights."}},"required":["birthDate","planet","returnDate","approximateCycle","location","chart","natalPlanetPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/astrocartography":{"post":{"operationId":"generateAstrocartography","tags":["Western Astrology"],"summary":"Astrocartography map - planetary lines and relocation calculator","description":"Generate an astrocartography map of Midheaven, Imum Coeli, Ascendant, and Descendant planetary lines for any birth moment. Each line marks where a planet turns angular across the world, the core of relocation astrology and astro mapping. Returns right ascension, declination, the two meridian line longitudes, and sampled rising and setting curves ready to plot, with a short interpretation per line.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"chiron","description":"Optional comma separated list of extra bodies to plot beyond the ten classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Unknown values are ignored. Defaults to none."},"required":false,"description":"Optional comma separated list of extra bodies to plot beyond the ten classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Unknown values are ignored. Defaults to none.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Astrocartography planetary lines calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AstrocartographyResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/relocation-chart":{"post":{"operationId":"generateRelocationChart","tags":["Western Astrology"],"summary":"Generate relocation chart - Relocated birth chart calculator with shifted houses and angles","description":"Calculate a relocation chart (relocated birth chart) for a new place on Earth. The birth moment stays the same, so every planet keeps its natal sign and degree, while the Ascendant, Midheaven, Vertex, and all twelve house cusps are recomputed for the new latitude and longitude. Returns the relocated houses and angles, the planets that change house, the angular planets activated at the new place, and the distance and compass direction from the birthplace. Built for relocation astrology readings, astrocartography style move planning, and travel charts. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelocationChartRequest"}}}},"responses":{"200":{"description":"Relocation chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelocationChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/local-space":{"post":{"operationId":"generateLocalSpace","tags":["Western Astrology"],"summary":"Local space astrology map - Directional planetary compass lines","description":"Generate a local space astrology map that projects the natal planets onto the local horizon as compass directions and great-circle lines radiating from the birthplace. Returns each body azimuth (degrees clockwise from true north), altitude, 16-point compass direction, whether it sits above the horizon, and the latitude and longitude waypoints of its directional line. Ideal for relocation planning, directional astrology, and travel-direction maps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"chiron,lilith","description":"Optional comma-separated extra bodies to add beyond the 10 classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Omit to return the 10 classical planets only."},"required":false,"description":"Optional comma-separated extra bodies to add beyond the 10 classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Omit to return the 10 classical planets only.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Combined with time and timezone it fixes the birth instant whose planetary positions are projected onto the local horizon."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Time is essential: the local horizon rotates a full circle each day, so the azimuth (compass direction) of every body depends on the exact birth time."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birthplace latitude in decimal degrees (-90 to 90). This is the origin point of every local space line and the observer latitude used to turn each body into an azimuth and altitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birthplace longitude in decimal degrees (-180 to 180). Sets the local horizon orientation and the starting point from which the directional lines radiate."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birth date.","example":-5}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Local space map generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalSpaceResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/fixed-stars":{"post":{"operationId":"generateFixedStars","tags":["Western Astrology"],"summary":"Fixed stars and star conjunctions calculator - Regulus, Spica, Algol natal report","description":"Calculate the tropical zodiac positions of the major named fixed stars for any birth moment, including the four Royal stars and the fifteen Behenian stars, then detect conjunctions to the natal planets, Ascendant, and Midheaven. Each star returns its precessed ecliptic longitude, zodiac sign, visual magnitude, and traditional planetary nature, with a plain language interpretation for every conjunction inside the chosen orb. A focused tool for natal reports that weigh Regulus, Spica, Aldebaran, Antares, and Algol against the chart.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":3,"default":1,"example":1,"description":"Conjunction orb in degrees, the maximum separation for a star to count as conjunct a chart point. Defaults to 1, maximum 3. Widen it to surface looser contacts or tighten it for only the closest hits."},"required":false,"description":"Conjunction orb in degrees, the maximum separation for a star to count as conjunct a chart point. Defaults to 1, maximum 3. Widen it to surface looser contacts or tighten it for only the closest hits.","name":"orb","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Fixed star positions and conjunctions calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FixedStarsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/arabic-lots":{"post":{"operationId":"calculateArabicLots","tags":["Western Astrology"],"summary":"Arabic lots calculator - seven Hermetic parts including Part of Fortune and Spirit","description":"Calculate the seven Hermetic lots (Arabic parts) for any birth moment: Part of Fortune, Part of Spirit, Eros, Necessity, Courage, Victory, and Nemesis. Each lot is a sensitive point projected by arc from the Ascendant, with the day or night formula applied automatically from the chart sect. Returns the zodiac sign, degree, exact longitude, the arc used, and a plain language interpretation per lot, for Hellenistic and traditional astrology apps. Built on accurate tropical chart positions, no astronomy expertise needed.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArabicLotsRequest"}}}},"responses":{"200":{"description":"Arabic lots calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArabicLotsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/asteroids":{"post":{"operationId":"generateAsteroids","tags":["Western Astrology"],"summary":"Asteroid goddesses calculator - Ceres, Pallas, Juno, and Vesta natal positions","description":"Calculate the natal positions of the four classical asteroid goddesses, Ceres, Pallas, Juno, and Vesta, for any birth moment. Each asteroid returns its tropical zodiac sign, degree, house placement, daily speed, retrograde status, and a plain language interpretation of its meaning in the chart. Chiron is available through the natal chart endpoint, so this endpoint stays focused on the four asteroid goddesses for natal reports and relationship astrology.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsteroidsRequest"}}}},"responses":{"200":{"description":"Asteroid positions calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsteroidsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/lilith":{"post":{"operationId":"generateLilith","tags":["Western Astrology"],"summary":"Black Moon Lilith calculator - mean and true lunar apogee in the natal chart","description":"Calculate Black Moon Lilith for any birth chart, both the mean lunar apogee, the steady and most widely used point, and the true or osculating apogee, the exact position that can shift sign and turn retrograde. Returns the zodiac sign, degree, house, ecliptic longitude and latitude, daily speed, retrograde flag, and a plain language interpretation for each variant. Built for natal astrology apps and AI agents exploring the wild, suppressed, and reclaimed self that Lilith represents.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LilithRequest"}}}},"responses":{"200":{"description":"Black Moon Lilith calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LilithResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/progressions":{"post":{"operationId":"generateProgressions","tags":["Western Astrology"],"summary":"Secondary progressions calculator - progressed chart, progressed Sun and Moon","description":"Generate the secondary progressed chart for any date using the day-for-a-year key, where each day of ephemeris motion after birth stands in for one year of life. Returns every progressed body with its sign, degree, whole-sign house, motion, and retrograde state, plus the progressed Ascendant and Midheaven via the Naibod arc. The progressed Sun and progressed Moon are the headline timing markers for inner growth and emotional chapters. Secondary progressions API, progressed chart calculator, progressed Sun and Moon, progressed Ascendant and Midheaven.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressionsRequest"}}}},"responses":{"200":{"description":"Progressed chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressionsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/solar-arc":{"post":{"operationId":"generateSolarArc","tags":["Western Astrology"],"summary":"Solar arc directions calculator - directed chart at one degree per year","description":"Calculate a solar arc directed chart for any birth moment and target date. The solar arc is the secondary-progressed Sun longitude minus the natal Sun longitude, about one degree for each year of life, and every natal point including the Ascendant and Midheaven is advanced forward by that same arc. Returns the solar arc, each directed point with its natal and directed longitude, zodiac sign, degree, and a plain language interpretation, for predictive astrology apps timing major life events. Built on accurate tropical chart positions, no astronomy expertise needed.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarArcRequest"}}}},"responses":{"200":{"description":"Solar arc directed chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarArcResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrology/profections":{"post":{"operationId":"generateProfections","tags":["Western Astrology"],"summary":"Annual profections calculator - lord of the year and yearly time lord by age","description":"Calculate the annual profection and lord of the year for any birth chart and target date using the Hellenistic time lord technique. Each completed year of life advances the rising sign by one whole sign house, activating a new profected house, profected sign, and ruling planet that sets the tone of the year. Returns the age, profected house and sign, the lord of the year with its natal sign and house placement, and a plain language interpretation for traditional and Hellenistic astrology apps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfectionsRequest"}}}},"responses":{"200":{"description":"Annual profection calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfectionsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/birth-chart":{"post":{"operationId":"generateBirthChart","tags":["Vedic Astrology"],"summary":"Get birth chart (D1 Rashi chart) - Kundli Calculator API","description":"Calculate complete Vedic birth chart (Janam Kundli, natal chart) with all 9 planetary positions (Sun through Ketu) plus Ascendant (Lagna). Kundli calculator API for astrology apps, matrimonial sites. Returns accurate graha positions grouped by zodiac signs (rashis) with nakshatra details and pada. Perfect for kundli generation, horoscope matching, and Vedic astrology software integration.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthChartRequest"}}}},"responses":{"200":{"description":"D1 Rashi birth chart with all 12 houses, 9 grahas plus Lagna, combustion analysis (Surya Siddhanta limits, applied as the standard ecliptic longitude orb), planetary war detection, bhava interpretations, and a meta lookup keyed by planet name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/navamsa":{"post":{"operationId":"generateNavamsa","tags":["Vedic Astrology"],"summary":"Get Navamsa chart (D9) - Marriage Compatibility Calculator","description":"Calculate Navamsa (D9 divisional chart) for marriage compatibility analysis, spouse prediction, and spiritual life assessment. Navamsa calculator API reveals planetary strength in married life. Each planetary position is divided into 9 parts for accurate marriage astrology. Detects Vargottama planets (exalted status). Essential for matrimonial matching, relationship prediction, and marital harmony analysis in Vedic astrology.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NavamsaRequest"}}}},"responses":{"200":{"description":"D9 Navamsa chart with all 12 houses, 9 grahas plus Lagna, Vargottama planet detection, and Vargottama significance explanation. Same structure as birth chart response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NavamsaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/divisional-chart":{"post":{"operationId":"generateDivisionalChart","tags":["Vedic Astrology"],"summary":"Get divisional chart (Varga) - D2 to D60 Calculator","description":"Calculate any Vedic divisional chart (Varga) from D2 Hora to D60 Shashtiamsa. Divisional charts divide each zodiac sign into smaller segments to reveal detailed insights about specific life areas: wealth (D2), siblings (D3), property (D4), children (D7), marriage (D9), career (D10), parents (D12), vehicles (D16), spirituality (D20), education (D24), strength (D27), misfortunes (D30), merit (D40), character (D45), and past life karma (D60). Based on Brihat Parashara Hora Shastra (BPHS) Shodasha Varga system. Detects Vargottama planets (same sign in D1 and selected chart).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionalChartRequest"}}}},"responses":{"200":{"description":"Divisional chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionalChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/compatibility":{"post":{"operationId":"calculateGunMilan","tags":["Vedic Astrology"],"summary":"Calculate compatibility score - Gun Milan API (Ashtakoot Matching)","description":"Calculate detailed Ashtakoot compatibility (Gun Milan) for kundli matching between two people. Returns accurate 36-point Guna Milan scale with breakdown across all 8 kootas (Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi), Nadi and Bhakoot dosha detection with classical cancellation analysis per Muhurta Martanda and BPHS rules, and marriage recommendation. Perfect for kundli matching for marriage, matrimonial platforms, horoscope compatibility, and Vedic matchmaking services.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityRequest"}}}},"responses":{"200":{"description":"Ashtakoot Gun Milan result with total score out of 36, percentage, compatibility verdict, detected doshas (Nadi/Bhakoot) with cancellation analysis, dosha cancellation reasons when applicable, recommendation, and detailed breakdown of all 8 kootas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/planetary-positions":{"post":{"operationId":"getPlanetPositions","tags":["Vedic Astrology"],"summary":"Get planetary positions - Graha Positions API","description":"Get simplified planetary positions (graha positions) for all 9 planets (Sun through Ketu) plus Ascendant (Lagna). Real-time planet transit calculator for Vedic astrology. Navagraha positions API with nakshatra, pada, and rashi details. Includes house number placement using Whole Sign house system from Lagna. Faster response for basic planetary data without full chart structure. Perfect for planetary alignment tracking, daily transit updates, and astrology widgets.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanetaryPositionsRequest"}}}},"responses":{"200":{"description":"Successful planetary positions calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanetaryPositionsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/planetary-positions/monthly":{"post":{"operationId":"getMonthlyEphemeris","tags":["Vedic Astrology"],"summary":"Monthly Ephemeris - Daily sidereal planetary positions for a month","description":"Get daily sidereal ecliptic positions for all 9 Vedic planets (Navagraha) for an entire month. Returns longitude, zodiac sign, degree within sign, and retrograde status for each planet on each day. Calculated at noon UTC. Omit year and month to get the month in progress, so a published ephemeris page stays current without a redeploy. Essential for ephemeris generation, transit tracking, and planetary movement visualization. Monthly planetary ephemeris API, sidereal position table, daily graha gochara positions, ecliptic longitude calculator.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly ephemeris (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for ephemeris. Defaults to the current month (UTC)."},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}}}}}},"responses":{"200":{"description":"Monthly ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the ephemeris. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":2,"description":"Month of the ephemeris. Echoes the month that was requested, or the current UTC month when it was omitted."},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-02-01","description":"Date in YYYY-MM-DD format."},"positions":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Planet name, one of the Navagraha (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Marte","description":"Planet name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet exactly. Rahu and Ketu are rendered as the lunar nodes they are, so Spanish returns Nodo Norte and Nodo Sur while Hindi returns their Sanskrit names."},"longitude":{"type":"number","example":285.6732,"description":"Sidereal ecliptic longitude in degrees (0-360) using Lahiri ayanamsa."},"sign":{"type":"string","example":"Capricorn","description":"Zodiac sign (rashi) the planet occupies on this date. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Capricornio","description":"Zodiac sign name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat sign exactly."},"degreeInSign":{"type":"number","example":15.6732,"description":"Degrees traversed within the current sign (0-30). Useful for precise transit tracking."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in retrograde motion (vakri) on this date."}},"required":["planet","longitude","sign","degreeInSign","isRetrograde"]},"description":"Sidereal positions of all 9 Vedic planets on this date at noon UTC."}},"required":["date","positions"]},"description":"Daily planetary position entries for the entire month."}},"required":["year","month","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/current":{"post":{"operationId":"getCurrentDasha","tags":["Vedic Astrology"],"summary":"Get current Mahadasha, Antardasha, Pratyantardasha, Sookshma, Prana - Dasha Calculator API","description":"Calculate all five running Vimshottari Dasha levels (Mahadasha, Antardasha, Pratyantardasha, Sookshma, Prana) with remaining time in each. Accurate dasha calculator API for life phase prediction and planetary period analysis. Returns the dasha timeline with start/end dates for every level, ready for a current DBA readout down to hour-level timing. Set significators true to add the KP star lord, sub lord, signified houses and strength grade of each running lord, plus the houses they have in common. Essential for understanding current planetary influences, dasha transitions, and timing events in Vedic astrology. 120-year dasha system based on moon nakshatra at birth, with selectable Lahiri or KP ayanamsa.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Currently active Mahadasha, Antardasha, Pratyantardasha, Sookshma and Prana dasha with start/end dates, remaining balance, Moon nakshatra, and Vedic interpretations for each period.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"moonNakshatra":{"type":"integer","minimum":1,"maximum":27,"example":15,"description":"Birth Moon nakshatra number (1-27). This nakshatra determines the starting dasha lord in the Vimshottari 120-year cycle."},"nakshatraName":{"type":"string","example":"Swati","description":"Name of the birth Moon nakshatra (lunar mansion). One of 27 Vedic nakshatras from Ashwini to Revati."},"nakshatraLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Vimshottari dasha lord of the birth nakshatra. This planet rules the first Mahadasha in the native life cycle."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"mahadasha":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."}},"required":["planet","startDate","endDate","durationYears"],"description":"Mahadasha (major planetary period) in the 120-year Vimshottari dasha cycle. Start and end dates are determined by Moon nakshatra at birth."},"antardasha":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord"],"description":"Antardasha (bhukti), sub-period within a Mahadasha. Each Mahadasha contains 9 Antardashas proportional to the Vimshottari years of each planet."},"pratyantardasha":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord"],"description":"Pratyantardasha (sub-sub-period), the third level of the Vimshottari dasha hierarchy, Provides finer timing within each Antardasha for event prediction."},"sookshmaDasha":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Parent Pratyantardasha lord under which this Sookshma dasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord","pratyantardashaLord"],"description":"Sookshma dasha (sookshma antardasha), the fourth level of the Vimshottari dasha hierarchy. Each Pratyantardasha divides into 9 Sookshma periods running roughly 3 to 30 days each, used for day-level event timing and muhurta style selection."},"pranaDasha":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Parent Pratyantardasha lord under which this Sookshma dasha runs."},"sookshmaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Sookshma dasha lord under which this Prana dasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord","pratyantardashaLord","sookshmaLord"],"description":"Prana dasha (praana antardasha), the fifth and finest level of the Vimshottari dasha hierarchy. Each Sookshma dasha divides into 9 Prana periods, running from about 20 minutes inside a Sun Mahadasha to about 4 days inside a Saturn one. This is the level that takes Vimshottari from day-level to hour-level timing, used for muhurta selection and pinpointing the trigger inside an already identified window."},"commonHouses":{"type":"object","properties":{"allLevels":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11],"description":"Houses signified by ALL FIVE running lords at once (Mahadasha through Prana). The tightest reading available: a house every active level carries is the one the current moment is pointed at. Often empty, which is itself informative, it means the five levels do not converge on a single house."},"dashaBhuktiAntara":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,5],"description":"Houses signified by the Mahadasha, Antardasha and Pratyantardasha lords together, the classical KP three-lord test used to decide whether a matter fructifies in the running period. Wider than allLevels because it ignores the two fastest levels, which is what makes it the practical filter for month-scale predictions."}},"required":["allLevels","dashaBhuktiAntara"],"description":"Houses common to the significators of the running dasha lords. In KP a matter fructifies under lords that jointly signify the houses of that matter, so these two sets are what a prediction is checked against."},"remainingInMahadasha":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Time remaining in the currently running Mahadasha (major period)."},"remainingInAntardasha":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Time remaining in the currently running Antardasha (sub-period) within the Mahadasha."},"remainingInPratyantardasha":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Time remaining in the currently running Pratyantardasha (sub-sub-period)."},"remainingInSookshma":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Time remaining in the currently running Sookshma dasha (fourth level). Sookshma periods last days rather than months, so this value turns over quickly."},"remainingInPrana":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Time remaining in the currently running Prana dasha (fifth level). Prana periods run hours to days, so totalDays is often 0 or 1 and the years and months fields are almost always zero."}},"required":["moonNakshatra","nakshatraName","nakshatraLord","moonLongitude","ayanamsa","ayanamsaType","mahadasha","antardasha","pratyantardasha","sookshmaDasha","pranaDasha","remainingInMahadasha","remainingInAntardasha","remainingInPratyantardasha","remainingInSookshma","remainingInPrana"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/major":{"post":{"operationId":"getMajorDashas","tags":["Vedic Astrology"],"summary":"Get all 9 Mahadasha periods (120-year cycle)","description":"Returns complete Vimshottari Dasha cycle starting from birth. Shows all major planetary periods from birth through 120 years.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Complete 120-year Vimshottari Dasha timeline with all 9 Mahadasha periods, birth dasha balance, Moon nakshatra, and start/end dates for each planetary period.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"moonNakshatra":{"type":"integer","minimum":1,"maximum":27,"example":15,"description":"Birth Moon nakshatra number (1-27) that determines the Vimshottari starting point."},"nakshatraName":{"type":"string","example":"Swati","description":"Birth Moon nakshatra name, one of 27 Vedic lunar mansions."},"nakshatraLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Dasha lord of the birth nakshatra, rules the first Mahadasha."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"birthDashaBalance":{"type":"object","properties":{"years":{"type":"number","example":2,"description":"Full years remaining in this Vimshottari dasha period."},"months":{"type":"number","example":4,"description":"Additional months remaining beyond full years."},"days":{"type":"number","example":15,"description":"Additional days remaining beyond full months."},"totalDays":{"type":"number","example":865,"description":"Total remaining days in this dasha period. Useful for progress calculations."}},"required":["years","months","days","totalDays"],"description":"Remaining balance of the first Mahadasha at birth. Based on Moon degree within the birth nakshatra. partial dasha already elapsed before birth."},"mahadashas":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."}},"required":["planet","startDate","endDate","durationYears"],"description":"Mahadasha (major planetary period) in the 120-year Vimshottari dasha cycle. Start and end dates are determined by Moon nakshatra at birth."},"description":"Complete sequence of all 9 Mahadasha periods spanning 120 years from birth. Follows the Vimshottari order: Ketu(7), Venus(20), Sun(6), Moon(10), Mars(7), Rahu(18), Jupiter(16), Saturn(19), Mercury(17)."},"totalYears":{"type":"number","example":120,"description":"Total Vimshottari cycle length in years (always 120)."}},"required":["moonNakshatra","nakshatraName","nakshatraLord","moonLongitude","ayanamsa","ayanamsaType","birthDashaBalance","mahadashas","totalYears"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/sub/{mahadasha}":{"post":{"operationId":"getSubDashas","tags":["Vedic Astrology"],"summary":"Get all Antardashas (sub-periods) for a specific Mahadasha","description":"Returns 9 Antardasha sub-periods within a Mahadasha. Each Mahadasha is divided into 9 proportional sub-periods.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Mahadasha planet name, case-insensitive (e.g., jupiter, Jupiter, JUPITER all work). Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury."},"required":true,"description":"Mahadasha planet name, case-insensitive (e.g., jupiter, Jupiter, JUPITER all work). Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury.","name":"mahadasha","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"All 9 Antardasha sub-periods within the specified Mahadasha, with start/end dates and the parent Mahadasha period details.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling planet of the requested Mahadasha period."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"mahadashaPeriod":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."}},"required":["planet","startDate","endDate","durationYears"],"description":"Full details of the parent Mahadasha including start/end dates and duration."},"antardashas":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord"],"description":"Antardasha (bhukti), sub-period within a Mahadasha. Each Mahadasha contains 9 Antardashas proportional to the Vimshottari years of each planet."},"minItems":1,"maxItems":9,"description":"Antardasha (bhukti) sub-periods within this Mahadasha, proportional to each planet Vimshottari years, sorted chronologically. Nine for any Mahadasha the native lived through in full. FEWER than nine for the first Mahadasha in the chart, because the Vimshottari cycle was already running at birth: the Antardashas that ended before the birth date are not part of the chart, and the one in force at birth starts on the birth date."}},"required":["mahadashaLord","moonLongitude","ayanamsa","ayanamsaType","mahadashaPeriod","antardashas"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/sub/{mahadasha}/{antardasha}":{"post":{"operationId":"getPratyantardashas","tags":["Vedic Astrology"],"summary":"Get all Pratyantardashas (antara periods) for a Mahadasha and Antardasha","description":"Pratyantardasha calculator API. Returns the 9 Pratyantardasha (antara) periods inside a chosen Antardasha, the third level of the Vimshottari dasha hierarchy. Use it to drill from a Mahadasha into month level timing for event prediction, muhurta selection, and dasha timeline UIs. Each period is proportional to the Vimshottari years of its lord.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Mahadasha planet name, case-insensitive (e.g. saturn, Saturn, SATURN all work). Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury."},"required":true,"description":"Mahadasha planet name, case-insensitive (e.g. saturn, Saturn, SATURN all work). Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury.","name":"mahadasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive. Every Mahadasha contains all 9 lords, so a repeat such as saturn/saturn is valid."},"required":true,"description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive. Every Mahadasha contains all 9 lords, so a repeat such as saturn/saturn is valid.","name":"antardasha","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"All 9 Pratyantardasha periods within the specified Mahadasha and Antardasha, with start/end dates and the parent Antardasha period details.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Ruling planet of the requested Mahadasha period."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Ruling planet of the requested Antardasha sub-period."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"antardashaPeriod":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord"],"description":"Full details of the parent Antardasha including start/end dates and duration."},"pratyantardashas":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord"],"description":"Pratyantardasha (sub-sub-period), the third level of the Vimshottari dasha hierarchy, Provides finer timing within each Antardasha for event prediction."},"minItems":1,"maxItems":9,"description":"Pratyantardasha (antara) periods within this Antardasha, proportional to each planet Vimshottari years, sorted chronologically and starting with the Antardasha lord. Fewer than nine only when the parent Antardasha is the one that was already running at birth, in which case the periods that ended before the birth date are omitted."}},"required":["mahadashaLord","antardashaLord","moonLongitude","ayanamsa","ayanamsaType","antardashaPeriod","pratyantardashas"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/sub/{mahadasha}/{antardasha}/{pratyantardasha}":{"post":{"operationId":"getSookshmaDashas","tags":["Vedic Astrology"],"summary":"Get all Sookshma dashas for a Mahadasha, Antardasha and Pratyantardasha","description":"Sookshma dasha API. Returns the 9 Sookshma periods inside a chosen Pratyantardasha, the fourth and finest level of the Vimshottari dasha hierarchy. Completes a full vimshottari drill down from the 120-year cycle to day level timing, typically 3 to 30 days per period. Built for dasha drill down tables, current DBA readouts, and precise event timing in Vedic astrology software.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Mahadasha planet name, case-insensitive. Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury."},"required":true,"description":"Mahadasha planet name, case-insensitive. Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury.","name":"mahadasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive."},"required":true,"description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive.","name":"antardasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Pratyantardasha (antara) planet name inside that Antardasha, case-insensitive."},"required":true,"description":"Pratyantardasha (antara) planet name inside that Antardasha, case-insensitive.","name":"pratyantardasha","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"All 9 Sookshma dasha periods within the specified Mahadasha, Antardasha, and Pratyantardasha, with start/end dates and the parent Pratyantardasha period details.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Ruling planet of the requested Mahadasha period."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Ruling planet of the requested Antardasha sub-period."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Ruling planet of the requested Pratyantardasha sub-sub-period."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"pratyantardashaPeriod":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord"],"description":"Full details of the parent Pratyantardasha including start/end dates and duration."},"sookshmaDashas":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Parent Pratyantardasha lord under which this Sookshma dasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord","pratyantardashaLord"],"description":"Sookshma dasha (sookshma antardasha), the fourth level of the Vimshottari dasha hierarchy. Each Pratyantardasha divides into 9 Sookshma periods running roughly 3 to 30 days each, used for day-level event timing and muhurta style selection."},"minItems":1,"maxItems":9,"description":"Sookshma dasha periods within this Pratyantardasha, proportional to each planet Vimshottari years, sorted chronologically and starting with the Pratyantardasha lord. Fewer than nine only when the parent Pratyantardasha is the one that was already running at birth, in which case the periods that ended before the birth date are omitted."}},"required":["mahadashaLord","antardashaLord","pratyantardashaLord","moonLongitude","ayanamsa","ayanamsaType","pratyantardashaPeriod","sookshmaDashas"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dasha/sub/{mahadasha}/{antardasha}/{pratyantardasha}/{sookshma}":{"post":{"operationId":"getPranaDashas","tags":["Vedic Astrology"],"summary":"Get all Prana dashas for a Mahadasha, Antardasha, Pratyantardasha and Sookshma","description":"Prana dasha API. Returns the 9 Prana periods inside a chosen Sookshma dasha, the fifth and finest level of the Vimshottari dasha hierarchy. Completes the full vimshottari drill down from the 120-year cycle to hour level timing, typically 20 minutes to 4 days per period depending on the parent Mahadasha. Built for five column dasha drill down tables, muhurta selection, and pinpointing the trigger moment inside an event window already found at the Sookshma level.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Mahadasha planet name, case-insensitive. Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury."},"required":true,"description":"Mahadasha planet name, case-insensitive. Valid: Ketu, Venus, Sun, Moon, Mars, Rahu, Jupiter, Saturn, Mercury.","name":"mahadasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive."},"required":true,"description":"Antardasha (bhukti) planet name inside that Mahadasha, case-insensitive.","name":"antardasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Pratyantardasha (antara) planet name inside that Antardasha, case-insensitive."},"required":true,"description":"Pratyantardasha (antara) planet name inside that Antardasha, case-insensitive.","name":"pratyantardasha","in":"path"},{"schema":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Sookshma dasha planet name inside that Pratyantardasha, case-insensitive. Every full period contains all 9 lords, so a repeat such as saturn/saturn/saturn/saturn is valid."},"required":true,"description":"Sookshma dasha planet name inside that Pratyantardasha, case-insensitive. Every full period contains all 9 lords, so a repeat such as saturn/saturn/saturn/saturn is valid.","name":"sookshma","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas)."},"time":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions. It changes every two hours roughly. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly. Defaults to 5.5.","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"default":"lahiri","example":"lahiri","description":"Ayanamsa system used to place the birth Moon in its nakshatra, which sets every dasha start and end date. \"lahiri\" uses Lahiri/Chitrapaksha, the traditional Vedic standard, and is the default. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, matching Krishnamurti Paddhati software. \"kp-old\" uses the Krishnamurti original table from KP Reader-1. \"raman\" uses the B.V. Raman ayanamsa, the second frame traditional Indian software commonly offers beside Lahiri. \"custom\" takes your own value in degrees via ayanamsaValue, for reconciling exactly against a specific reference program. Switching frames shifts every dasha boundary by weeks, so pick the one your reference software uses."},"ayanamsaValue":{"type":"number","example":24,"description":"Custom ayanamsa value in degrees. When provided, overrides the computed ayanamsa from the selected type. Use for testing with specific ayanamsa values or matching a particular reference source."},"significators":{"type":"boolean","default":false,"example":false,"description":"Set true to attach the KP significators of each period lord: its star lord, sub lord, occupied house, the houses it signifies at levels L1 to L4, and a strength grade. Off by default, so responses stay exactly as they are for clients that only need dates. Requires the birth latitude and longitude, since significators are read off a Placidus house chart, and uses the same ayanamsa frame selected above."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu, used ONLY when \"significators\" is true. Dasha dates themselves come from the Moon and never move with this field. \"mean\" uses the smooth mean node (traditional default). \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean over a 173-day cycle and can therefore change which house or star a node falls in. Defaults to \"mean\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"All 9 Prana dasha periods within the specified Mahadasha, Antardasha, Pratyantardasha, and Sookshma dasha, with start/end dates and the parent Sookshma period details.","content":{"application/json":{"schema":{"type":"object","properties":{"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Ruling planet of the requested Mahadasha period."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Venus","description":"Ruling planet of the requested Antardasha sub-period."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Ruling planet of the requested Pratyantardasha sub-sub-period."},"sookshmaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling planet of the requested Sookshma dasha."},"moonLongitude":{"type":"number","example":190.994,"description":"Sidereal (nirayana) longitude of the birth Moon in degrees, 0 to 360, measured in the ayanamsa frame reported below. This single value determines the birth nakshatra and therefore every dasha start and end date in this response. Compare it against a reference chart to reconcile any date difference at its source."},"ayanamsa":{"type":"number","example":23.72167,"description":"Ayanamsa actually applied, in degrees. The precession offset subtracted from the tropical (sayana) longitude to get the sidereal (nirayana) one. Lahiri sits near 23 deg 43 min for a 1990 birth, KP-Newcomb near 23 deg 38 min."},"ayanamsaType":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman","custom"],"example":"lahiri","description":"Ayanamsa system used, echoing the request field. One of \"lahiri\", \"kp-newcomb\", \"kp-old\" or \"custom\". Echoed so a client can confirm which frame produced these dates without re-deriving it. When it reads \"custom\" the ayanamsa field above carries the exact value you supplied."},"sookshmaPeriod":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Parent Pratyantardasha lord under which this Sookshma dasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord","pratyantardashaLord"],"description":"Full details of the parent Sookshma dasha including start/end dates and duration."},"pranaDashas":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling graha of this Vimshottari dasha period. One of 9 planets in the Ketu-Venus-Sun-Moon-Mars-Rahu-Jupiter-Saturn-Mercury sequence."},"startDate":{"type":"string","example":"1990-07-04T10:12:00","description":"Start datetime of this dasha period. Adjusted to the requested timezone offset."},"endDate":{"type":"string","example":"1996-07-04T10:12:00","description":"End datetime of this dasha period. Adjusted to the requested timezone offset."},"durationYears":{"type":"number","example":6,"description":"Duration of this dasha period in years. Mahadasha durations range from 6 years (Sun) to 20 years (Venus)."},"nominalStartDate":{"type":"string","example":"1984-09-01T09:00:00","description":"Theoretical start of this period, present ONLY when the birth date truncated it. The Vimshottari cycle is already running when a native is born, so the period in force at birth began earlier: startDate is clipped to the birth moment while this field keeps the real start. Its presence is also why the first period of a chart can contain fewer than 9 sub-periods, the earlier ones having finished before birth. Absent on every period that runs its full length."},"interpretation":{"type":"string","example":"Sun Mahadasha brings leadership opportunities, authority, and self-expression.","description":"Vedic interpretation of the planetary period describing themes, karmic lessons, and life areas affected by this graha."},"significators":{"type":"object","properties":{"house":{"type":"integer","minimum":1,"maximum":12,"example":11,"description":"House 1-12 this lord occupies in the Placidus birth chart. Its own Level 2 signification, repeated here because the occupied house is the first thing a KP reading looks at."},"starLord":{"type":"string","example":"Moon","description":"Lord of the nakshatra this planet sits in, one of the 9 grahas. In KP the star lord outranks the planet itself: a period lord mainly delivers the houses its star lord occupies and owns, which is why those appear at L1 and L3 rather than the planet own house."},"subLord":{"type":"string","example":"Venus","description":"KP sub lord of this planet, the 1 of 249 subdivision its longitude falls in, one of the 9 grahas. The star lord says WHAT results the period gives, the sub lord says WHETHER they materialize, so KP judgement checks both."},"signifies":{"type":"object","properties":{"L1":{"type":"array","items":{"type":"integer"},"example":[11,6],"description":"Level 1, the strongest signification (grade A). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes the L1 houses of their agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"integer"},"example":[11],"description":"Level 2 (grade B). The house this planet physically occupies. For Rahu and Ketu, also includes houses occupied by their agent planets."},"L3":{"type":"array","items":{"type":"integer"},"example":[3,8],"description":"Level 3 (grade C). Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes the L3 houses of their agent planets."},"L4":{"type":"array","items":{"type":"integer"},"example":[5,6],"description":"Level 4, the weakest signification (grade D). Houses this planet rules by zodiac sign ownership, up to 2 for Sun through Saturn and 3 where a sign is intercepted. Rahu and Ketu own no sign, so their L4 comes entirely from their agent planets."}},"required":["L1","L2","L3","L4"],"description":"KP 4-level significator breakdown showing which houses (1-12) this planet signifies at each strength tier. L1 is strongest, L4 is weakest."},"signifiedHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6,3,8,5],"description":"Every house this lord signifies, deduplicated and ordered strongest tier first. Where a house is reached at more than one level it is listed once, at its strongest. This is the flat \"houses signified\" column of a KP dasha table."},"strongHouses":{"type":"array","items":{"type":"integer","minimum":1,"maximum":12},"example":[11,6],"description":"Subset of signifiedHouses reached at grade A or B (levels L1 and L2). These are the houses a KP reading acts on for this period; the rest are supporting connections."},"strength":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"example":62.5,"description":"Mean KP percentage weight across signifiedHouses, each house counted at its strongest level (A 100, B 75, C 50, D 25). A mean rather than a total, so signifying many houses weakly does not outrank signifying two houses at grade A."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"B","description":"Band the score falls in, on the standard KP significator grading: A planets in the constellation of the occupant, B occupants, C planets in the constellation of the house owner, D the house owner. Band edges are the midpoints between the four weights."},"label":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"strong","description":"Plain-language form of grade: \"very-strong\" for A, \"strong\" for B, \"moderate\" for C, \"weak\" for D. Says how firmly this lord is connected to the houses it signifies, NOT whether those houses are favourable, which depends on the matter being judged."}},"required":["score","grade","label"],"description":"How firmly this lord is tied to the houses it signifies, on the KP A to D significator grading. Reproducible from the significator levels alone, in two steps. STEP 1, per house keep only the strongest level: a planet routinely reaches the same house at more than one level, for example its star lord occupies house 11 and it also owns house 11, and KP cites a significator by its best connection, so that house counts once at grade A. This is why signifiedHouses is shorter than the four level arrays concatenated, and omitting it is what makes a hand calculation disagree. STEP 2, average the surviving weights: each house contributes 100, 75, 50 or 25 for grade A, B, C or D, and the mean is the score. Worked example, a lord signifying house 11 at level 1, house 6 at level 2 and house 2 at level 4 scores (100 + 75 + 25) / 3 = 66.7, which lands in band B because the band edges are the midpoints 87.5, 62.5 and 37.5. The score says how firmly the lord is connected, never whether the houses are favourable, which depends on the matter being judged."}},"required":["house","starLord","signifies","signifiedHouses","strongHouses","strength"],"description":"KP significators of this period lord, read from the Placidus birth chart in the requested ayanamsa. Present only when the request sets \"significators\": true."},"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Mahadasha lord under which this Antardasha sub-period runs."},"antardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Saturn","description":"Parent Antardasha lord under which this Pratyantardasha runs."},"pratyantardashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Rahu","description":"Parent Pratyantardasha lord under which this Sookshma dasha runs."},"sookshmaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Parent Sookshma dasha lord under which this Prana dasha runs."}},"required":["planet","startDate","endDate","durationYears","mahadashaLord","antardashaLord","pratyantardashaLord","sookshmaLord"],"description":"Prana dasha (praana antardasha), the fifth and finest level of the Vimshottari dasha hierarchy. Each Sookshma dasha divides into 9 Prana periods, running from about 20 minutes inside a Sun Mahadasha to about 4 days inside a Saturn one. This is the level that takes Vimshottari from day-level to hour-level timing, used for muhurta selection and pinpointing the trigger inside an already identified window."},"minItems":1,"maxItems":9,"description":"Prana dasha periods within this Sookshma dasha, proportional to each planet Vimshottari years, sorted chronologically and starting with the Sookshma lord. Fewer than nine only when the parent Sookshma dasha is the one that was already running at birth, in which case the periods that ended before the birth date are omitted."}},"required":["mahadashaLord","antardashaLord","pratyantardashaLord","sookshmaLord","moonLongitude","ayanamsa","ayanamsaType","sookshmaPeriod","pranaDashas"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/daily":{"post":{"operationId":"getVedicDailyReading","tags":["Vedic Astrology"],"summary":"Daily Reading - Composed Gochara, Panchanga and Dasha for one native on one day","description":"The composed Vedic daily reading for one native on one date, in one call. Runs classical Gochara as the gate pipeline the texts describe: the house each transiting graha makes from the natal Moon (Janma Rashi), the vedha pair that can cancel it, the Ashtakavarga bindu gate that decides whether it is delivered, and the Phaladeepika XXVI.30 to XXVI.32 nullifiers, so every graha lands in ONE cited state rather than a bar of a chart. Joined to the panchanga day, which runs sunrise to sunrise with a validity window on every limb, plus tarabala and chandrabala resolved for THIS native as windows rather than as one value, the running Vimshottari chain three levels deep, and a KP finance net over the wealth and loss houses. Ships a hand-reproducible strength score with its arithmetic published in the field itself, and states plainly which part is classical and which part is our convention. Positions are computed in the Lahiri sidereal frame; the KP significators behind the finance area use the KP-Newcomb frame, as they do on every KP route. Vedic daily horoscope API, gochara API, daily panchang prediction, tarabala and chandrabala API, ashtakavarga transit strength.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1984-11-03","description":"Birth date in YYYY-MM-DD format. Fixes the Janma Rashi and Janma Nakshatra every part of this reading is counted from, and the natal Ashtakavarga the bindu gate reads."},"birthTime":{"type":"string","format":"time","example":"01:35:00","description":"Birth time in HH:MM:SS format (24-hour). The Moon moves about half a degree an hour, so an error here moves the Janma Rashi and Janma Nakshatra and therefore every gochara house count, the tarabala and the chandrabala in this response."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.8944,"description":"Birth location latitude in decimal degrees. Sets the natal house cusps behind the Ashtakavarga scorecard and the KP significators, and the sunrise that opens the panchanga day."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":76.5894,"description":"Birth location longitude in decimal degrees. Affects local sidereal time for the natal cusps and the sunrise the reading is composed at."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\") OR decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). IANA strings are resolved to the DST-correct offset for the date being read. Interprets the birth time and the civil date below. Defaults to 5.5.","example":5.5},"date":{"type":"string","format":"date","example":"2026-06-21","description":"Civil date to read, in YYYY-MM-DD format. Defaults to today (UTC). The panchanga day it names runs from sunrise at the birth coordinates to the next sunrise, not from midnight, so a reading for this date covers the night that follows it."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu. \"mean\" uses the smooth mean node, which is the traditional Vedic default and what printed panchangs use. \"true\" uses the osculating node, which swings up to 1.5 degrees either side of mean and can therefore move a node into a different rashi and change its gochara house. Defaults to \"mean\"."}},"required":["birthDate","birthTime","latitude","longitude"]}}}},"responses":{"200":{"description":"Daily reading composed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"frames":{"type":"object","properties":{"natal":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this part of the reading was cast in. Always \"lahiri\" here: it is not a caller choice, because the composition runs two frames at once and a single request field could only ever name one of them."},"ayanamsaDegrees":{"type":"number","example":23.64094017088563,"description":"Degrees actually subtracted from every tropical longitude this frame produced. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."},"at":{"type":"string","example":"1984-11-02T20:05:00.000Z","description":"ISO instant the ayanamsa was read at. Part of the value, not metadata: an ayanamsa moves about 50.3 arcseconds a year, so the same frame read at a birth in 1984 and at a transit in 2026 differs by more than half a degree."},"governs":{"type":"array","items":{"type":"string","enum":["subject","grahas","panchanga","tara","chandrabala","dasha","areas.finance"]},"example":["subject","grahas","tara","chandrabala","dasha","areas.finance"],"description":"Response sections this frame is a determinant of, as paths into this payload. One of subject, grahas, panchanga, tara, chandrabala, dasha, areas.finance. A section appears under EVERY frame that feeds it, which is why grahas is listed three times: the transiting longitudes and the natal Moon they are counted from are both Lahiri read at different instants, while the Ashtakavarga Lagna row behind binduCount and kaksha is KP-Newcomb. Exactly two sections belong to one frame alone, subject to the natal frame and panchanga to the transit frame."}},"required":["ayanamsa","ayanamsaDegrees","at","governs"],"description":"Lahiri at the birth instant. Produces the natal Moon this whole reading is counted from, the Vimshottari balance, and the natal graha rows of the Ashtakavarga scorecard the bindu gate reads."},"transit":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this part of the reading was cast in. Always \"lahiri\" here: it is not a caller choice, because the composition runs two frames at once and a single request field could only ever name one of them."},"ayanamsaDegrees":{"type":"number","example":24.22902171512637,"description":"Degrees actually subtracted from every tropical longitude this frame produced. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."},"at":{"type":"string","example":"2026-06-20T23:55:43.685Z","description":"ISO instant the ayanamsa was read at. Part of the value, not metadata: an ayanamsa moves about 50.3 arcseconds a year, so the same frame read at a birth in 1984 and at a transit in 2026 differs by more than half a degree."},"governs":{"type":"array","items":{"type":"string","enum":["subject","grahas","panchanga","tara","chandrabala","dasha","areas.finance"]},"example":["grahas","panchanga","tara","chandrabala"],"description":"Response sections this frame is a determinant of, as paths into this payload. One of subject, grahas, panchanga, tara, chandrabala, dasha, areas.finance. A section appears under EVERY frame that feeds it, which is why grahas is listed three times: the transiting longitudes and the natal Moon they are counted from are both Lahiri read at different instants, while the Ashtakavarga Lagna row behind binduCount and kaksha is KP-Newcomb. Exactly two sections belong to one frame alone, subject to the natal frame and panchanga to the transit frame."}},"required":["ayanamsa","ayanamsaDegrees","at","governs"],"description":"Lahiri at sunrise on the day being read. Produces every transiting longitude and every panchanga limb. Inside one day precession moves it 0.14 arcseconds, so this one value speaks for every limb resolved between the two sunrises."},"kp":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"kp-newcomb","description":"Sidereal frame this part of the reading was cast in. Always \"kp-newcomb\" here: it is not a caller choice, because the composition runs two frames at once and a single request field could only ever name one of them."},"ayanamsaDegrees":{"type":"number","example":23.5444031708357,"description":"Degrees actually subtracted from every tropical longitude this frame produced. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."},"at":{"type":"string","example":"1984-11-03T00:00:00.000Z","description":"ISO instant the ayanamsa was read at. Part of the value, not metadata: an ayanamsa moves about 50.3 arcseconds a year, so the same frame read at a birth in 1984 and at a transit in 2026 differs by more than half a degree."},"governs":{"type":"array","items":{"type":"string","enum":["subject","grahas","panchanga","tara","chandrabala","dasha","areas.finance"]},"example":["grahas","areas.finance"],"description":"Response sections this frame is a determinant of, as paths into this payload. One of subject, grahas, panchanga, tara, chandrabala, dasha, areas.finance. A section appears under EVERY frame that feeds it, which is why grahas is listed three times: the transiting longitudes and the natal Moon they are counted from are both Lahiri read at different instants, while the Ashtakavarga Lagna row behind binduCount and kaksha is KP-Newcomb. Exactly two sections belong to one frame alone, subject to the natal frame and panchanga to the transit frame."}},"required":["ayanamsa","ayanamsaDegrees","at","governs"],"description":"KP-Newcomb, read at UTC midnight of the birth date. Produces the Placidus cusps behind the Ashtakavarga Lagna row and the KP significators behind the finance area, exactly as every KP route on this API computes them."}},"required":["natal","transit","kp"],"description":"Every sidereal frame behind this reading, so a cached or forwarded payload is self describing and no number sits under a label it did not come from. TWO ayanamsas are in play by design: positions are Lahiri, and the Placidus cusps plus the KP significators are KP-Newcomb, which is the frame KP owns and the split a practitioner actually works in. The two differ by about 0.09 degrees, which is under a third of a KP sub-lord span and enough to move a placement near a boundary, so the reading declares which produced what rather than leaving a caller to guess. THREE entries for two ayanamsas, because Lahiri is read at two instants: the birth moment and the sunrise of the day being read, roughly half a degree apart on a chart forty years old, six times the gap between the two ayanamsas themselves. There is no ayanamsa request field on this route and there will not be one, since a single selector cannot honour two frames and accepting it would promise something the composition cannot deliver."},"date":{"type":"string","example":"2026-06-21","description":"Civil date this reading covers, echoing the request field or the UTC date it defaulted to."},"dayStart":{"type":"string","example":"2026-06-20T23:55:43.685Z","description":"ISO instant the panchanga day begins, which is SUNRISE at the birth coordinates and not midnight. Every limb below is resolved at this instant. Where the Sun does not rise, local noon is used instead and the substitution is named in degraded rather than applied silently."},"dayEnd":{"type":"string","example":"2026-06-21T23:55:56.962Z","description":"ISO instant the panchanga day ends, which is the next sunrise."},"subject":{"type":"object","properties":{"janmaRashi":{"type":"string","example":"Aquarius","description":"Natal Moon rashi, the reference point every gochara house count in this response is taken from. Always English."},"janmaNakshatra":{"type":"string","example":"Shatabhisha","description":"Natal Moon nakshatra, the reference point the tarabala is counted from. Canonical Sanskrit."},"janmaNakshatraNumber":{"type":"number","example":24,"description":"Janma Nakshatra number 1 to 27, counted from Ashwini."},"moonLongitude":{"type":"number","example":312.4808,"description":"Sidereal longitude of the natal Moon in degrees. The single value both reference points are derived from, so any disagreement with a reference chart can be traced to its source rather than to a verdict."}},"required":["janmaRashi","janmaNakshatra","janmaNakshatraNumber","moonLongitude"],"description":"The two natal reference points this whole reading is counted from, plus the longitude they come from."},"panchanga":{"type":"object","properties":{"vara":{"type":"string","example":"Sunday","description":"Weekday of the panchanga day. The Hindu vara runs sunrise to sunrise, so it can differ from the civil weekday of the same date before dawn. Always English."},"varaSanskrit":{"type":"string","example":"Ravivara","description":"The same weekday under its Sanskrit name."},"paksha":{"type":"string","example":"Shukla","description":"Lunar fortnight at sunrise: Shukla for the waxing half, Krishna for the waning half."},"tithi":{"type":"object","properties":{"number":{"type":"number","example":7,"description":"tithi number in its own cycle, resolved at sunrise."},"name":{"type":"string","example":"Saptamī","description":"Name of the tithi running at sunrise. Canonical Sanskrit, so it stays safe to compare against in code."},"validTo":{"type":"string","example":"2026-06-21T09:51:02.874Z","description":"ISO instant this tithi ends. Read from the same transition search POST /panchang/detailed publishes, never recomputed here, so the two endpoints cannot disagree about when the event happens."},"next":{"type":"string","example":"Aṣṭamī","description":"The tithi that follows, so the rest of the day can be labelled without a second request."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."}},"required":["number","name","validTo","next","timescale"],"description":"Tithi (lunar day) running at sunrise, with the instant it ends. The tithi is the 12-degree step of the Moon away from the Sun, so its length varies through the month."},"nakshatra":{"type":"object","properties":{"number":{"type":"number","example":11,"description":"nakshatra number in its own cycle, resolved at sunrise."},"name":{"type":"string","example":"Purva Phalguni","description":"Name of the nakshatra running at sunrise. Canonical Sanskrit, so it stays safe to compare against in code."},"validTo":{"type":"string","example":"2026-06-21T04:01:32.171Z","description":"ISO instant this nakshatra ends. Read from the same transition search POST /panchang/detailed publishes, never recomputed here, so the two endpoints cannot disagree about when the event happens."},"next":{"type":"string","example":"Uttara Phalguni","description":"The nakshatra that follows, so the rest of the day can be labelled without a second request."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."}},"required":["number","name","validTo","next","timescale"],"description":"Nakshatra the Moon occupies at sunrise, with the instant it ends. This is the sky-wide limb; for what it means to THIS native, read the tara array."},"yoga":{"type":"object","properties":{"number":{"type":"number","example":16,"description":"yoga number in its own cycle, resolved at sunrise."},"name":{"type":"string","example":"Siddhi","description":"Name of the yoga running at sunrise. Canonical Sanskrit, so it stays safe to compare against in code."},"validTo":{"type":"string","example":"2026-06-21T05:51:32.757Z","description":"ISO instant this yoga ends. Read from the same transition search POST /panchang/detailed publishes, never recomputed here, so the two endpoints cannot disagree about when the event happens."},"next":{"type":"string","example":"Vyatipaata","description":"The yoga that follows, so the rest of the day can be labelled without a second request."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."}},"required":["number","name","validTo","next","timescale"],"description":"Nitya yoga running at sunrise, with the instant it ends. The 27 yogas step through the combined longitude of the Sun and the Moon."},"karana":{"type":"object","properties":{"number":{"type":"number","example":6,"description":"karana number in its own cycle, resolved at sunrise."},"name":{"type":"string","example":"Vanij","description":"Name of the karana running at sunrise. Canonical Sanskrit, so it stays safe to compare against in code."},"validTo":{"type":"string","example":"2026-06-21T09:51:02.874Z","description":"ISO instant this karana ends. Read from the same transition search POST /panchang/detailed publishes, never recomputed here, so the two endpoints cannot disagree about when the event happens."},"next":{"type":"string","example":"Vishti","description":"The karana that follows, so the rest of the day can be labelled without a second request."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"hours","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."}},"required":["number","name","validTo","next","timescale"],"description":"Karana running at sunrise, with the instant it ends. A karana is half a tithi, which is why it is the fastest of the four limbs."}},"required":["vara","varaSanskrit","paksha","tithi","nakshatra","yoga","karana"],"description":"The four panchanga limbs, each resolved at sunrise and each carrying the instant it gives way, so a client can label the whole day rather than asserting one value for it."},"grahas":{"type":"array","items":{"type":"object","properties":{"graha":{"type":"string","example":"Moon","description":"Graha name, Sun through Ketu. Always English, whatever the lang parameter says, so it stays safe to compare against in code."},"sign":{"type":"string","example":"Leo","description":"Rashi this graha is transiting on the day being read. Always English."},"longitude":{"type":"number","example":144.4294,"description":"Sidereal longitude of the transiting graha in degrees, 0 to 360, Lahiri frame."},"houseFromMoon":{"type":"number","example":7,"description":"House this graha transits counted whole-sign and inclusively from the natal Moon rashi (Janma Rashi), so the Moon rashi itself is 1. This is the reference classical Gochara is reckoned in: Phaladeepika XXVI.1 opens the transit chapter by saying that of all the Lagnas only the Moon Lagna matters for transit results. A reading counted from the Lagna instead answers a different question and every verdict below would be wrong."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."},"favourable":{"type":"boolean","example":true,"description":"Gate 1. Whether houseFromMoon is on this graha classical favourable list (Phaladeepika XXVI.2). The baseline verdict, before vedha, bindus or the nullifiers have had their say."},"favourableHouses":{"type":"array","items":{"type":"number"},"example":[1,3,6,7,10,11],"description":"Gate 1 evidence: the whole favourable list for this graha, so the baseline verdict can be checked in place without a second request or a table lookup."},"vedhaHouse":{"type":["number","null"],"example":2,"description":"Gate 2. The house whose occupation by another graha cancels this transit (Phaladeepika XXVI.3-8). Null when the transit is not favourable to begin with, since there is nothing for an obstruction to cancel."},"obstructedBy":{"type":"array","items":{"type":"string"},"example":["Saturn"],"description":"Gate 2. Grahas actually standing in vedhaHouse, with the mutual exemptions already applied. Empty when nothing obstructs. A non-empty list makes the state \"obstructed\", which is a THIRD outcome rather than a smaller number: the texts cancel the promised good outright rather than discounting it."},"vedhaExempt":{"type":"array","items":{"type":"string"},"example":["Mercury"],"description":"Gate 2. Grahas that cannot obstruct this one however they transit, from the two mutual exemptions the texts name: the Sun and Saturn do not obstruct each other, and neither do the Moon and Mercury."},"binduCount":{"type":["number","null"],"example":6,"description":"Gate 3. Bindus this graha holds in the whole sign it is transiting, 0 to 8, or null for Rahu and Ketu, which have no Bhinnashtakavarga and therefore SKIP this gate entirely rather than scoring zero. The gate reads the number two ways: a favourable house carrying fewer than 4 bindus under delivers, and an unfavourable house carrying a strict majority of the eight contributors, 5 or more, is turned good by Phaladeepika XXVI.41. Exactly 4 fires neither rule, which is the literal reading of both phrasings rather than a rounding choice. WHOSE READING THE NUMBER IS, stated because generalising it is ours: B.V. Raman prints 4 once and prints it about the MOON, then generalises the PRINCIPLE to every graha in the next sentence without repeating any number, and Phaladeepika XXVI.41 is general across grahas and also states no number. Applying 4 to all nine bodies is RoxyAPI reading the general rule through the one worked example the author gave it, and it is not a universally stated classical threshold."},"kaksha":{"type":"object","properties":{"number":{"type":"number","example":3,"description":"Kaksha number 1-8 within the current sign. Each sign divides into eight kakshas of 3 degrees 45 minutes, crossed in order, so this is how far through the sign the graha has travelled."},"lord":{"type":"string","example":"Mars","description":"Graha ruling this kaksha. The eight lords run Saturn, Jupiter, Mars, Sun, Venus, Mercury, Moon, Lagna from the start of every sign, ordered by how long each takes to cross a sign."},"startDegree":{"type":"number","example":7.5,"description":"Degree within the sign where this kaksha begins (0, 3.75, 7.5 and so on)."},"endDegree":{"type":"number","example":11.25,"description":"Degree within the sign where this kaksha ends."},"bindu":{"type":["boolean","null"],"example":true,"description":"Whether this kaksha lord gave the transiting graha a bindu in the sign being transited, which is the Gochara Kaksha verdict: true reads as a favourable stretch of the transit, false as an unfavourable one. Null means the question does not apply rather than that the answer is no, because Rahu and Ketu have no Bhinnashtakavarga to read. Never render null as unfavourable."},"binduCount":{"type":["number","null"],"example":5,"description":"Bindus the transiting graha holds in this whole sign, 0-8, or null for Rahu and Ketu. Context for the verdict, since the same kaksha reads differently in a sign worth 7 than in one worth 1."}},"required":["number","lord","startDegree","endDegree","bindu","binduCount"],"description":"Gochara Kaksha: the ashtakavarga-qualified reading of this transit. The sign says where a graha is, this says whether the exact stretch it currently occupies is one its own Bhinnashtakavarga supports, which is the classical way of refining a transit verdict from sign-level to under four degrees."},"dignity":{"type":["string","null"],"enum":["exalted","own","debilitated","enemy","neutral",null],"example":"neutral","description":"Gate 4. Dignity of the graha in the sign it is transiting, or null for Rahu and Ketu which have none. Feeds the Phaladeepika XXVI.31 shield (\"exalted\" or \"own\" does no harm in an untoward bhava) and the XXVI.32 weakness (\"debilitated\" or \"enemy\" voids a good transit). One of exalted, own, debilitated, enemy, neutral."},"combust":{"type":["boolean","null"],"example":false,"description":"Gate 4. Whether the graha is combust at the transit moment, or null for the Sun and the two nodes where the question does not arise at all. Combustion voids a good transit under Phaladeepika XXVI.32 and aggravates a bad one."},"aspectedByBenefic":{"type":"array","items":{"type":"string"},"example":[],"description":"Gate 4. Transiting natural benefics casting graha drishti on this graha. Under Phaladeepika XXVI.30 a benefic sight on a BAD result is what voids it. Read as drishti from the other TRANSITING grahas, which is a school choice this endpoint makes and states: the sloka sits between the vedha rules and the rules about the transiting graha own condition."},"aspectedByMalefic":{"type":"array","items":{"type":"string"},"example":["Mars"],"description":"Gate 4. Transiting natural malefics casting graha drishti on this graha. A malefic sight on a GOOD result voids it under Phaladeepika XXVI.30. Rahu and Ketu never appear here: they cast no drishti in this package, which is its own documented school choice, although they can be aspected."},"aspectedByEnemy":{"type":"array","items":{"type":"string"},"example":[],"description":"Gate 4. Transiting natural enemies of this graha casting graha drishti on it. Phaladeepika XXVI.30 voids the result either way for an enemy sight, whichever direction the baseline verdict pointed."},"state":{"type":"string","enum":["favourable","underdelivered","obstructed","void","aggravated","unfavourable"],"example":"obstructed","description":"The single outcome the four gates produced for this graha, and the only field the score counts. \"favourable\" is the house list holding with nothing cancelling it, \"underdelivered\" is a favourable house below the bindu delivery floor, \"obstructed\" is vedha, \"void\" is an aspect, a dignity shield or a weakness emptying the result of effect, \"aggravated\" is the one compounding rule in the chapter, and \"unfavourable\" is a house that was never on the list. Canonical English machine values: every one is a classical outcome word rather than an invented label, which is why none carries a translated sibling."},"stateSource":{"type":"string","example":"Phaladeepika XXVI.3-8, the paired vedha house is occupied","description":"The rule that decided the state, named so a verdict can be checked against its sloka without leaving the payload."}},"required":["graha","sign","longitude","houseFromMoon","timescale","favourable","favourableHouses","vedhaHouse","obstructedBy","vedhaExempt","binduCount","kaksha","dignity","combust","aspectedByBenefic","aspectedByMalefic","aspectedByEnemy","state","stateSource"]},"description":"All nine transiting grahas, each with its four gate results and the ONE state they produced. The gates run in the order the sources give them: house from the natal Moon, then vedha, then the bindu gate, then the nullifiers of Phaladeepika XXVI.30 to XXVI.32. Obstruction is terminal, so a blocked transit is never rescued by the gates that follow it."},"tara":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string","example":"2026-06-20T23:55:43.685Z","description":"ISO instant this tarabala window opens."},"validTo":{"type":"string","example":"2026-06-21T04:01:32.171Z","description":"ISO instant this tarabala window closes, which is when the Moon changes nakshatra."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."},"moonNakshatra":{"type":"string","example":"Purva Phalguni","description":"Nakshatra the Moon occupies during this window. Canonical Sanskrit."},"number":{"type":"number","example":6,"description":"Tara number 1 to 9, counted inclusively from the Janma Nakshatra to the Moon nakshatra and folded by 9."},"name":{"type":"string","enum":["Janma","Sampat","Vipat","Kshema","Pratyari","Sadhaka","Vadha","Mitra","Parama Mitra"],"example":"Sadhaka","description":"Name of the tara this native gets during this window, from the 9-tara cycle Janma through Parama Mitra. A Sanskrit proper noun and a canonical machine value, which is why the favourability is a separate field rather than something a caller has to infer from the word."},"quality":{"type":"string","enum":["favourable","unfavourable","neutral"],"example":"favourable","description":"Where this tara falls in the three-way classical reading. Taras 2, 4, 6, 8 and 9 are favourable, 3, 5 and 7 are not, and the 1st (Janma) is neither."}},"required":["validFrom","validTo","timescale","moonNakshatra","number","name","quality"]},"description":"Tarabala for THIS native, as an array of windows rather than one value, because the Moon can change nakshatra inside a panchanga day and the reference panchangs print two windows when it does. Three windows happen and are returned when they do. One entry means the tara held all day."},"chandrabala":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string","example":"2026-06-20T23:55:43.685Z","description":"ISO instant this chandrabala window opens."},"validTo":{"type":"string","example":"2026-06-21T10:10:08.968Z","description":"ISO instant this chandrabala window closes, which is when the Moon changes rashi."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"days","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."},"moonSign":{"type":"string","example":"Leo","description":"Rashi the Moon occupies during this window. Always English."},"houseFromMoon":{"type":"number","example":7,"description":"House the Moon rashi makes from the Janma Rashi, counted whole-sign and inclusively, so the Janma Rashi itself is 1. This is the number chandrabala is read off."},"favourable":{"type":"boolean","example":true,"description":"Whether the Moon stands in one of the rashis that give this native chandrabala during this window."},"ashtamaChandra":{"type":"boolean","example":false,"description":"The Moon in the 8th from the Janma Rashi. Its OWN flag, printed beside chandrabala rather than folded into it, exactly as the reference panchangs print it. Folding it in would let a caller read one boolean and miss the warning the source deliberately separates."}},"required":["validFrom","validTo","timescale","moonSign","houseFromMoon","favourable","ashtamaChandra"]},"description":"Chandrabala for THIS native, windowed for the same reason as the tarabala: the Moon can change rashi inside the panchanga day. Ashtama Chandra is a separate flag on each window."},"dasha":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["mahadasha","antardasha","pratyantardasha"],"example":"antardasha","description":"Which Vimshottari level this period is. Only mahadasha, antardasha, pratyantardasha are carried: the sookshma and prana lords turn over in hours and minutes, so embedding them would advertise a day-long cache lifetime over a value that is already stale. Use POST /dasha/current for those two."},"lord":{"type":"string","example":"Rahu","description":"Graha ruling this period. Always English."},"startDate":{"type":"string","example":"2024-08-10T12:05:00.000Z","description":"ISO instant this period begins."},"endDate":{"type":"string","example":"2027-06-17T12:05:00.000Z","description":"ISO instant this period ends."},"timescale":{"type":"string","enum":["hours","days","months","years"],"example":"years","description":"How long this component holds one verdict. Present on every component because this reading joins two genres classical literature keeps in separate books: a gochara verdict lasts as long as the graha stays in a rashi, which is years for Saturn, while a tarabala changes overnight. Without it a Saturn verdict that reads identically for nine hundred days would sit under one date field beside a limb that turns over at dawn."}},"required":["level","lord","startDate","endDate","timescale"]},"description":"The running Vimshottari chain at sunrise, outermost first, three levels deep. This is the frame the day is read inside, and it is also what the finance area reads the significators off. Empty for a chart whose cycle cannot be resolved."},"areas":{"type":"object","properties":{"finance":{"type":"object","properties":{"score":{"type":["number","null"],"example":67,"description":"Share of the running lords six-house connections that land on the positive group, 0 to 100, rounded. A COUNT, so positive and negative below reproduce it in one division: round(positive / (positive + negative) * 100). Zero when the running lords reach none of the six houses, which is an ABSENCE of connection rather than a negative verdict. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score. The two house groups are Krishnamurti Paddhati practice, but the NET is a KP practitioner convention rather than a classical operation: the KP sources that carry these groups use them as a promise test and an avoidance test, never as arithmetic. The groups also vary by author, and the 6th house is the live disagreement, since some KP authors place it on the POSITIVE side as service income and salary, the exact opposite of the assignment used here. This is a six house net and it is NOT the focus=finance lens, which re-reads all twelve bhavas in money vocabulary and moves no number. The two are orthogonal and both ship."},"band":{"type":["string","null"],"enum":["very-strong","strong","moderate","weak",null],"example":"strong","description":"The band the finance score falls in, on the same ladder as the top-level verdict so the two can never disagree about what a word means: \"very-strong\" at 75 and above, \"strong\" at 50 and above, \"moderate\" at 25 and above, \"weak\" below 25. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score."},"positive":{"type":["number","null"],"example":6,"description":"How many connections land on the positive house group 2, 5, 11, which KP reads as accumulated wealth, speculation and gains. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score."},"negative":{"type":["number","null"],"example":3,"description":"How many connections land on the negative house group 6, 8, 12, which KP reads as debt, sudden loss and expenditure. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score."},"drivers":{"type":["array","null"],"items":{"type":"object","properties":{"graha":{"type":"string","example":"Rahu","description":"The running dasha lord making this connection. A lord holding two of the three levels is listed once per house rather than twice, so nothing here is a hidden weight."},"house":{"type":"number","example":2,"description":"The finance house this lord reaches. One of the positive group 2, 5, 11 or the negative group 6, 8, 12."},"level":{"type":"integer","minimum":1,"maximum":4,"example":3,"description":"Strongest KP significator level at which this lord reaches this house, 1 to 4. Level 1 is a planet in the constellation of the occupant, 2 the occupant, 3 a planet in the constellation of the house owner, 4 the house owner. Strongest level per house wins, which is step 1 of the published grading rule the dasha routes already use."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"C","description":"The KP letter for that level, on the standard A to D significator grading. A is the strongest connection."},"dashaLevels":{"type":"array","items":{"type":"string","enum":["mahadasha","antardasha","pratyantardasha"]},"example":["antardasha"],"description":"Which of the running levels this graha rules. Carries the fact that one lord holds more than one level without letting it count twice."}},"required":["graha","house","level","grade","dashaLevels"]},"description":"Every positive-group connection, strongest KP level first. These are the specific lord-to-house links the score is made of, so the number can be audited rather than trusted. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score."},"cautions":{"type":["array","null"],"items":{"type":"object","properties":{"graha":{"type":"string","example":"Rahu","description":"The running dasha lord making this connection. A lord holding two of the three levels is listed once per house rather than twice, so nothing here is a hidden weight."},"house":{"type":"number","example":2,"description":"The finance house this lord reaches. One of the positive group 2, 5, 11 or the negative group 6, 8, 12."},"level":{"type":"integer","minimum":1,"maximum":4,"example":3,"description":"Strongest KP significator level at which this lord reaches this house, 1 to 4. Level 1 is a planet in the constellation of the occupant, 2 the occupant, 3 a planet in the constellation of the house owner, 4 the house owner. Strongest level per house wins, which is step 1 of the published grading rule the dasha routes already use."},"grade":{"type":"string","enum":["A","B","C","D"],"example":"C","description":"The KP letter for that level, on the standard A to D significator grading. A is the strongest connection."},"dashaLevels":{"type":"array","items":{"type":"string","enum":["mahadasha","antardasha","pratyantardasha"]},"example":["antardasha"],"description":"Which of the running levels this graha rules. Carries the fact that one lord holds more than one level without letting it count twice."}},"required":["graha","house","level","grade","dashaLevels"]},"description":"Every negative-group connection, strongest KP level first. Null above latitude 66.56, where the Placidus cusps the KP significators are read from have no solution: the question does not apply there rather than the answer being no, so never render it as zero or as a weak verdict. The natal block beside it is unaffected and still ships, and degraded names areas.finance.score."},"natal":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"daridra","description":"Glossary id of the verdict, one of dhana, daridra, lakshmi, dhanamalika. Use it with GET /yoga/{id} for the full glossary entry, which carries the description and the classical result in every supported language. Canonical English, so it stays safe to switch on in code."},"name":{"type":"string","example":"Daridra Yoga","description":"Classical Sanskrit name of the combination. Canonical whatever the lang parameter says, exactly as the yoga endpoints return it."},"quality":{"type":"string","enum":["Positive","Negative","Both"],"example":"Negative","description":"Which way a present verdict points, carried because three of the four are wealth combinations and Daridra is a poverty one, so present alone does not tell a client whether to read it as support or as pressure. Canonical English machine value."},"present":{"type":"boolean","example":true,"description":"Whether the combination is on this chart. False means every rule in the family was evaluated and none held, which is a real answer rather than a missing one, and the evidence beside it names the full denominator."},"evidence":{"type":"string","example":"Daridra Yoga holds on 1 of the 8 rules evaluated. daridra-7 (BPHS 42.6): the Lagna lord Sun is joined by Saturn (the 6th lord) and receives drishti from no natural benefic. Nine of the eleven catalogued Daridra rows are evaluated, as eight rules: daridra-4 and daridra-5 are the two halves of BPHS 42.4. daridra-8 and daridra-9 are excluded because B.V. Raman is their only authority, and an unverified rule may not decide a verdict.","description":"Why the verdict reads the way it does: every rule that matched, named by its own glossary id and its verse, with the exact condition it matched on, then the scope of the family. This is what makes the verdict checkable against a text rather than a label to be trusted, and it is also where the two excluded rules are declared: daridra-8 and daridra-9 rest on a single authority and are barred from deciding a verdict, though both still ship through GET /yoga/{id}. English in every language, like the per-graha stateSource, because it is provenance rather than display copy."}},"required":["id","name","quality","present","evidence"]},"description":"The natal basis of this area: whether the chart is wealthy AT ALL, as the four classical wealth and poverty verdicts dhana, daridra, lakshmi, dhanamalika, each with the evidence that decided it. A PROPERTY OF THE BIRTH CHART AND NOT OF THE DAY, so it is the same block on every date this native is ever read for, which is exactly why it is CONTEXT rather than a term: it deliberately does not enter score, verdict, tally or evaluated, above or here. Folding a constant into a per-day number would shift every day by the identical amount, carrying no information into the only comparison those numbers support, and it would break the published closed form that makes the top-level score reproducible by hand from grahas alone. Read it as the standing question the day is being read against. The verdicts are the same ones POST /yoga/detect and POST /birth-chart return for this chart, computed in the Lahiri natal frame rather than in the KP-Newcomb frame the significators above use. PRESENT AT EVERY LATITUDE, including above the polar circle: these verdicts need only whole-sign houses from the Lagna, so nothing about them depends on the cusps the KP members above lose there."}},"required":["score","band","positive","negative","drivers","cautions","natal"],"description":"The finance area: the positive house group 2, 5, 11 netted against the negative group 6, 8, 12, read off the lords of the running dasha, bhukti and antara, because that is the KP rule for when a matter fructifies, plus the natal basis the day is read against. ALWAYS AN OBJECT. Above latitude 66.56 the six netted members are null, because the Placidus cusps behind the significators have no solution there, while natal is still populated because it is a property of the birth chart and needs no cusps; the reading also still carries its gochara, panchanga and dasha and names the omission in degraded. The two house groups are Krishnamurti Paddhati practice, but the NET is a KP practitioner convention rather than a classical operation: the KP sources that carry these groups use them as a promise test and an avoidance test, never as arithmetic. The groups also vary by author, and the 6th house is the live disagreement, since some KP authors place it on the POSITIVE side as service income and salary, the exact opposite of the assignment used here. This is a six house net and it is NOT the focus=finance lens, which re-reads all twelve bhavas in money vocabulary and moves no number. The two are orthogonal and both ship."}},"required":["finance"],"description":"Life areas carried as a TYPED closed set rather than an open map, so every generated SDK knows which keys exist. Finance ships alone in this version, because an area is a named classical house group with a citation and not a life category invented for a dropdown. Widening it later adds a key and breaks nothing."},"score":{"type":"number","example":22,"description":"How much of the transiting sky supports this native today: supportive grahas divided by grahas evaluated, as a percentage, rounded. HAND REPRODUCIBLE FROM THIS RESPONSE ALONE, with no weights to publish and none to defend. STEP 1, count the grahas whose state is one of favourable; the tally array has that count already. STEP 2, divide by evaluated and round. Worked example: 2 supportive out of 9 evaluated scores round(2 / 9 * 100) = 22. The other states (underdelivered, obstructed, void, aggravated, unfavourable) count for nothing, because each of them is the tradition saying the promised good was reduced, cancelled or emptied. WHY IT IS A COUNT AND NOT A SUM: the tradition does not add these limbs up. Phaladeepika XXVI.41 makes a high bindu count an OVERRIDE that turns even the 6th, 8th and 12th good, and XXVI.30 to XXVI.32 make aspect, dignity and combustion NULLIFIERS, so a weighted sum would be a different mathematical object and could not carry those citations. The GATES are classical, the COUNTING is the RoxyAPI convention, and this sentence is where we say which is which. HOW TO READ THE NUMBER: it runs low by construction and that is the correct answer rather than a defect. Nine bodies casting drishti means almost every transiting graha is aspected by something, and the sloka voids the result when it is, so most days land in the bottom half and a high score is rare and therefore meaningful. Read it as a rare-high scale, not as a mark out of 100: 22 is an ordinary day, not a failing one. And it measures SUPPORT, never OUTCOME. It says how much of the sky backs this native today, never whether the day is good for a particular matter, which depends on the matter being judged."},"verdict":{"type":"string","enum":["very-strong","strong","moderate","weak"],"example":"weak","description":"The band the score falls in: \"very-strong\" at 75 and above, \"strong\" at 50 and above, \"moderate\" at 25 and above, \"weak\" below 25. The four WORDS are the shipped KP significator band words, reused so nothing new has to be translated. The EDGES are the RoxyAPI convention and are quartiles, because no authority bands a day and quartiles are the least arbitrary division of a percentage into four named steps. Read it with the same expectation the score carries: the gates cancel far more often than they deliver, so the lower bands are the common case."},"tally":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string","enum":["favourable","underdelivered","obstructed","void","aggravated","unfavourable"],"example":"void","description":"One of the six outcomes a transiting graha can reach."},"count":{"type":"number","example":2,"description":"How many of the evaluated grahas reached that state."}},"required":["state","count"]},"description":"The full per-state count, always all six states including the zeros. This is the WHOLE input to the score, which is what makes the number reproducible by hand, and it is also what lets a caller who reads the states differently compute their own figure from this response instead of asking for a second one."},"evaluated":{"type":"number","example":9,"description":"How many grahas were put through the gates, which is the denominator of the score. Rahu and Ketu are included: they skip the bindu gate because they have no Bhinnashtakavarga, and a skipped gate is not a failed one, so they still reach a state through the other three."},"degraded":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string","enum":["dayStart","dayEnd","areas.finance.score"],"example":"areas.finance.score","description":"Which part of the reading this location or date could not supply. \"areas.finance.score\" names the KP net by the member it is read through: the finance area itself always ships and its natal block is always populated, and it is the six netted members that are null."},"reason":{"type":"string","enum":["sun-does-not-rise","polar-latitude"],"example":"polar-latitude","description":"Why it could not: \"sun-does-not-rise\" for a day with no sunrise at these coordinates, \"polar-latitude\" above 66.56 degrees where the Placidus cusps have no solution."}},"required":["component","reason"]},"description":"Components this request could not supply, named rather than silently defaulted. Empty on an ordinary reading. A polar chart degrades through here instead of failing, so the caller still gets the gochara, the panchanga, the dasha and the natal basis of the finance area, and is told exactly what is missing."},"houseThemes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"example":["wealth","family","speech","possessions","food"],"description":"Short keyword significations of the bhava this key numbers, localized by the lang query parameter and drawn from the vocabulary the focus parameter selected. Join it against any house number elsewhere in the response to render readable text."},"example":{"2":["wealth","family","speech","possessions","food"]},"description":"Significations of each of the twelve bhavas (houses), keyed by house number 1 to 12, as short keywords. Bhava 1 is the Lagna (self, body, vitality), 2 wealth and speech, 4 home and mother, 7 marriage and partnership, 10 career and status, 11 gains. Use it to label the house numbers returned elsewhere in the response: a Vimshottari dasha period signifying houses 2, 7 and 8, or a KP significator carrying houses 11 and 6, becomes readable text without a separate lookup call. Returned once per response rather than repeated per period, and localized by the lang query parameter alongside every other interpretation field."},"focus":{"type":"string","enum":["general","finance"],"example":"general","description":"Which signification vocabulary produced the houseThemes keywords in this response, echoing the focus query parameter. Always present, and \"general\" when the parameter was omitted. Read it to label a rendered house legend, or to tell two cached responses apart when only one asked for the finance lens."}},"required":["frames","date","dayStart","dayEnd","subject","panchanga","grahas","tara","chandrabala","dasha","areas","score","verdict","tally","evaluated","degraded","houseThemes","focus"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/panchang/basic":{"post":{"operationId":"getBasicPanchang","tags":["Vedic Astrology"],"summary":"Get basic Panchang - Tithi Nakshatra Yoga Karana Calculator","description":"Calculate Panchang elements (Hindu calendar) for any date: Tithi (lunar day), Nakshatra (lunar mansion), Yoga, and Karana. Daily panchang API for determining auspicious timings (muhurta), festival dates, and planetary influences. Tithi calculator with Shukla/Krishna paksha. Accurate nakshatra today with ruling planet. Essential for Hindu calendar integration, muhurta selection, and Vedic timekeeping in astrology apps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-12-17","description":"Date in YYYY-MM-DD format. Panchang elements (Tithi, Nakshatra, Yoga, Karana) are calculated for this date."},"time":{"type":"string","format":"time","example":"12:00:00","description":"Time in HH:MM:SS format (24-hour). Determines the exact Moon and Sun positions for tithi and nakshatra calculation."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Observer latitude in decimal degrees. Determines sunrise/sunset times which define the Vara (weekday) and muhurta boundaries."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Observer longitude in decimal degrees. Affects local time calculations for sunrise/sunset-dependent panchang elements."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours. Defaults to 5.5 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Basic panchang with all five limbs (Tithi, Nakshatra, Yoga, Karana, Vara) including lunar phase, paksha, ruling planets, deities, and interpretive characteristics.","content":{"application/json":{"schema":{"type":"object","properties":{"tithi":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":30,"example":5,"description":"Tithi number (1-30). 1-15 are Shukla Paksha (waxing), 16-30 are Krishna Paksha (waning). Purnima is 15, Amavasya is 30."},"name":{"type":"string","example":"Panchami","description":"Sanskrit name of the tithi (lunar day). One of 30 tithis in the lunar month cycle."},"paksha":{"type":"string","enum":["Shukla","Krishna"],"example":"Shukla","description":"Lunar fortnight: Shukla (waxing, bright half) or Krishna (waning, dark half)."},"percent":{"type":"number","minimum":0,"maximum":100,"example":67.5,"description":"Percentage of the current tithi elapsed (0-100). Useful for determining tithi strength and transition proximity."},"deity":{"type":"string","example":"Vishnu","description":"Presiding deity of this tithi from Vedic tradition."},"rulingPlanet":{"type":"string","example":"Sun","description":"Planetary ruler of this tithi. Influences the day energy and activities."},"element":{"type":"string","example":"Fire","description":"Elemental quality of this tithi (Fire, Earth, Air, Water, Ether)."}},"required":["number","name","paksha","percent"],"description":"Lunar day (tithi) information with interpretations. Central panchang element for determining auspicious timings."},"nakshatra":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":27,"example":1,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini. Each nakshatra spans 13 degrees 20 minutes."},"name":{"type":"string","example":"Ashwini","description":"Sanskrit name of the nakshatra (lunar mansion). One of 27 nakshatras spanning the zodiac belt."},"lord":{"type":"string","example":"Ketu","description":"Planetary ruler of this nakshatra. Determines Vimshottari dasha lord and influences nakshatra characteristics."},"pada":{"type":"integer","minimum":1,"maximum":4,"example":2,"description":"Pada (quarter, 1-4) of the nakshatra. Each nakshatra has 4 padas spanning 3 degrees 20 minutes each. Determines the navamsha sign and fine-tunes nakshatra predictions."},"deity":{"type":"string","example":"Ashwini Kumaras","description":"Presiding deity of this nakshatra from Vedic mythology. Influences spiritual qualities and karmic themes."},"symbol":{"type":"string","example":"Horse Head","description":"Traditional symbol representing this nakshatra. Reflects core energy and life themes."},"characteristics":{"type":"string","example":"Quick, healing energy","description":"Personality traits and behavioral tendencies when the Moon occupies this nakshatra. Useful for daily panchang readings."}},"required":["number","name","lord","pada"],"description":"Nakshatra (lunar mansion) information with interpretations"},"yoga":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":27,"example":1,"description":"Nitya Yoga index (1-27). Calculated from the sum of Sun and Moon sidereal longitudes divided by 13 degrees 20 minutes."},"name":{"type":"string","example":"Vishkumbha","description":"Sanskrit name of the Nitya Yoga. One of 27 yogas formed by combined Sun-Moon motion, each with distinct auspiciousness."},"characteristics":{"type":"string","example":"Auspicious for new beginnings","description":"Characteristics and auspiciousness of this yoga for activity planning."}},"required":["number","name"],"description":"Nitya Yoga information. Yoga is the third panchang element, derived from combined Sun-Moon longitude."},"karana":{"type":"object","properties":{"number":{"type":"integer","example":7,"description":"Karana index. There are 11 karanas total (4 fixed + 7 movable) cycling through 60 half-tithis per lunar month."},"name":{"type":"string","example":"Bava","description":"Sanskrit name of the karana. 7 movable karanas (Bava through Naga) repeat 8 times, plus 4 fixed karanas."},"type":{"type":"string","example":"Movable","description":"Karana type: Movable (repeating, generally auspicious) or Fixed (occur once per month)."},"characteristics":{"type":"string","example":"Good for travel and movement","description":"Activity suitability and characteristics of this karana for muhurta selection."}},"required":["number","name"],"description":"Karana (half-tithi) information. Fourth panchang element, changes twice per tithi."},"sunLongitude":{"type":"number","example":265.42,"description":"Sidereal longitude of the Sun in degrees (0-360). Used for tithi and yoga calculations."},"moonLongitude":{"type":"number","example":315.67,"description":"Sidereal longitude of the Moon in degrees (0-360). Moon moves ~13 degrees per day through the nakshatras."}},"required":["tithi","nakshatra","yoga","karana","sunLongitude","moonLongitude"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/panchang/detailed":{"post":{"operationId":"getDetailedPanchang","tags":["Vedic Astrology"],"summary":"Get detailed Panchang with Rahu Kaal, Yamaganda, Gulika","description":"Complete daily panchang with all five limbs (Tithi, Nakshatra, Yoga, Karana, Vara) plus sunrise, sunset, moonrise, moonset times. Includes inauspicious periods (Rahu Kaal, Yamaganda, Gulika Kaal) and auspicious windows (Abhijit Muhurta, Brahma Muhurta). Current planetary hora with start/end times. Essential for muhurta selection, daily horoscope apps, Hindu calendar integration, and electional astrology. Accurate calculations based on observer location.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-03","description":"Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Observer latitude in decimal degrees. Determines sunrise and sunset times which define day/night boundaries for muhurta calculations."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Observer longitude in decimal degrees. Affects local time calculations for sunrise, sunset, and muhurta period boundaries."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours, for example -5 for New York or 9 for Tokyo. Send the offset that matches the coordinates: sunrise, sunset and every muhurta boundary are found by searching forward from local midnight, so the default anchors the search to an Indian day. Omitting it for a location outside IST returns a correctly ordered set of periods for the wrong window, shifted by the difference between 5.5 and the real offset. Defaults to 5.5 (IST).","example":5.5}},"required":["date","latitude","longitude"]}}}},"responses":{"200":{"description":"Full daily panchang with five limbs, sunrise/sunset/moonrise/moonset times, inauspicious periods (Rahu Kaal, Yamaganda, Gulika Kaal), auspicious muhurtas (Abhijit, Brahma), current hora, panchang transitions, and panchaka/bhadra/varjyam/amrit kalam analysis.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-02-03","description":"Date for which panchang is calculated."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":28.6139,"description":"Observer latitude used for sunrise/sunset calculation."},"longitude":{"type":"number","example":77.209,"description":"Observer longitude used for sunrise/sunset calculation."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in hours."}},"required":["latitude","longitude","timezone"],"description":"Location coordinates used for all time-based calculations."},"vara":{"type":"object","properties":{"name":{"type":"string","example":"Tuesday","description":"Weekday name in English. Vara begins at local sunrise, not at midnight, so a time before sunrise belongs to the previous vara."},"sanskritName":{"type":"string","example":"Mangalavara","description":"Vara name transliterated from Sanskrit: Ravivara, Somavara, Mangalavara, Budhavara, Guruvara, Shukravara, Shanivara. Use this rather than name for a Jyotish-facing reading, since it is the form the classical texts use and it does not change with the lang parameter."},"lord":{"type":"string","example":"Mars","description":"Ruling planet of the day (Vara lord). Influences day-level auspiciousness."}},"required":["name","sanskritName","lord"],"description":"Vara (weekday) information based on Hindu sunrise calendar."},"sunrise":{"type":"string","example":"2026-02-03T07:12:00","description":"Local sunrise in the requested timezone as YYYY-MM-DDTHH:MM:SS, with no zone suffix. Marks the start of the Hindu day."},"sunset":{"type":"string","example":"2026-02-03T18:32:00","description":"Local sunset in the requested timezone as YYYY-MM-DDTHH:MM:SS, with no zone suffix. Marks the transition to night muhurtas."},"moonrise":{"type":["string","null"],"example":"2026-02-03T20:03:00","description":"Moonrise time in the requested timezone. Can be null if Moon does not rise on this date."},"moonset":{"type":["string","null"],"example":"2026-02-03T08:10:00","description":"Moonset time in the requested timezone. Can be null if Moon does not set on this date."},"moonSign":{"type":"object","properties":{"name":{"type":"string","example":"Capricorn","description":"Moon rashi (sidereal zodiac sign) at sunrise."},"sanskritName":{"type":"string","example":"Makara","description":"Sanskrit name of the Moon rashi."}},"required":["name","sanskritName"],"description":"Moon sign (Chandra Rashi) at sunrise. Central to Vedic astrology. determines daily emotional tone, Chandrabalam, and Tarabalam."},"sunSign":{"type":"object","properties":{"name":{"type":"string","example":"Aquarius","description":"Sun rashi (sidereal zodiac sign) at sunrise."},"sanskritName":{"type":"string","example":"Kumbha","description":"Sanskrit name of the Sun rashi."}},"required":["name","sanskritName"],"description":"Sun sign (Surya Rashi) at sunrise. Determines the solar month (Saura Masa) in the Hindu calendar. Changes approximately once a month (Sankranti)."},"sunNakshatra":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":27,"example":21,"description":"Sun nakshatra number (1-27)."},"name":{"type":"string","example":"Dhanishtha","description":"Name of the nakshatra the Sun occupies."},"lord":{"type":"string","example":"Mars","description":"Ruling planet (lord) of the Sun nakshatra."},"pada":{"type":"integer","minimum":1,"maximum":4,"example":3,"description":"Pada (quarter) of the Sun nakshatra."}},"required":["number","name","lord","pada"],"description":"Sun nakshatra at sunrise. The Sun spends approximately 13-14 days in each nakshatra. Used for Surya-based muhurta and festival calculations."},"tithi":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":30,"example":5,"description":"Tithi number (1-30). 1-15 are Shukla Paksha (waxing), 16-30 are Krishna Paksha (waning). Purnima is 15, Amavasya is 30."},"name":{"type":"string","example":"Panchami","description":"Sanskrit name of the tithi (lunar day). One of 30 tithis in the lunar month cycle."},"paksha":{"type":"string","enum":["Shukla","Krishna"],"example":"Shukla","description":"Lunar fortnight: Shukla (waxing, bright half) or Krishna (waning, dark half)."},"percent":{"type":"number","minimum":0,"maximum":100,"example":67.5,"description":"Percentage of the current tithi elapsed (0-100). Useful for determining tithi strength and transition proximity."},"deity":{"type":"string","example":"Vishnu","description":"Presiding deity of this tithi from Vedic tradition."},"rulingPlanet":{"type":"string","example":"Sun","description":"Planetary ruler of this tithi. Influences the day energy and activities."},"element":{"type":"string","example":"Fire","description":"Elemental quality of this tithi (Fire, Earth, Air, Water, Ether)."}},"required":["number","name","paksha","percent"],"description":"Lunar day (tithi) information with interpretations. Central panchang element for determining auspicious timings."},"nakshatra":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":27,"example":1,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini. Each nakshatra spans 13 degrees 20 minutes."},"name":{"type":"string","example":"Ashwini","description":"Sanskrit name of the nakshatra (lunar mansion). One of 27 nakshatras spanning the zodiac belt."},"lord":{"type":"string","example":"Ketu","description":"Planetary ruler of this nakshatra. Determines Vimshottari dasha lord and influences nakshatra characteristics."},"pada":{"type":"integer","minimum":1,"maximum":4,"example":2,"description":"Pada (quarter, 1-4) of the nakshatra. Each nakshatra has 4 padas spanning 3 degrees 20 minutes each. Determines the navamsha sign and fine-tunes nakshatra predictions."},"deity":{"type":"string","example":"Ashwini Kumaras","description":"Presiding deity of this nakshatra from Vedic mythology. Influences spiritual qualities and karmic themes."},"symbol":{"type":"string","example":"Horse Head","description":"Traditional symbol representing this nakshatra. Reflects core energy and life themes."},"characteristics":{"type":"string","example":"Quick, healing energy","description":"Personality traits and behavioral tendencies when the Moon occupies this nakshatra. Useful for daily panchang readings."}},"required":["number","name","lord","pada"],"description":"Nakshatra (lunar mansion) information with interpretations"},"yoga":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":27,"example":1,"description":"Nitya Yoga index (1-27). Calculated from the sum of Sun and Moon sidereal longitudes divided by 13 degrees 20 minutes."},"name":{"type":"string","example":"Vishkumbha","description":"Sanskrit name of the Nitya Yoga. One of 27 yogas formed by combined Sun-Moon motion, each with distinct auspiciousness."},"characteristics":{"type":"string","example":"Auspicious for new beginnings","description":"Characteristics and auspiciousness of this yoga for activity planning."}},"required":["number","name"],"description":"Nitya Yoga information. Yoga is the third panchang element, derived from combined Sun-Moon longitude."},"karana":{"type":"object","properties":{"number":{"type":"integer","example":7,"description":"Karana index. There are 11 karanas total (4 fixed + 7 movable) cycling through 60 half-tithis per lunar month."},"name":{"type":"string","example":"Bava","description":"Sanskrit name of the karana. 7 movable karanas (Bava through Naga) repeat 8 times, plus 4 fixed karanas."},"type":{"type":"string","example":"Movable","description":"Karana type: Movable (repeating, generally auspicious) or Fixed (occur once per month)."},"characteristics":{"type":"string","example":"Good for travel and movement","description":"Activity suitability and characteristics of this karana for muhurta selection."}},"required":["number","name"],"description":"Karana (half-tithi) information. Fourth panchang element, changes twice per tithi."},"hora":{"type":"object","properties":{"current":{"type":"string","example":"Mars","description":"Planet ruling the current hora (planetary hour). Each hora lasts ~1 hour."},"number":{"type":"number","example":5,"description":"Hora number within the day sequence (1-24)."},"start":{"type":"string","example":"2026-02-03T07:08:00","description":"Start time of the current hora, as local civil time in the requested timezone offset. The first hora of any day begins at local sunrise, so this equals the sunrise field when the hora number is 1."},"end":{"type":"string","example":"2026-02-03T08:02:00","description":"End time of the current hora, as local civil time in the requested timezone offset. Day horas and night horas have different lengths, so a hora is only approximately 60 minutes."}},"required":["current","number","start","end"],"description":"Current planetary hora. Used for electional astrology and muhurta selection."},"rahuKaal":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Rahu Kaal, inauspicious period ruled by Rahu. Avoid starting new ventures. Calculated from sunrise duration divided into 8 parts."},"yamaganda":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Yamaganda, inauspicious period ruled by Yama (lord of death). Avoid important activities."},"gulika":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Gulika Kaal, inauspicious period ruled by Saturn son Gulika. Considered harmful for initiating work."},"abhijitMuhurta":{"type":["object","null"],"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Abhijit Muhurta (Abhijit Muhurat), the most auspicious ~48-minute window around solar noon, the 8th of 15 day muhurtas. Ideal for starting new ventures, signing contracts, and performing rituals when no other shubh muhurat is available. Null on Wednesdays because Abhijit coincides with Dur Muhurta on that weekday per Muhurta Chintamani."},"brahmaMuhurta":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Brahma Muhurta, sacred pre-dawn period approximately 96 minutes before sunrise (14th of 15 night muhurtas). Considered the best time for meditation, mantra japa, Vedic study, and spiritual sadhana. Referenced in Ashtanga Hridaya and Dharmashastra texts."},"vijayaMuhurta":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Vijaya Muhurta (Vijay Muhurat), the 11th of 15 day muhurtas between sunrise and sunset. Auspicious for journeys, legal proceedings, competitions, warfare, and any activity requiring victory or success. Used in electional astrology (muhurta shastra) for timing important undertakings."},"nishitaMuhurta":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Nishita Muhurta (Nishith Kaal), the 8th of 15 night muhurtas from sunset to next sunrise, occurring around midnight. Sacred period for worship of Lord Shiva, especially on Maha Shivaratri. Also significant for Janmashtami midnight celebrations and tantric sadhana."},"godhuliMuhurta":{"type":["object","null"],"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Godhuli Muhurta (cow dust time), 12 minutes before sunset to 12 minutes after sunset. Universally auspicious for any activity, especially marriages and grihapravesha. No blemish from tithi, vara, nakshatra, karana, or yoga applies during Godhuli. Null only in polar regions where sun does not set."},"pratahSandhya":{"type":["object","null"],"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Pratah Sandhya, morning twilight junction period for Sandhyavandanam prayer. Spans 3 night ghatis before sunrise to sunrise. Duration varies by location and season based on ratrimana (night duration). One of the three daily Sandhya prayer times prescribed in Dharmashastra."},"sayahnaSandhya":{"type":["object","null"],"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"],"description":"Sayahna Sandhya, evening twilight junction period for Sandhyavandanam prayer. Spans sunset to 3 night ghatis after sunset. Duration varies by location and season based on ratrimana (night duration). One of the three daily Sandhya prayer times prescribed in Dharmashastra."},"durMuhurta":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"]},"description":"Dur Muhurta (Dur Muhurtam), inauspicious muhurta periods determined by the weekday. The daytime is divided into 15 muhurtas from sunrise to sunset. Specific muhurta numbers are inauspicious each weekday per Muhurta Chintamani. Each period lasts ~48 minutes. Most days have 2 Dur Muhurtas, Wednesday and Sunday have 1. Avoid initiating important activities during these periods."},"varjyam":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"]},"description":"Varjyam (Thyajyam, Vishghati, Nakshatra Thyajyam), inauspicious ~96-minute period based on Moon transit through specific ghati fractions within the current nakshatra. Each of the 27 nakshatras has a fixed Varjyam window measured in ghatikas (1 ghati = 24 minutes). Avoid starting new ventures, travel, or auspicious ceremonies during Varjyam. Usually 1-2 periods per panchang day."},"amritKalam":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","example":"2026-02-03T09:00:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."},"end":{"type":"string","example":"2026-02-03T10:30:00","description":"Period end time in ISO 8601 format. Timezone-adjusted based on the input timezone offset."}},"required":["start","end"]},"description":"Amrit Kalam (Amrit Ghati, Amrita Yoga), the most auspicious ~96-minute period based on Moon transit through specific ghati fractions within the current nakshatra. Each of the 27 nakshatras has a fixed Amrit window. Activities initiated during Amrit Kalam are believed to yield excellent, lasting results. Highly recommended for muhurta selection when other auspicious yogas are absent. Usually 1-2 periods per panchang day."},"chandrabalam":{"type":"object","properties":{"favorableRashis":{"type":"array","items":{"type":"string"},"example":["Aries","Taurus","Leo","Libra","Sagittarius","Capricorn"],"description":"Rashis (zodiac signs) for which Moon transit is favorable today. Chandrabalam is positive when Moon transits 1st, 3rd, 6th, 7th, 10th, or 11th house from birth rashi."},"ashtamaChandraRashi":{"type":"string","example":"Pisces","description":"Rashi for which Moon is in Ashtama (8th house) position. highly inauspicious. Natives of this rashi should avoid important activities."}},"required":["favorableRashis","ashtamaChandraRashi"],"description":"Chandrabalam (Moon strength). indicates auspiciousness of Moon transit for each birth rashi. Essential for muhurta selection in Vedic electional astrology."},"tarabalam":{"type":"object","properties":{"favorableNakshatras":{"type":"array","items":{"type":"string"},"example":["Bharani","Rohini","Ardra","Pushya","Ashlesha"],"description":"Birth nakshatras with favorable Tarabalam based on Moon nakshatra transit. Derived from the 9-Tara system. taras Sampat, Kshema, Sadhaka, Mitra, and Parama Mitra are favorable."},"unfavorableNakshatras":{"type":"array","items":{"type":"string"},"example":["Krittika","Mrigashira","Punarvasu"],"description":"Birth nakshatras with unfavorable Tarabalam (Vipat, Pratyari, Vadha taras). Natives of these birth nakshatras should exercise caution."}},"required":["favorableNakshatras","unfavorableNakshatras"],"description":"Tarabalam (Star strength). based on the 9-Tara nakshatra cycle. Determines favorability of Moon nakshatra transit relative to each of the 27 birth nakshatras."},"panchaka":{"type":"object","properties":{"active":{"type":"boolean","example":true,"description":"True when Panchaka is in effect on this date, whether it is already running at sunrise or begins later in the day, in which case startsAt and endsAt give the window. False only when no Panchaka touches this date."},"type":{"type":["string","null"],"example":"Mrityu","description":"Panchaka dosha, set by the weekday the period BEGINS (not the nakshatra): Roga (Sunday, disease), Raja (Monday, government), Agni (Tuesday, fire), Chora (Friday, theft), Mrityu (Saturday, death). Null when Panchaka begins on Wednesday or Thursday (no dosha) or when no Panchaka touches this date."},"startsAt":{"type":["string","null"],"example":"2026-06-06T19:03:00","description":"When the Panchaka period starts (Moon enters 300 degrees, Dhanishta 3rd pada). May predate this date when Panchaka is already running. Null when no Panchaka is in force or begins on this date. In requested timezone."},"endsAt":{"type":["string","null"],"example":"2026-06-11T08:15:00","description":"When the Panchaka period ends (Moon exits Revati at 360 degrees), about five days after it starts. Null when no Panchaka. In requested timezone."}},"required":["active","type","startsAt","endsAt"],"description":"Panchaka, the inauspicious ~5-day window while the Moon transits the last five nakshatras (Dhanishta 3rd pada through Revati, 300 to 360 degrees sidereal). The dosha type depends on the weekday it begins; startsAt and endsAt report the period in force at sunrise or beginning later this day. Avoid major activities during Panchaka."},"bhadra":{"type":"object","properties":{"active":{"type":"boolean","example":true,"description":"True when a Bhadra (Vishti Karana) occurs on this date, in which case startsAt and endsAt give its window. False only when no Bhadra begins on this date."},"startsAt":{"type":["string","null"],"example":"2026-06-10T13:53:00","description":"When the Bhadra (Vishti) period that begins on this date starts. Null when no Bhadra begins on this date. In requested timezone."},"endsAt":{"type":["string","null"],"example":"2026-06-11T00:58:00","description":"When the Bhadra (Vishti) period that begins on this date ends. May fall on the next calendar day. Null when no Bhadra begins on this date. In requested timezone."}},"required":["active","startsAt","endsAt"],"description":"Bhadra (Vishti Karana), the 7th movable karana, avoided for all auspicious activities. Bhadra recurs roughly every 3 to 5 days and lasts about half a tithi. active is true whenever a Bhadra is attributed to this date; startsAt and endsAt give the window, which may end on the next calendar day."},"transitions":{"type":"object","properties":{"tithi":{"type":"object","properties":{"endsAt":{"type":"string","example":"2026-02-03T14:53:00","description":"ISO 8601 UTC time when the current tithi ends. Precise to ~1 minute via binary search."},"next":{"type":"string","example":"Dvadashi","description":"Name of the next tithi that begins after the transition."}},"required":["endsAt","next"],"description":"Tithi (lunar day) transition timing: when the current tithi ends and the next one begins."},"yoga":{"type":"object","properties":{"endsAt":{"type":"string","example":"2026-02-03T10:15:00","description":"ISO 8601 UTC time when the current yoga ends."},"next":{"type":"string","example":"Shobhana","description":"Name of the next yoga."}},"required":["endsAt","next"],"description":"Nitya Yoga transition timing: when the current yoga period ends. Based on combined Sun-Moon motion."},"karana":{"type":"object","properties":{"endsAt":{"type":"string","example":"2026-02-03T08:30:00","description":"ISO 8601 UTC time when the current karana ends."},"next":{"type":"string","example":"Balava","description":"Name of the next karana (half-tithi)."}},"required":["endsAt","next"],"description":"Karana (half-tithi) transition. karanas change twice per tithi. Important for muhurta timing."},"nakshatra":{"type":"object","properties":{"endsAt":{"type":"string","example":"2026-02-03T16:22:00","description":"ISO 8601 UTC time when the Moon leaves the current nakshatra."},"next":{"type":"string","example":"Jyeshtha","description":"Name of the next nakshatra the Moon will enter."},"nextPada":{"type":"number","example":1,"description":"Pada (quarter, 1-4) of the next nakshatra. Each nakshatra has 4 padas spanning 3 degrees 20 minutes each."}},"required":["endsAt","next","nextPada"],"description":"Nakshatra (lunar mansion) transition timing: when Moon moves to the next nakshatra. Critical for muhurta and Tarabalam calculations."},"moonSign":{"type":"object","properties":{"current":{"type":"string","example":"Libra","description":"Current Moon rashi (zodiac sign)."},"changesAt":{"type":"string","example":"2026-02-04T01:11:00","description":"ISO 8601 UTC time when Moon enters the next rashi. Moon changes sign approximately every 2.25 days."},"next":{"type":"string","example":"Scorpio","description":"Next rashi the Moon will enter."}},"required":["current","changesAt","next"],"description":"Moon sign (Chandra rashi) transition, when Moon changes zodiac sign. Affects Chandrabalam, Tarabalam, and daily horoscope predictions."}},"required":["tithi","yoga","karana","nakshatra","moonSign"],"description":"Panchang element transition times. exact timing of when each element (tithi, yoga, karana, nakshatra, Moon sign) changes. Calculated using binary search for ~1 minute precision. Essential for precise muhurta determination and panchang calendars."}},"required":["date","location","vara","sunrise","sunset","moonrise","moonset","moonSign","sunSign","sunNakshatra","tithi","nakshatra","yoga","karana","hora","rahuKaal","yamaganda","gulika","abhijitMuhurta","brahmaMuhurta","vijayaMuhurta","nishitaMuhurta","godhuliMuhurta","pratahSandhya","sayahnaSandhya","durMuhurta","varjyam","amritKalam","chandrabalam","tarabalam","panchaka","bhadra","transitions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/panchang/choghadiya":{"post":{"operationId":"getChoghadiya","tags":["Vedic Astrology"],"summary":"Get Choghadiya - 8 Muhurta divisions of day and night","description":"Calculate Choghadiya (Chaughadia) muhurta timings for any date and location. Divides day (sunrise to sunset) and night (sunset to next sunrise) into 8 equal auspicious/inauspicious periods. Each period ruled by a planet: Udveg (Sun, bad), Amrit (Moon, good), Rog (Mars, bad), Labh (Mercury, good), Shubh (Jupiter, good), Char (Venus, good), Kaal (Saturn, bad). Essential for muhurta selection, daily planning, and traditional Hindu timekeeping. Choghadiya calculator API, daily muhurat timings, auspicious time finder.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-03","description":"Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees. Determines sunrise and sunset times which define day/night boundaries for muhurta calculations."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees. Affects local time calculations for sunrise, sunset, and muhurta period boundaries."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours. Used for accurate sunrise/sunset calculation and output time formatting. Essential for correct Choghadiya periods outside IST. Defaults to 5.5 (IST).","example":5.5}},"required":["date","latitude","longitude"]}}}},"responses":{"200":{"description":"8 daytime and 8 nighttime Choghadiya muhurta periods with names, ruling planets, auspiciousness ratings (Good/Bad), and exact start/end times based on sunrise and sunset.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-02-03","description":"Calendar date the choghadiya muhurta table was computed for, YYYY-MM-DD, echoed back from the request. The day periods run from that date sunrise to its sunset, and the night periods run on to the next sunrise."},"dayChoghadiya":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Udveg","Amrit","Rog","Labh","Shubh","Char","Kaal"],"example":"Shubh","description":"Choghadiya muhurta name. Auspicious: Amrit (Moon), Shubh (Jupiter), Labh (Mercury), Char (Venus). Inauspicious: Udveg (Sun), Rog (Mars), Kaal (Saturn)."},"lord":{"type":"string","example":"Jupiter","description":"Ruling planet of this Choghadiya period. Planet determines the quality and suitability of activities during this muhurta."},"effect":{"type":"string","enum":["Good","Bad"],"example":"Good","description":"Auspiciousness of this period. Good periods (Amrit, Shubh, Labh, Char) are suitable for important activities. Bad periods (Udveg, Rog, Kaal) should be avoided."},"start":{"type":"string","example":"2026-02-03T01:10:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on input timezone offset."},"end":{"type":"string","example":"2026-02-03T02:30:00","description":"Period end time in ISO 8601 format. Each Choghadiya period is one-eighth of the day or night duration."}},"required":["name","lord","effect","start","end"]},"description":"8 daytime choghadiya periods (sunrise to sunset)"},"nightChoghadiya":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Udveg","Amrit","Rog","Labh","Shubh","Char","Kaal"],"example":"Shubh","description":"Choghadiya muhurta name. Auspicious: Amrit (Moon), Shubh (Jupiter), Labh (Mercury), Char (Venus). Inauspicious: Udveg (Sun), Rog (Mars), Kaal (Saturn)."},"lord":{"type":"string","example":"Jupiter","description":"Ruling planet of this Choghadiya period. Planet determines the quality and suitability of activities during this muhurta."},"effect":{"type":"string","enum":["Good","Bad"],"example":"Good","description":"Auspiciousness of this period. Good periods (Amrit, Shubh, Labh, Char) are suitable for important activities. Bad periods (Udveg, Rog, Kaal) should be avoided."},"start":{"type":"string","example":"2026-02-03T01:10:00","description":"Period start time in ISO 8601 format. Timezone-adjusted based on input timezone offset."},"end":{"type":"string","example":"2026-02-03T02:30:00","description":"Period end time in ISO 8601 format. Each Choghadiya period is one-eighth of the day or night duration."}},"required":["name","lord","effect","start","end"]},"description":"8 nighttime choghadiya periods (sunset to next sunrise)"}},"required":["date","dayChoghadiya","nightChoghadiya"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/panchang/hora":{"post":{"operationId":"getHora","tags":["Vedic Astrology"],"summary":"Get Hora - 24 Planetary Hours (12 day + 12 night)","description":"Calculate all 24 Hora (planetary hour) periods for any date and location. Day is divided into 12 equal horas from sunrise to sunset, night into 12 equal horas from sunset to next sunrise. Each hora is ruled by a planet in the Chaldean sequence starting from the day lord. Hora timings API, planetary hours calculator, Vedic hora chart, electional astrology timing.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-03","description":"Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees. Determines sunrise and sunset times which define day/night boundaries for muhurta calculations."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees. Affects local time calculations for sunrise, sunset, and muhurta period boundaries."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours. Used for accurate sunrise/sunset calculation and output time formatting. Essential for correct Hora periods outside IST. Defaults to 5.5 (IST).","example":5.5}},"required":["date","latitude","longitude"]}}}},"responses":{"200":{"description":"12 daytime and 12 nighttime Hora (planetary hour) periods with ruling planet, sequence number, and exact start/end times based on sunrise and sunset.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-02-03","description":"Date for which hora periods were calculated."},"dayHoras":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Ruling planet of this hora period. Follows the Chaldean planetary order: Sun, Venus, Mercury, Moon, Saturn, Jupiter, Mars."},"number":{"type":"number","example":1,"description":"Hora period number within the day or night segment (1-12)."},"start":{"type":"string","example":"2026-02-03T01:10:00","description":"Start time of the hora period in ISO 8601 format."},"end":{"type":"string","example":"2026-02-03T02:05:00","description":"End time of the hora period in ISO 8601 format."}},"required":["planet","number","start","end"]},"description":"12 daytime hora periods from sunrise to sunset. Duration varies by season."},"nightHoras":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Ruling planet of this hora period. Follows the Chaldean planetary order: Sun, Venus, Mercury, Moon, Saturn, Jupiter, Mars."},"number":{"type":"number","example":1,"description":"Hora period number within the day or night segment (1-12)."},"start":{"type":"string","example":"2026-02-03T01:10:00","description":"Start time of the hora period in ISO 8601 format."},"end":{"type":"string","example":"2026-02-03T02:05:00","description":"End time of the hora period in ISO 8601 format."}},"required":["planet","number","start","end"]},"description":"12 nighttime hora periods from sunset to next sunrise. Duration varies by season."}},"required":["date","dayHoras","nightHoras"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dosha/manglik":{"post":{"operationId":"checkManglikDosha","tags":["Vedic Astrology"],"summary":"Check Manglik Dosha - Mangal Dosha Calculator API","description":"Detect Manglik dosha (Kuja dosha, Mars dosha) based on Mars position in inauspicious houses (1, 2, 4, 7, 8, 12) from Lagna. Accurate mangal dosha calculator for matrimonial compatibility checks in Vedic astrology. Returns severity levels (Mild/Moderate/Severe) and cancellation factors. Essential for kundli matching for marriage, manglik compatibility, and marriage astrology in matrimonial sites. Includes exceptions that reduce manglik dosha effects.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManglikRequest"}}}},"responses":{"200":{"description":"Manglik dosha detection result with severity, Mars house placement, cancellation exceptions, traditional remedies, and effects on marriage and personality.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManglikResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dosha/kalsarpa":{"post":{"operationId":"checkKalsarpaDosha","tags":["Vedic Astrology"],"summary":"Check Kalsarpa Dosha - Kalsarpa Yoga Calculator API","description":"Detect Kalsarpa dosha (Kalsarpa yoga) when all 7 planets are hemmed between Rahu-Ketu axis. Accurate kalsarpa dosha calculator identifying 12 types (Ananta, Kulik, Vasuki, Shankhapala, Padma, Mahapadma, Takshak, Karkotak, Shankhachud, Ghatak, Vishdhar, Sheshnag). Returns severity and effects based on Rahu house position. Essential for Vedic astrology dosha analysis, birth chart evaluation, and matrimonial compatibility. Considered significant dosha affecting life obstacles and spiritual growth.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KalsarpaRequest"}}}},"responses":{"200":{"description":"Kalsarpa dosha detection result with type identification (1 of 12 types), severity, Rahu-Ketu axis details, traditional remedies, and effects on career, health, and relationships.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KalsarpaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/dosha/sadhesati":{"post":{"operationId":"checkSadhesati","tags":["Vedic Astrology"],"summary":"Check Sadhesati - Sade Sati Calculator API (Saturn Transit)","description":"Calculate Sadhesati (Sade Sati) periods when Saturn transits 12th, 1st, and 2nd houses from natal Moon. Accurate sade sati calculator with current status and phase identification (Rising/Peak/Setting). Shani sadhesati 7.5 year period tracker. Returns Saturn transit dates and effects on life. Essential for Saturn transit analysis, sadhesati remedies timing, and understanding challenging Saturn periods in Vedic astrology. Important for timing major life decisions.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SadhesatiRequest"}}}},"responses":{"200":{"description":"Sade Sati detection result with current phase (Rising/Peak/Setting), Saturn transit position relative to natal Moon, severity, traditional Shani remedies, and phase-specific effects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SadhesatiResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/yoga":{"get":{"operationId":"listYogas","tags":["Vedic Astrology"],"summary":"List all planetary yogas - 301 entry Vedic Yoga Glossary","description":"Browse the 301-entry Vedic planetary-yoga glossary. Returns id and name for every cataloged yoga (Raja, Dhana, Pancha Mahapurusha, Nabhasa, Chandra-Mangala, and more). This is a dictionary lookup, not chart-driven detection: it does not inspect a birth chart. Use GET /yoga/{id} for the full glossary entry, or POST /yoga/detect to run all 48 detection rules against a specific kundli. Ideal for yoga-browser UIs, search, and progressive data loading.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Filter the catalog to one Nabhasa family: asraya (3), dala (2), akriti (20) or sankhya (7). Omit for the full catalog. `classical` is accepted but matches nothing here, because it is a detection-verdict value for single-combination yogas rather than a catalog grouping."},"required":false,"description":"Filter the catalog to one Nabhasa family: asraya (3), dala (2), akriti (20) or sankhya (7). Omit for the full catalog. `classical` is accepted but matches nothing here, because it is a detection-verdict value for single-combination yogas rather than a catalog grouping.","name":"family","in":"query"}],"responses":{"200":{"description":"List of all yogas (basic info)","content":{"application/json":{"schema":{"type":"object","properties":{"yogas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"gajakesari","description":"Unique yoga identifier in lowercase kebab-case. Use this to fetch full details via GET /yoga/{id}."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Traditional Sanskrit name of the planetary yoga combination."},"family":{"type":"string","enum":["classical","asraya","dala","akriti","sankhya"],"example":"akriti","description":"Nabhasa family, present only on the 32 Nabhasa distribution yogas and absent on every other catalog row. Never translated, so it groups identically under any lang."}},"required":["id","name"]},"description":"Array of planetary yogas with basic identifiers, narrowed by `family` when that filter is supplied. Use GET /yoga/{id} for formation rules, effects, and quality classification."},"total":{"type":"number","example":300,"description":"Number of yogas in this response, which is the filtered count when `family` is supplied and the full catalog size otherwise. Includes Raj Yogas, Dhan Yogas, Pancha Mahapurusha Yogas, Nabhasa Yogas, and more."}},"required":["yogas","total"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/yoga/{id}":{"get":{"operationId":"getYoga","tags":["Vedic Astrology"],"summary":"Get yoga details by ID - Vedic Yoga Glossary Entry","description":"Look up the dictionary entry for a specific named yoga from the 301-entry Vedic planetary-yoga glossary. Returns formation conditions, life results, and quality classification (Positive/Negative/Both). This is a glossary lookup against the static catalog; it does NOT analyze a birth chart. For chart-driven present/absent verdicts on the 48 detection-grade yogas (Gajakesari, the Pancha Mahapurusha set, all 32 Nabhasa distribution yogas, and the wealth and poverty verdicts) call POST /yoga/detect with birth data.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["gajakesari","sunapha","anapha","dhurdhura","kemadruma","chandramangala","adhi","chatussagara","vasumathi","rajalakshana","vanchanachorabheethi","sakata","amala","parvata","kahala","vesi","vasi","obhayachari","hamsa","malavya","sasa","ruchaka","bhadra","budhaaditya","mahabhagya","pushkala","lakshmi","gauri","bharathi","chapa","sreenatha","lagnamalika","dhanamalika","vikramamalika","sukhamalika","putramalika","satrumalika","kalatramalika","randhramalika","bhagyamalika","karmamalika","labhamalika","vrayamalika","sankha","bheri","mridanga","parijatha","gaja","kalanidhi","amsavatara","hariharabrahma","kusuma","matsya","kurma","devendra","makuta","chandika","jaya","vidyut","gandharva","siva","vishnu","brahma","indra","ravi","garuda","go","gola","thrilochana","kulavardhana","yupa","ishu","sakti","danda","nav","kuta","chhatra","chapa-2","ardhachandra","chandra","gada","sakata-2","vihaga","vajra","yava","sringhataka","hala","kamala","vapee","samudra","vallaki","damni","pasa","kedara","sula","yuga","gola-2","rajju","musala","nala","srik","mala","sarpa","duryoga","daridra","harsha","sarala","vimala","sareerasoukhya","dehapushti","dehakashta","rogagrastha","krisanga","krisanga-2","dehasthoulya","dehasthoulya-2","dehasthoulya-3","sadasanchara","dhana","dhana-2","dhana-3","dhana-4","dhana-5","dhana-6","dhana-7","dhana-8","dhana-9","dhana-10","dhana-11","bahudravyarjana","swaveeryaddhana","swaveeryaddhana-2","swaveeryaddhana-3","madhyavayasidhana","anthyavayasidhana","balyadhana","bhratrumooladdhanaprapti","bhratrumooladdhanaprapti-2","matrumooladdhana","putramooladdhana","satrumooladdhana","kalatramooladdhana","amarananthadhana","ayatnadhanalabha","daridra-2","daridra-3","daridra-4","daridra-5","daridra-6","daridra-7","daridra-8","daridra-9","daridra-10","daridra-11","yukthisamanwithavagmi","yukthisamanwithavagmi-2","parihasaka","asatyavadi","jada","bhaskara","marud","saraswathi","budha","mooka","netranasa","andha","sumukha","sumukha-2","durmukha","durmukha-2","bhojanasoukhya","annadana","parannabhojana","sraddhannabhuktha","sarpaganda","vakchalana","vishaprayoga","bhratruvriddhi","sodaranasa","ekabhagini","dwadasasahodara","sapthasankhyasahodara","parakrama","yuddhapraveena","yuddhatpoorvadridhachitta","yuddhatpaschaddrudha","satkathadisravana","uttamagriha","vichitrasaudhaprakara","ayatnagrihaprapta","ayatnagrihaprapta-2","grihanasa","grihanasa-2","bandhupujya","bandhupujya-2","bandhubhisthyaktha","matrudeerghayur","matrudeerghayur-2","matrunasa","matrunasa-2","matrugami","sahodareesangama","kapata","kapata-2","kapata-3","nishkapata","nishkapata-2","matrusatrutwa","matrusneha","vahana","vahana-2","anapathya","sarpasapa","sarpasapa-2","sarpasapa-3","sarpasapa-4","pitrusapasutakshaya","matrusapasutakshaya","bhratrusapasutakshaya","pretasapa","bahuputra","bahuputra-2","dattaputra","dattaputra-2","aputra","ekaputra","suputra","kalanirdesatputra","kalanirdesatputra-2","kalanirdesatputranasa","kalanirdesatputranasa-2","buddhimaturya","theevrabuddhi","buddhijada","thrikalagnana","putrasukha","jara","jarajaputra","bahustree","satkalatra","bhagachumbana","bhagya","jananatpurvampitrumarana","dhatrutwa","apakeerti","raja","raja-2","raja-3","raja-4","raja-5","raja-6","raja-7","raja-8","raja-9","raja-10","raja-11","raja-12","raja-13","raja-14","raja-15","raja-16","raja-17","raja-18","raja-19","galakarna","vrana","sisnavyadhi","kalatrashanda","kushtaroga","kushtaroga-2","kshayaroga","bandhana","karascheda","sirachcheda","durmarana","yuddhemarana","sanghatakamarana","sanghatakamarana-2","peenasaroga","pittaroga","vikalangapatni","putrakalatraheena","bharyasahavyabhichara","vamsacheda","guhyaroga","angaheena","swetakushta","pisachagrastha","andha-2","andha-3","vatharoga","matibhramana","matibhramana-2","matibhramana-3","matibhramana-4","khalwata","nishturabhashi","rajabhrashta","raja-20","raja-21","gohanta"],"example":"gajakesari","description":"Yoga identifier (lowercase, hyphenated)"},"required":true,"description":"Yoga identifier (lowercase, hyphenated)","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Detailed yoga information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YogaDetail"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Yoga not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/yoga/detect":{"post":{"operationId":"detectYogas","tags":["Vedic Astrology"],"summary":"Detect classical Vedic yogas in a birth chart","description":"Chart-driven detection of 48 classical Vedic yogas. Twelve conjunction and dignity yogas: Gajakesari (parashara three-rule definition), Sunapha, Anapha, Dhurdhura, Kemadruma, Chandra Mangala, Budha-Aditya, and the five Pancha Mahapurusha yogas (Ruchaka, Bhadra, Hamsa, Malavya, Sasa). Plus all 32 Nabhasa distribution yogas, which describe how the seven visible grahas are spread across the whole chart rather than any single conjunction, across four families: Asraya (Rajju, Musala, Nala), Dala (Mala, Sarpa), Akriti (Gada, Shakata, Vihaga, Shringataka, Hala, Vajra, Yava, Kamala, Vapi, Yupa, Shara, Shakti, Danda, Nauka, Kuta, Chhatra, Dhanusha, Ardhachandra, Chakra, Samudra) and Sankhya (Gola, Yuga, Shoola, Kedara, Pasa, Damini, Veena). Plus four wealth and poverty verdicts, each ONE answer over a whole family of classical rules: Dhana Yoga over the eleven catalogued wealth combinations of BPHS ch. 41, Daridra Yoga over the poverty combinations of BPHS ch. 42 and Phaladeepika ch. 6, Lakshmi Yoga (BPHS ch. 36), and Dhana Malika (Jataka Parijata ch. 7). Their evidence names every rule that matched and the exact condition it matched on, so a wealth reading cites the combination rather than a label, and a rule resting on a single authority is excluded from the verdict and says so rather than quietly counting. Each yoga is returned with an `id`, `name`, a `present` boolean, a `quality` (Positive, Negative, or Both, i.e. auspicious, inauspicious, or context-dependent), and a classical-text `evidence` string naming the rule that triggered or failed (kendra position, dignity, malefic drishti, lordship, retrograde state, sign modality, bhava distribution). Nabhasa results also apply the four classical precedence norms, so a yoga that matched its own rule but was outranked by a stronger family is returned as absent with evidence naming the norm that silenced it, letting you explain a verdict rather than only report it. There is no separate major/minor flag; `quality` is the auspiciousness axis. Unlike GET /yoga and GET /yoga/{id} which are dictionary lookups, this endpoint computes the kundli from birth data and runs the detection rules. Sources: BPHS ch. 35 and ch. 75, Mantreswara Phaladeepika ch. 6, B.V. Raman Three Hundred Important Combinations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/YogaDetectRequest"}}}},"responses":{"200":{"description":"List of 48 classical yogas with present/absent verdicts and classical-text evidence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YogaDetectResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/ayanamsa":{"get":{"operationId":"getKpAyanamsa","tags":["Vedic Astrology"],"summary":"Get KP-Newcomb ayanamsa - Dynamic daily calculation","description":"Get the KP-Newcomb (Krishnamurti) ayanamsa for any instant, computed continuously from Newcomb precession theory rather than looked up in a preset table, so it tracks the exact moment you ask for instead of the calendar year. Supply date alone for midnight UTC, or add time and timezone to pin a birth moment exactly. This is the precession offset subtracted from a tropical longitude to obtain the sidereal one, and it is what makes a KP chart reproduce the reference software your practitioners already use. Returns the same value every KP endpoint applies internally. KP Newcomb ayanamsa API, dynamic ayanamsa calculator, Krishnamurti ayanamsa today, current KP ayanamsa","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"date","example":"2025-12-26","description":"Date for ayanamsa calculation in YYYY-MM-DD format. Defaults to today if not provided. Ayanamsa changes by ~0.01 degrees per month due to the precession of Earth."},"required":false,"description":"Date for ayanamsa calculation in YYYY-MM-DD format. Defaults to today if not provided. Ayanamsa changes by ~0.01 degrees per month due to the precession of Earth.","name":"date","in":"query"},{"schema":{"type":"string","format":"time","example":"09:00:00","description":"Time of day in 24-hour HH:MM:SS format, interpreted in the timezone below. Omit for midnight UTC. The ayanamsa moves about 0.14 arcseconds across a day, so supplying the time matters only when reconciling a chart against reference software to the arcsecond."},"required":false,"description":"Time of day in 24-hour HH:MM:SS format, interpreted in the timezone below. Omit for midnight UTC. The ayanamsa moves about 0.14 arcseconds across a day, so supplying the time matters only when reconciling a chart against reference software to the arcsecond.","name":"time","in":"query"},{"schema":{"type":"string","example":"Asia/Kolkata","description":"IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"), decimal hours (e.g. 5.5 for IST, -5 for EST), or a fixed UTC offset (e.g. \"+05:30\"). IANA resolved to the DST-correct offset for the given date. Applies to the time field above. Defaults to 0 (UTC)."},"required":false,"description":"IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"), decimal hours (e.g. 5.5 for IST, -5 for EST), or a fixed UTC offset (e.g. \"+05:30\"). IANA resolved to the DST-correct offset for the given date. Applies to the time field above. Defaults to 0 (UTC).","name":"timezone","in":"query"}],"responses":{"200":{"description":"Successfully calculated KP-Newcomb ayanamsa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPAyanamsaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/planets":{"post":{"operationId":"getKpPlanets","tags":["Vedic Astrology"],"summary":"Get KP planetary positions with sub-lords","description":"Get planetary positions with detailed KP star-lord and sub-lord calculations for precise event timing and significator analysis. Returns all 9 planets (Sun through Ketu) with nakshatra, star-lord, sub-lord, and KP horary numbers (1-249). Essential for KP astrology software, significator analysis, and event prediction. KP planet positions API, star lord sub lord calculator, KP significator API, Krishnamurti Paddhati planets","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPPlanetsRequest"}}}},"responses":{"200":{"description":"Successfully calculated KP planetary positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPPlanetsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/cusps":{"post":{"operationId":"getKpCusps","tags":["Vedic Astrology"],"summary":"Get KP Placidus house cusps with sub-lords","description":"Calculate unequal Placidus house cusps with ruling sign-lord, nakshatra-lord, and sub-lord for each cusp. Dynamic KP-Newcomb or custom ayanamsa support. Used in KP horary astrology, cusp sub-lord analysis, and birth chart rectification. Returns all 12 house cusps with KP sub-division details. SEO: Placidus house cusps API, KP cusp calculator, house cusps star sub lord, KP horary cusps","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPCuspsRequest"}}}},"responses":{"200":{"description":"Successfully calculated Placidus house cusps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPCuspsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/chart":{"post":{"operationId":"generateKpChart","tags":["Vedic Astrology"],"summary":"Generate complete KP birth chart","description":"Generate authentic Krishnamurti Paddhati birth charts with Placidus house cusps, star-lord and sub-lord calculations. Supports custom ayanamsa and dynamic KP-Newcomb ayanamsa calculation. Returns complete chart with all 9 planets (Sun through Ketu), Ascendant, 12 Placidus house cusps, nakshatra details, star-lords, sub-lords, and KP horary numbers (1-249). Perfect for KP astrology software, horary prediction apps, and event timing analysis. SEO: KP astrology chart API, Placidus house cusps planets, Krishnamurti Paddhati chart generator, KP birth chart calculator","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPChartRequest"}}}},"responses":{"200":{"description":"Successfully generated KP birth chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/ruling-planets":{"post":{"operationId":"getKpRulingPlanets","tags":["Vedic Astrology"],"summary":"Get KP ruling planets with optional significators","description":"Calculate the 5 ruling planets at any moment using Krishnamurti Paddhati horary astrology. Returns Day Lord, Moon Sign/Star/Sub Lord, Lagna Sign/Star/Sub Lord. Optionally provide birth data (birthDate, birthTime) to include significators showing which houses each ruling planet signifies in the birth chart - essential for KP prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"example":28.6139,"description":"Observer latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":77.209,"description":"Observer longitude in decimal degrees"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC. IANA resolved to the DST-correct offset based on birthDate or datetime. Defaults to 5.5.","example":5.5},"datetime":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z","description":"ISO 8601 datetime (YYYY-MM-DDTHH:MM:SS) for ruling planets. Defaults to current time. Interpreted as local time when a non-zero timezone is provided (a trailing Z is accepted but ignored); with timezone 0 it is UTC."},"birthDate":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date (YYYY-MM-DD) to calculate significators. If provided with birthTime, response includes which houses each ruling planet signifies."},"birthTime":{"type":"string","format":"time","example":"10:12:00","description":"Birth time (HH:MM:SS) for significator calculation. Required if birthDate is provided."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["latitude","longitude"]}}}},"responses":{"200":{"description":"Ruling planets calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPRulingPlanetsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/ruling-planets-interval":{"post":{"operationId":"getKpRulingInterval","tags":["Vedic Astrology"],"summary":"Get KP ruling planets with significators at intervals","description":"Calculate ruling planets and their KP significators at regular time intervals using Krishnamurti Paddhati prashna (horary) astrology. For each interval, a full Placidus house chart is erected and significators are computed using the 4-level KP hierarchy: Level 1 (strongest) planets in star of house occupant, Level 2 occupants, Level 3 planets in star of house owner, Level 4 house owner. Returns Day Lord (sunrise-based Hindu Vara), Moon Sign/Star/Sub/Sub-Sub Lords, Lagna Sign/Star/Sub/Sub-Sub Lords, unique ruling planets set, and per-ruling-planet house significations. No birth data needed, significators come from each moments sky chart. Use for birth time rectification, muhurta selection, and KP horary number analysis.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startDatetime":{"type":"string","format":"date-time","example":"2026-02-03T00:00:00Z","description":"Start of the interval range in ISO 8601 (YYYY-MM-DDTHH:MM:SS). Interpreted as local time when a non-zero timezone is provided (a trailing Z is accepted but ignored); with timezone 0 it is UTC."},"endDatetime":{"type":"string","format":"date-time","example":"2026-02-03T01:00:00Z","description":"End of the interval range in ISO 8601 (YYYY-MM-DDTHH:MM:SS). Interpreted as local time when a non-zero timezone is provided (a trailing Z is accepted but ignored); with timezone 0 it is UTC."},"intervalMinutes":{"type":"integer","minimum":1,"maximum":1440,"example":5,"description":"Interval between calculations in minutes (1-1440). Use 1-5 for birth time rectification."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours. When non-zero, all datetimes are treated as local time in this timezone (Z suffix is ignored). Output times are also converted to this timezone. Defaults to 5.5 (IST).","example":5.5},"ayanamsa":{"type":"string","enum":["kp-newcomb","kp-old","lahiri","raman"],"default":"kp-newcomb","example":"kp-newcomb","description":"Ayanamsa system for sidereal conversion. \"kp-newcomb\" uses the KP-Newcomb dynamic formula, the most common choice for KP astrology. \"kp-old\" uses the Krishnamurti original table from KP Reader-1 with constant precession rate. \"lahiri\" uses Lahiri/Chitrapaksha ayanamsa, matching most traditional Vedic software. \"raman\" uses the B.V. Raman ayanamsa from Hindu Predictive Astrology, a recognised traditional school that sits about 1.45 degrees below Lahiri. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the Rahu and Ketu positions. Mean is the traditional Vedic default and what printed panchangs use; the choice can move a KP sub-lord in narrow boundary cases, where a span can be as small as 0.5 degrees. Defaults to \"mean\"."}},"required":["startDatetime","endDatetime","intervalMinutes","latitude","longitude"]}}}},"responses":{"200":{"description":"Ruling planets with significators at intervals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPRulingPlanetsIntervalResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/sublord-changes":{"post":{"operationId":"getKpSublordChanges","tags":["Vedic Astrology"],"summary":"Find KP sublord changes","description":"Track when planets cross KP sublord boundaries (1-249 divisions) for precise Krishnamurti Paddhati event timing. Returns exact timestamps when a planet transitions between sublords, essential for prashna kundali analysis and dasha predictions. Use this to find favorable windows when benefic sublords are active. Supports Sun, Moon, Mars, Mercury, Jupiter, Venus, and Saturn tracking over any date range.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPSublordChangesRequest"}}}},"responses":{"200":{"description":"Sublord change timings calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPSublordChangesResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/rasi-changes":{"post":{"operationId":"getKpRasiChanges","tags":["Vedic Astrology"],"summary":"Find KP rasi ingress times","description":"Track when planets enter new zodiac signs (rasi) with precise ingress timestamps. Essential for Vedic astrology transit analysis, muhurta selection, and predictive horoscope readings. Returns exact times when planets cross sign boundaries (0, 30, 60 degrees etc). Use for tracking Sun sankranti dates, Moon sign changes for panchang, or outer planet transits for yearly predictions.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPRasiChangesRequest"}}}},"responses":{"200":{"description":"Sign ingress timings calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPRasiChangesResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/planets-interval":{"post":{"operationId":"getKpPlanetsInterval","tags":["Vedic Astrology"],"summary":"Get KP planets at time intervals","description":"Calculate positions of all 9 planets (Sun through Saturn, Rahu, Ketu) at regular time intervals with full KP hierarchy: sign lord, star lord, sublord, and sub-sublord. Returns longitude, zodiac sign, nakshatra, sublord, sub-sublord, and KP number (1-249) for each planet at each timestamp. Ideal for tracking planetary motion, finding optimal muhurta windows, analyzing transit patterns, and building KP ephemeris tables. Maximum range of 7 days with 15-minute to 24-hour intervals.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPPlanetsIntervalRequest"}}}},"responses":{"200":{"description":"Planetary positions calculated at all intervals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPPlanetsIntervalResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/kp/horary":{"post":{"operationId":"castKpHoraryChart","tags":["Vedic Astrology"],"summary":"Cast a KP horary (Prashna) chart from a number 1-249 - KP Horary API","description":"Cast a Krishnamurti Paddhati horary chart, also called Prashna, from a number between 1 and 249 given by the querent plus the moment and place the question is judged. NO BIRTH DETAILS ARE NEEDED, which is what makes horary the KP answer when birth time is unknown or unreliable. The number maps to one of the 249 KP sub divisions and sets the Ascendant; the twelve Placidus cusps follow from that Ascendant at the given latitude, and every planetary position comes from the real sky at the moment of the question. Returns the Ascendant with its sub lord, all twelve cusps with star lord and sub lord, the nine grahas placed against those cusps, the five ruling planets for validating the chart, and four-level significators for judging which houses each graha supports. KP horary API, Prashna kundali calculator, 249 horary number chart, Krishnamurti Paddhati horary, cusp sub lord question answering.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPHoraryRequest"}}}},"responses":{"200":{"description":"Horary chart with the Ascendant from the number, Placidus cusps, planets at the question moment, ruling planets, and four-level significators.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KPHoraryResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/aspects":{"post":{"operationId":"calculateDrishti","tags":["Vedic Astrology"],"summary":"Get planetary aspects (Drishti) - Mutual aspects between all planets","description":"Calculate all planetary aspects (Drishti) for a given time. Returns full aspects (7th house for all planets) and special aspects (Mars 4th/8th, Jupiter 5th/9th, Saturn 3rd/10th). Includes aspect table grouped by planet, mutual aspects, and individual aspect details with orb calculation. Essential for birth chart analysis, compatibility checking, and transit predictions. Planetary aspects API, drishti calculator, vedic astrology aspects, graha drishti.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-03","description":"Date in YYYY-MM-DD format. Planetary positions are calculated for this date to determine mutual aspects (drishti)."},"time":{"type":"string","format":"time","example":"12:00:00","description":"Time in HH:MM:SS format (24-hour). Exact time affects fast-moving planets (Moon, Mercury) and aspect orbs."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees. Used for Lagna calculation which affects house-based aspect analysis."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees. Affects local sidereal time for positional calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Aspects calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","description":"Chart time the aspects were calculated for, echoed back as the local wall clock of the request (ISO 8601, no offset). This is the `date` and `time` you sent, NOT a UTC instant: hold them fixed and vary `timezone` and every longitude moves while this field does not. Combine it with the `timezone` you sent to recover the absolute moment.","example":"1990-06-15T14:30:00"},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Mars","description":"Planet name (Sun through Ketu, all 9 Vedic grahas)."},"longitude":{"type":"number","example":285.67,"description":"Sidereal longitude in degrees (0-360)."},"sign":{"type":"string","example":"Capricorn","description":"Vedic zodiac sign (rashi) the planet occupies."}},"required":["name","longitude","sign"]},"description":"Sidereal positions of all 9 planets at the given time."},"aspects":{"type":"array","items":{"type":"object","properties":{"aspectingPlanet":{"type":"string","example":"Mars","description":"Planet casting the aspect (graha drishti)."},"aspectedPlanet":{"type":"string","example":"Moon","description":"Planet receiving the aspect."},"aspectType":{"type":"string","enum":["conjunction","7th","4th","8th","5th","9th","3rd","10th"],"example":"7th","description":"Vedic aspect type. All planets have 7th aspect. Special aspects: Mars 4th/8th, Jupiter 5th/9th, Saturn 3rd/10th."},"strength":{"type":"number","example":100,"description":"Aspect strength percentage (0-100). 100 = exact aspect, decreases with orb distance."},"orb":{"type":"number","example":2.5,"description":"Angular distance from exact aspect in degrees. Smaller orb = more potent aspect."}},"required":["aspectingPlanet","aspectedPlanet","aspectType","strength","orb"]},"description":"Complete list of all Vedic aspects (drishti) between planets. Includes full (7th) and special aspects (Mars 4th/8th, Jupiter 5th/9th, Saturn 3rd/10th)."},"aspectTable":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Planet casting aspects."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Planet being aspected."},"aspectType":{"type":"string","example":"8th","description":"Vedic aspect house (7th, 4th, 8th, 5th, 9th, 3rd, 10th, or conjunction)."},"strength":{"type":"number","example":85,"description":"Aspect strength percentage."}},"required":["planet","aspectType","strength"]},"description":"All aspects cast by this planet."}},"required":["planet","aspects"]},"description":"Aspect table grouped by aspecting planet. useful for rendering aspect grids in astrology software."},"mutualAspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Mars","description":"First planet in the mutual aspect pair."},"planet2":{"type":"string","example":"Saturn","description":"Second planet in the mutual aspect pair."},"aspectType":{"type":"string","example":"7th","description":"The aspect type shared mutually. Mutual aspects are especially strong in Vedic astrology."}},"required":["planet1","planet2","aspectType"]},"description":"Pairs of planets aspecting each other simultaneously. Mutual aspects amplify planetary influence significantly."}},"required":["datetime","planets","aspects","aspectTable","mutualAspects"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/aspects/monthly":{"post":{"operationId":"getMonthlyAspects","tags":["Vedic Astrology"],"summary":"Monthly Planetary Aspects - Major and minor aspect events for a month","description":"Calculate all planetary aspect events (excluding Moon) for a given month. Detects 22 aspect types. 5 major (conjunction, opposition, trine, square, sextile) and 17 minor (vigintile, semi-sextile, undecile, semi-quintile, novile, semi-square, septile, quintile, binovile, centile, biseptile, tredecile, sesqui-square, bi-quintile, quincunx, triseptile, quadranovile). Returns exact date and time of closest approach using ternary search refinement. Uses degree-based aspect methodology on sidereal positions (Lahiri ayanamsa). Omit year and month to get the month in progress, so a published aspect calendar stays current without a redeploy. For Moon-specific aspects, use the /aspects/lunar endpoint. Essential for transit timing, muhurta selection, and monthly astrological forecasting. Monthly planetary aspects API, graha drishti calendar, mutual aspect ephemeris, minor aspects.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly analysis (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12). Defaults to the current month (UTC)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}}}}}},"responses":{"200":{"description":"Monthly planetary aspect events","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the aspect analysis. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":2,"description":"Month of the aspect analysis. Echoes the month that was requested, or the current UTC month when it was omitted."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in hours that the event dates and times are reported in. Echoes the requested timezone."},"events":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Mars","description":"First planet forming the aspect. One of the Navagraha, Sun through Ketu. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Marte","description":"First planet name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet1 exactly."},"planet2":{"type":"string","example":"Venus","description":"Second planet forming the aspect. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Venus","description":"Second planet name in the requested language, for display. Present only when lang is set to a language other than English."},"aspect":{"type":"string","example":"conjunction","description":"Aspect type. major: conjunction (0 deg), opposition (180 deg), trine (120 deg), square (90 deg), sextile (60 deg). Minor: vigintile (18 deg), semi-sextile (30 deg), undecile (32.73 deg), semi-quintile (36 deg), novile (40 deg), semi-square (45 deg), septile (51.43 deg), quintile (72 deg), binovile (80 deg), centile (100 deg), biseptile (102.86 deg), tredecile (108 deg), sesqui-square (135 deg), bi-quintile (144 deg), quincunx (150 deg), triseptile (154.29 deg), quadranovile (160 deg)."},"date":{"type":"string","example":"2026-02-15","description":"Date when the aspect is closest to exact (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"14:32","description":"Time when the aspect is closest to exact (HH:MM, 24-hour). Adjusted to requested timezone."},"datetime":{"type":"string","example":"2026-02-15T14:32:00","description":"Full datetime when aspect is closest to exact. Adjusted to requested timezone."},"orb":{"type":"number","example":0.45,"description":"Angular distance from exact aspect in degrees at closest approach. Smaller orb indicates a more powerful aspect."},"distance":{"type":"number","example":120.45,"description":"Actual angular distance between the two planets in degrees at closest approach."},"planet1Longitude":{"type":"number","example":285.67,"description":"Sidereal longitude of the first planet at time of aspect (Lahiri ayanamsa)."},"planet2Longitude":{"type":"number","example":285.22,"description":"Sidereal longitude of the second planet at time of aspect."}},"required":["planet1","planet2","aspect","date","time","datetime","orb","distance","planet1Longitude","planet2Longitude"]},"description":"All planetary aspect events detected during the month, sorted chronologically by closest approach date."}},"required":["year","month","timezone","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/aspects/lunar":{"post":{"operationId":"getLunarAspects","tags":["Vedic Astrology"],"summary":"Monthly Lunar Aspects - Moon aspect events with all planets for a month","description":"Track all lunar aspect events for a given month including major and minor aspects. The Moon traverses approximately 13 degrees per day, forming 22 aspect types with each planet. 5 major (conjunction, opposition, trine, square, sextile) and 17 minor (vigintile, semi-sextile, undecile, semi-quintile, novile, semi-square, septile, quintile, binovile, centile, biseptile, tredecile, sesqui-square, bi-quintile, quincunx, triseptile, quadranovile). Returns exact date and time of each Moon aspect event with ternary search refinement to the minute. Omit year and month to get the month in progress, so a published lunar calendar stays current without a redeploy. Essential for muhurta selection, daily panchang analysis, and chandra gochar predictions. Monthly lunar aspects API, Moon transit calendar, chandra drishti ephemeris, minor lunar aspects.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly analysis (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12). Defaults to the current month (UTC)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}}}}}},"responses":{"200":{"description":"Monthly lunar aspect events","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the lunar aspect analysis. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":2,"description":"Month of the lunar aspect analysis. Echoes the month that was requested, or the current UTC month when it was omitted."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in hours that the event dates and times are reported in. Echoes the requested timezone."},"events":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Planet that the Moon forms an aspect with. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Júpiter","description":"Planet name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet exactly."},"aspect":{"type":"string","example":"trine","description":"Aspect type. major: conjunction, opposition, trine, square, sextile. Minor: vigintile, semi-sextile, undecile, semi-quintile, novile, semi-square, septile, quintile, binovile, centile, biseptile, tredecile, sesqui-square, bi-quintile, quincunx, triseptile, quadranovile."},"date":{"type":"string","example":"2026-02-10","description":"Date of closest approach for this lunar aspect (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"14:32","description":"Time of closest approach for this lunar aspect (HH:MM, 24-hour). Adjusted to requested timezone."},"datetime":{"type":"string","example":"2026-02-10T14:32:00","description":"Full datetime of closest approach. Adjusted to requested timezone."},"orb":{"type":"number","example":0.32,"description":"Angular distance from exact lunar aspect in degrees. Smaller orb = stronger Moon influence."},"distance":{"type":"number","example":120.32,"description":"Actual angular distance between Moon and the aspected planet in degrees."},"moonLongitude":{"type":"number","example":154.82,"description":"Sidereal longitude of the Moon at the time of aspect (Lahiri ayanamsa)."},"planetLongitude":{"type":"number","example":274.67,"description":"Sidereal longitude of the aspected planet at the time of aspect."}},"required":["planet","aspect","date","time","datetime","orb","distance","moonLongitude","planetLongitude"]},"description":"All Moon aspect events during the month, sorted chronologically. Moon completes one full cycle in approximately 27 days."}},"required":["year","month","timezone","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/transit":{"post":{"operationId":"calculateTransit","tags":["Vedic Astrology"],"summary":"Transit Analysis - Compare current planets to natal chart (Gochar)","description":"Analyze planetary transits (Gochar) over natal chart positions. Each transiting graha comes back with TWO whole-sign house numbers, because the two readings answer different questions: houseFromMoon is counted from the natal Moon sign (Janma Rashi), which is the reference classical Gochara uses, and natalHouse is counted from the Lagna. Also returns graha drishti onto the natal grahas (7th for every graha, plus Mars 4th and 8th, Jupiter 5th and 9th, Saturn 3rd and 10th), degree-based angular aspects with orbs, the Gochara Kaksha verdict, and highlighted transits from the slow-moving grahas (Jupiter, Saturn, Rahu, Ketu). Essential for timing predictions, event forecasting, and understanding current planetary influences. Transit analysis API, gochar calculator, vedic transit predictions, Chandra Lagna gochara, graha drishti.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format. Used to calculate the natal chart against which transits are analyzed."},"birthTime":{"type":"string","format":"time","example":"10:12:00","description":"Birth time in HH:MM:SS format (24-hour). Critical for accurate natal Lagna and Placidus house cusps which determine transit house placements."},"transitDate":{"type":"string","format":"date","example":"2026-02-03","description":"Transit date to analyze in YYYY-MM-DD format. Planetary positions on this date are overlaid on the natal chart."},"transitTime":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS format (24-hour). Affects fast-moving planets like Moon. Defaults to noon."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees. Determines Placidus house cusps for natal chart house assignments."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees. Affects local sidereal time for Lagna and house calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}},"required":["birthDate","birthTime","transitDate","latitude","longitude"]}}}},"responses":{"200":{"description":"Transit analysis calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"frame":{"type":"object","properties":{"ayanamsa":{"type":"string","example":"lahiri","description":"Sidereal frame this chart was cast in, echoing the ayanamsa request field. \"lahiri\" when the field was omitted."},"ayanamsaDegrees":{"type":"number","example":24.2247,"description":"Degrees actually subtracted from every tropical longitude to produce this chart, read at the birth instant. Subtract it back to recover the tropical positions, or compare it against your reference software to confirm you are in the same frame before chasing a placement difference."}},"required":["ayanamsa","ayanamsaDegrees"],"description":"The zodiac frame every longitude in this response was computed in, so a cached or forwarded payload is self describing. Sidereal requests report the Lahiri ayanamsa, read at the birth instant; the transit positions use the same named frame resolved at their own instant, which moves by about 50 arcseconds a year. A tropical request reports \"tropical\" with 0 degrees subtracted, which is the one case a Vedic table can otherwise be rendered in the wrong zodiac with nothing on screen saying so."},"birthDatetime":{"type":"string","example":"1990-07-04T10:12:00","description":"Birth datetime used for the natal chart, echoed as the local civil date and time supplied in the request (YYYY-MM-DDTHH:MM:SS). Combine it with the timezone field to recover the UTC instant."},"transitDatetime":{"type":"string","example":"2026-02-03T12:00:00","description":"Transit datetime being analyzed, echoed as the local civil date and time supplied in the request (YYYY-MM-DDTHH:MM:SS). Gochar positions are computed for this moment and overlaid on the natal chart."},"natalPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Graha name, Sun through Ketu. The Lagna is not one of these entries; it is a house frame rather than a body, and the natal house numbers on every entry are counted from it."},"longitude":{"type":"number","example":102.34,"description":"Sidereal longitude in degrees (0-360) using Lahiri ayanamsa."},"sign":{"type":"string","example":"Cancer","description":"Vedic zodiac sign (rashi) the planet occupies in the birth chart."},"house":{"type":"number","example":4,"description":"Bhava (house) number 1-12, counted whole-sign from the Lagna (house 1 is the Lagna rashi)."}},"required":["name","longitude","sign","house"]},"description":"All 9 planetary positions from the natal (birth) chart."},"transitingPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Saturn","description":"Transiting planet name."},"longitude":{"type":"number","example":340.15,"description":"Current sidereal longitude of the transiting planet."},"sign":{"type":"string","example":"Pisces","description":"Current zodiac sign of the transiting planet."},"natalHouse":{"type":"number","example":10,"description":"Which natal house (whole-sign bhava counted from the Lagna) this graha is currently transiting through. This is the Lagna reading of the transit, which is what a transit chart drawn over the birth chart shows. For the house classical Gochara is judged from, read houseFromMoon instead."},"houseFromMoon":{"type":"number","example":7,"description":"Which house this graha is transiting counted from the natal Moon sign (Janma Rashi), 1-12 whole-sign and counted inclusively, so the Moon sign itself is 1. This is the number classical Gochara is reckoned in: Phaladeepika chapter 26 opens by saying that of all the Lagnas only the Moon Lagna matters for transit results, and the Vedha and Ashtakavarga transit rules are counted from the Moon throughout. The reference sign is the sign of the Moon entry in natalPlanets, so a client can label the column without a second request."},"aspectsToNatal":{"type":"array","items":{"type":"object","properties":{"natalPlanet":{"type":"string","example":"Moon","description":"Natal planet being aspected by this transiting planet."},"aspectType":{"type":"string","example":"square","description":"Degree-based angular aspect between the two longitudes: conjunction, opposition, trine, square, or sextile. This is the Western aspect vocabulary and it is offered for charts read that way. Parashari jyotish has no sextile, square or trine, so for the Vedic reading use drishtiToNatal, which reports graha drishti by house count."},"orb":{"type":"number","example":2.45,"description":"Angular distance from exact aspect in degrees. Smaller orb = stronger influence."}},"required":["natalPlanet","aspectType","orb"]},"description":"Degree-based angular aspects between this transiting graha and the natal grahas. Western vocabulary, kept for callers who read a chart that way; drishtiToNatal is the Vedic answer to the same question."},"drishtiToNatal":{"type":"array","items":{"type":"object","properties":{"natalPlanet":{"type":"string","example":"Sun","description":"Natal graha receiving the drishti from this transiting graha."},"aspectType":{"type":"string","enum":["conjunction","7th","4th","8th","5th","9th","3rd","10th"],"example":"3rd","description":"Which house the drishti falls on, counted whole-sign and inclusively from the transiting graha. Every graha aspects the 7th; Mars adds the 4th and 8th, Jupiter the 5th and 9th, Saturn the 3rd and 10th. Same vocabulary the /aspects endpoint returns, so the two can be compared directly."},"strength":{"type":"number","example":100,"description":"Drishti strength as a percentage. Full and special aspects are 100; the partial quarter, half and three-quarter sights are not reported."},"orb":{"type":"number","example":2.5,"description":"Gap between the two degrees-in-sign, in degrees. Graha drishti is whole-sign and does not depend on this, so read it as how exact the sight is inside the pair of rashis rather than as a condition for the aspect."}},"required":["natalPlanet","aspectType","strength","orb"]},"description":"Graha drishti cast by this transiting graha onto the natal grahas, the Vedic reading of transit-to-natal aspects. Rahu and Ketu cast none. Empty when this graha reaches no occupied natal sign."},"kaksha":{"type":"object","properties":{"number":{"type":"number","example":3,"description":"Kaksha number 1-8 within the current sign. Each sign divides into eight kakshas of 3 degrees 45 minutes, crossed in order, so this is how far through the sign the graha has travelled."},"lord":{"type":"string","example":"Mars","description":"Graha ruling this kaksha. The eight lords run Saturn, Jupiter, Mars, Sun, Venus, Mercury, Moon, Lagna from the start of every sign, ordered by how long each takes to cross a sign."},"startDegree":{"type":"number","example":7.5,"description":"Degree within the sign where this kaksha begins (0, 3.75, 7.5 and so on)."},"endDegree":{"type":"number","example":11.25,"description":"Degree within the sign where this kaksha ends."},"bindu":{"type":["boolean","null"],"example":true,"description":"Whether this kaksha lord gave the transiting graha a bindu in the sign being transited, which is the Gochara Kaksha verdict: true reads as a favourable stretch of the transit, false as an unfavourable one. Null means the question does not apply rather than that the answer is no, because Rahu and Ketu have no Bhinnashtakavarga to read. Never render null as unfavourable."},"binduCount":{"type":["number","null"],"example":5,"description":"Bindus the transiting graha holds in this whole sign, 0-8, or null for Rahu and Ketu. Context for the verdict, since the same kaksha reads differently in a sign worth 7 than in one worth 1."}},"required":["number","lord","startDegree","endDegree","bindu","binduCount"],"description":"Gochara Kaksha: the ashtakavarga-qualified reading of this transit. The sign says where a graha is, this says whether the exact stretch it currently occupies is one its own Bhinnashtakavarga supports, which is the classical way of refining a transit verdict from sign-level to under four degrees."}},"required":["name","longitude","sign","natalHouse","houseFromMoon","aspectsToNatal","drishtiToNatal","kaksha"]},"description":"Current planetary positions overlaid on the natal chart with house placements, aspects, and the Gochara Kaksha verdict for each graha."},"keyTransits":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Saturn","description":"Slow-moving planet (Jupiter, Saturn, Rahu, Ketu) forming a significant transit."},"description":{"type":"string","example":"Saturn transiting Pisces (natal house 10, 4 from the Moon)","description":"Human-readable transit summary, naming the rashi being transited and both house readings: from the Lagna, then from the natal Moon."},"natalHouse":{"type":"number","example":10,"description":"Natal house being transited by this slow graha, counted whole-sign from the Lagna. Mirrors natalHouse on the matching transitingPlanets entry."},"houseFromMoon":{"type":"number","example":4,"description":"House being transited by this slow graha counted from the natal Moon sign (Janma Rashi), the classical Gochara reference. Mirrors houseFromMoon on the matching transitingPlanets entry."},"aspects":{"type":"array","items":{"type":"string"},"example":["conjunction to natal Sun (orb 4.64°)"],"description":"Notable degree-based angular aspects to natal planets from this slow-moving transiting planet, in Western vocabulary."},"drishti":{"type":"array","items":{"type":"string"},"example":["3rd drishti to natal Sun"],"description":"Graha drishti this slow-moving transiting graha casts on the natal grahas, the Vedic reading. Empty for Rahu and Ketu, which cast none."}},"required":["planet","description","natalHouse","houseFromMoon","aspects","drishti"]},"description":"Highlighted transits from slow-moving planets (Jupiter, Saturn, Rahu, Ketu), most impactful for Gochar analysis."}},"required":["frame","birthDatetime","transitDatetime","natalPlanets","transitingPlanets","keyTransits"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/transit/monthly":{"post":{"operationId":"getMonthlyTransits","tags":["Vedic Astrology"],"summary":"Monthly Transit - Planetary sign changes for an entire month","description":"Get all planetary sign (rashi) changes for a given month. Shows when each planet transitions from one zodiac sign to another. Covers all 9 Vedic planets: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu. Includes starting positions at the beginning of the month. Omit year and month to get the month in progress, so a published gochar calendar stays current without a redeploy. Essential for transit prediction, monthly horoscope generation, and muhurta planning. Monthly planetary transit API, gochar calendar, rashi parivartan dates.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly transit analysis (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for transit analysis. Defaults to the current month (UTC)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}}}}}},"responses":{"200":{"description":"Monthly transit data calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the monthly transit analysis. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":2,"description":"Month of the monthly transit analysis. Echoes the month that was requested, or the current UTC month when it was omitted."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in hours that the event dates and times are reported in. Echoes the requested timezone."},"startingPositions":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Planet (graha) name. One of the 9 Navagraha used in Vedic transit (Gochar) analysis. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Planet name in the requested language, for display. Present only when lang is set to a language other than English."},"sign":{"type":"string","example":"Capricorn","description":"Zodiac sign (rashi) the planet occupies at the start of the month. Always English. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Capricornio","description":"Zodiac sign name in the requested language, for display. Present only when lang is set to a language other than English."},"longitude":{"type":"number","example":286.45,"description":"Sidereal longitude at the start of the month."}},"required":["planet","sign","longitude"]},"description":"Planetary positions at the beginning of the month (day 1, 00:00 UTC)."},"transitEvents":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Planet that changes sign (rashi) during this month. One of the Navagraha: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Marte","description":"Planet name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet exactly."},"fromSign":{"type":"string","example":"Gemini","description":"Zodiac sign the planet is leaving (previous rashi). Always English. Use fromSignLocalized for anything a reader sees."},"fromSignLocalized":{"type":"string","example":"Géminis","description":"Name of the sign being left, in the requested language, for display. Present only when lang is set to a language other than English."},"toSign":{"type":"string","example":"Cancer","description":"Zodiac sign the planet is entering (new rashi transit). Always English. Use toSignLocalized for anything a reader sees."},"toSignLocalized":{"type":"string","example":"Cáncer","description":"Name of the sign being entered, in the requested language, for display. Present only when lang is set to a language other than English."},"date":{"type":"string","example":"2026-02-14","description":"Date of the sign change (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"14:32","description":"Time of the sign change (HH:MM, 24-hour). Adjusted to requested timezone. Precise to ~1 minute via binary search."},"datetime":{"type":"string","example":"2026-02-14T14:32:00","description":"Full datetime of the sign change. Adjusted to requested timezone."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in retrograde motion (vakri) at the time of sign change. A retrograde ingress means the planet is moving backward into the previous sign, which carries different astrological significance than a direct (forward) ingress. Rahu and Ketu are always retrograde."}},"required":["planet","fromSign","toSign","date","time","datetime","isRetrograde"]},"description":"All sign change events during the month, sorted chronologically. Moon changes sign roughly every 2.25 days, Sun once a month, slow planets less frequently."}},"required":["year","month","timezone","startingPositions","transitEvents"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/parallels":{"post":{"operationId":"calculateParallels","tags":["Vedic Astrology"],"summary":"Declination Parallels - Planets at same or opposite declination","description":"Calculate planetary declinations and find parallels (same declination) and contraparallels (opposite declination). Parallels are considered equivalent to conjunctions in strength, contraparallels to oppositions. Returns declination for each planet and all parallel/contraparallel aspects. Declination parallels API, planetary declination calculator, contraparallel aspects.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-02-03","description":"Date in YYYY-MM-DD format. Planetary declinations are calculated for this date to find parallel and contraparallel aspects."},"time":{"type":"string","format":"time","example":"12:00:00","description":"Time in HH:MM:SS format (24-hour). Exact time affects declination values, especially for the fast-moving Moon."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":17.385044,"description":"Observer latitude in decimal degrees. Used for topocentric declination corrections."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":78.486671,"description":"Observer longitude in decimal degrees. Affects local time context for declination calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":5.5,"description":"Timezone offset from UTC in hours. Defaults to 5.5 (IST).","example":5.5},"orb":{"type":"number","minimum":0.5,"maximum":3,"default":1.5,"example":1.5,"description":"Orb in degrees for parallel/contraparallel detection. Defaults to 1.5°."}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Declination parallels calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"datetime":{"type":"string","example":"1990-07-04T10:12:00","description":"Datetime used for the declination calculation, echoed as the local civil date and time supplied in the request (YYYY-MM-DDTHH:MM:SS). The timezone field of the request is what converts it to the instant the declinations are computed for."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun through Saturn, the 7 visible planets)."},"declination":{"type":"number","example":-17.23,"description":"Celestial declination in degrees. Positive = north of celestial equator, negative = south."},"rightAscension":{"type":"number","example":285.47,"description":"Right ascension in degrees (0-360) along the celestial equator."}},"required":["name","declination","rightAscension"]},"description":"Declination and right ascension for each planet at the given moment."},"parallels":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"First planet in the parallel/contraparallel pair."},"planet2":{"type":"string","example":"Mars","description":"Second planet in the pair."},"type":{"type":"string","enum":["parallel","contraparallel"],"example":"parallel","description":"Parallel = same declination (acts like conjunction). Contraparallel = opposite declination (acts like opposition)."},"orb":{"type":"number","example":0.85,"description":"Angular difference from exact parallel/contraparallel in degrees. Smaller = stronger."},"dec1":{"type":"number","example":14.23,"description":"Declination of the first planet in degrees."},"dec2":{"type":"number","example":13.38,"description":"Declination of the second planet in degrees."}},"required":["planet1","planet2","type","orb","dec1","dec2"]},"description":"All parallel and contraparallel aspects found within the specified orb. Parallels are powerful hidden aspects often overlooked in standard chart analysis."}},"required":["datetime","planets","parallels"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/parallels/monthly":{"post":{"operationId":"getMonthlyParallels","tags":["Vedic Astrology"],"summary":"Monthly Declination Parallels - Parallel and contraparallel events for a month","description":"Find all declination parallel and contraparallel events between the 7 visible planets for a given month. Parallels occur when two planets share the same celestial declination (equivalent to conjunction in strength). Contraparallels occur at opposite declinations (equivalent to opposition). Scanned daily at noon UTC. Omit year and month to get the month in progress, so a published parallel calendar stays current without a redeploy. Essential for advanced transit analysis and hidden aspect discovery. Monthly declination parallels API, planetary parallel ephemeris, contraparallel event calendar.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly parallel analysis (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for parallel analysis. Defaults to the current month (UTC)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5}}}}}},"responses":{"200":{"description":"Monthly parallel events","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the parallel analysis. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":2,"description":"Month of the parallel analysis. Echoes the month that was requested, or the current UTC month when it was omitted."},"events":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"First planet in the parallel or contraparallel pair. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Venus","description":"First planet name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet1 exactly."},"planet2":{"type":"string","example":"Mars","description":"Second planet in the pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Marte","description":"Second planet name in the requested language, for display. Present only when lang is set to a language other than English."},"type":{"type":"string","enum":["parallel","contraparallel"],"example":"parallel","description":"Parallel = same declination (acts like conjunction in strength). Contraparallel = opposite declination (acts like opposition)."},"date":{"type":"string","example":"2026-02-12","description":"Date of closest declination match (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"09:15","description":"Time of closest declination match (HH:MM, 24-hour). Adjusted to requested timezone."},"datetime":{"type":"string","example":"2026-02-12T09:15:00","description":"Full datetime of closest declination match. Adjusted to requested timezone."},"orb":{"type":"number","example":0.45,"description":"Declination difference from exact parallel/contraparallel in degrees. Smaller = stronger."},"dec1":{"type":"number","example":14.23,"description":"Declination of the first planet in degrees."},"dec2":{"type":"number","example":13.78,"description":"Declination of the second planet in degrees."}},"required":["planet1","planet2","type","date","time","datetime","orb","dec1","dec2"]},"description":"All parallel and contraparallel events detected during the month, sorted chronologically."}},"required":["year","month","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/ecliptic-crossings":{"post":{"operationId":"getEclipticCrossings","tags":["Vedic Astrology"],"summary":"Ecliptic Crossings - When planets cross the ecliptic plane","description":"Find all ecliptic plane crossings for visible planets during a given year. An ecliptic crossing occurs when a planetary celestial latitude passes through 0 degrees, crossing from one side of the ecliptic to the other. Ascending crossings (south to north) correspond to the ascending node, descending crossings (north to south) to the descending node. Moon crosses ~2 times per month, outer planets cross less frequently. Returns exact date, time, direction, sidereal longitude, and zodiac sign. Ecliptic crossing API, planetary node crossing, ascending descending node ephemeris.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year to scan for ecliptic crossings (1900-2100)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5},"coordinateSystem":{"type":"string","enum":["sidereal","tropical"],"default":"sidereal","example":"sidereal","description":"Coordinate system for longitude output. \"sidereal\" (Nirayana) uses Lahiri ayanamsa - standard for Vedic astrology. \"tropical\" (Sayana) uses raw ecliptic longitude matching Western astrology. Defaults to \"sidereal\"."}},"required":["year"]}}}},"responses":{"200":{"description":"Ecliptic crossing events for the year","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year scanned for ecliptic crossings."},"timezone":{"type":"number","example":5.5,"description":"Timezone offset from UTC in hours that the event dates and times are reported in. Echoes the requested timezone."},"events":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Planet crossing the ecliptic plane. Sun is excluded (always on the ecliptic by definition)."},"date":{"type":"string","example":"2026-03-15","description":"Date of the ecliptic crossing (YYYY-MM-DD). Adjusted to requested timezone."},"time":{"type":"string","example":"08:42","description":"Time of the ecliptic crossing (HH:MM, 24-hour). Adjusted to requested timezone."},"datetime":{"type":"string","example":"2026-03-15T08:42:00","description":"Full datetime of the ecliptic crossing. Adjusted to requested timezone."},"direction":{"type":"string","enum":["ascending","descending"],"example":"ascending","description":"Ascending = planet moves from south to north of the ecliptic. Descending = north to south."},"longitude":{"type":"number","example":345.67,"description":"Sidereal longitude of the planet at the moment of crossing (Lahiri ayanamsa)."},"sign":{"type":"string","example":"Pisces","description":"Vedic zodiac sign (rashi) the planet occupies at the crossing."}},"required":["planet","date","time","datetime","direction","longitude","sign"]},"description":"All ecliptic crossing events for visible planets during the year, sorted chronologically."}},"required":["year","timezone","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/rashis":{"get":{"operationId":"listRashis","tags":["Vedic Astrology"],"summary":"List all 12 Rashis - Vedic Zodiac Signs Reference","description":"Get the complete list of 12 rashis (zodiac signs) in Vedic astrology. Returns Sanskrit names, Western equivalents, sidereal date ranges, symbols, governing Adityas, and personality characteristics for each rashi. Reference data for Mesha through Meen. Essential for zodiac sign lookup tables, astrology apps, and rashi-based UI components.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Array of all 12 Vedic rashis (Mesha through Meen) with Sanskrit names, Western equivalents, sidereal date ranges, symbols, governing Adityas, and personality characteristics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RashiListResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/rashis/{id}":{"get":{"operationId":"getRashi","tags":["Vedic Astrology"],"summary":"Get Rashi by ID - Vedic Zodiac Sign Detail","description":"Get detailed information for a single rashi (zodiac sign) by its Vedic ID slug. Returns Sanskrit name, Western equivalent, sidereal date range, symbol, governing Aditya, and personality characteristics.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["mesha","vrishabha","mithun","karka","simha","kanya","tula","vrischika","dhanu","makar","kumbha","meen"],"example":"mesha","description":"Rashi ID slug. One of: mesha, vrishabha, mithun, karka, simha, kanya, tula, vrischika, dhanu, makar, kumbha, meen."},"required":true,"description":"Rashi ID slug. One of: mesha, vrishabha, mithun, karka, simha, kanya, tula, vrischika, dhanu, makar, kumbha, meen.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Single rashi with Sanskrit name, Western equivalent, sidereal date range, symbol, governing Aditya, and personality characteristics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RashiResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Rashi not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/nakshatras":{"get":{"operationId":"listNakshatras","tags":["Vedic Astrology"],"summary":"List all 27 Nakshatras - Lunar Mansions Reference","description":"Get the complete list of 27 nakshatras (lunar mansions) in Vedic astrology. Returns names, zodiac ranges, ruling planets, presiding deities, symbols, personality characteristics, and traditional remedies (mantras, gemstones, rituals) for each nakshatra from Ashwini to Revati. Essential for nakshatra lookup tables, dasha period calculations, muhurta selection, and astrology app reference data.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Array of all 27 nakshatras (Ashwini through Revati) with zodiac ranges, ruling planets, deities, symbols, personality characteristics, and traditional remedies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NakshatraListResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/nakshatras/{id}":{"get":{"operationId":"getNakshatra","tags":["Vedic Astrology"],"summary":"Get Nakshatra by ID - Lunar Mansion Detail","description":"Get detailed information for a single nakshatra (lunar mansion) by its ID slug. Returns name, zodiac range, ruling planet, presiding deity, symbol, personality characteristics, and traditional remedies including mantras, gemstones, and rituals.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["ashwini","bharani","krittika","rohini","mrigashira","ardra","punarvasu","pushya","ashlesha","magha","purva-phalguni","uttara-phalguni","hasta","chitra","swati","vishakha","anuradha","jyeshtha","moola","purva-ashadha","uttara-ashadha","shravana","dhanishta","shatabhisha","purva-bhadrapada","uttara-bhadrapada","revati"],"example":"ashwini","description":"Nakshatra ID slug. Examples: ashwini, bharani, krittika, rohini, mrigashira, ardra, punarvasu, pushya, ashlesha, magha, etc."},"required":true,"description":"Nakshatra ID slug. Examples: ashwini, bharani, krittika, rohini, mrigashira, ardra, punarvasu, pushya, ashlesha, magha, etc.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Single nakshatra with zodiac range, ruling planet, presiding deity, symbol, personality characteristics, and traditional remedies (mantras, gemstones, rituals).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NakshatraResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Nakshatra not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/upagraha":{"post":{"operationId":"getUpagrahaPositions","tags":["Vedic Astrology"],"summary":"Get upagraha (sub-planet) positions - Upagraha Calculator API","description":"Calculate all 11 Vedic upagraha (sub-planet) positions per Brihat Parashara Hora Shastra (BPHS). Returns 6 time-based upagrahas (Gulika, Mandi, Kala, Mrityu, Ardhaprahara, Yamaghantaka) derived from the 8-part day/night division, plus 5 Sun-longitude-based upagrahas (Dhuma, Vyatipata, Parivesha, Indra Chapa, Upaketu). Essential for complete kundli analysis, dosha assessment, and advanced chart interpretation. Upagraha calculator API, Gulika Mandi position, sub-planet Vedic astrology.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpagrahaRequest"}}}},"responses":{"200":{"description":"All 11 upagraha positions with rashi, nakshatra, and pada details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpagrahaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/ashtakavarga":{"post":{"operationId":"calculateAshtakavarga","tags":["Vedic Astrology"],"summary":"Get Ashtakavarga (planetary strength) analysis - Ashtakavarga Calculator API","description":"Calculate complete Ashtakavarga analysis per Brihat Parashara Hora Shastra (BPHS). Returns Bhinnashtakavarga (BAV), Sarvashtakavarga (SAV, total 337), Reduced Ashtakavarga (Trikona + Ekadipati Shodhana per Ch. 67-68), and Shodhya Pinda planetary strength (Rashi Pinda + Graha Pinda per Ch. 69). Essential for transit prediction timing, house strength analysis, dasha result evaluation, and planetary strength comparison. Ashtakavarga calculator API, bindu rekha points, Shodhya Pinda, Vedic astrology.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AshtakavargaRequest"}}}},"responses":{"200":{"description":"Complete Ashtakavarga with Bhinnashtakavarga, Sarvashtakavarga (337-point), Reduced Ashtakavarga (Trikona + Ekadipati Shodhana), and Shodhya Pinda planetary strength.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AshtakavargaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/shadbala":{"post":{"operationId":"calculateShadbala","tags":["Vedic Astrology"],"summary":"Get Shadbala (six-fold planetary strength) analysis - Shadbala Calculator API","description":"Calculate complete Shadbala (six-fold planetary strength) per Brihat Parashara Hora Shastra (BPHS) and BV Raman Graha and Bhava Balas. Returns all 6 strength components (Sthana Bala, Dig Bala, Kala Bala, Chesta Bala, Naisargika Bala, Drik Bala) plus Ishta Phala, Kashta Phala, strength ratio, and relative ranking for all 7 classical planets. Essential for evaluating planetary strength in Vedic birth chart analysis, dasha prediction, transit interpretation, and yoga assessment. Shadbala calculator API, planetary strength Vedic astrology, graha bala, Ishta Kashta Phala.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShadbalaRequest"}}}},"responses":{"200":{"description":"Complete Shadbala with 6 strength components, Ishta/Kashta Phala, strength ratios, and relative ranking for all 7 planets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShadbalaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/avasthas":{"get":{"operationId":"listAvasthas","tags":["Vedic Astrology"],"summary":"List all 17 avastha states - Planetary State Reference","description":"Reference list of every avastha (planetary state) across the three classical systems: the five Baladi age states, the three Jagradadi waking states, and the nine Deeptadi dispositional states. Each carries a short label and what the state means for the results the graha can deliver. Use it to turn the bare state names a birth chart returns into readable output, filtered by system if you only need one. Avastha meaning API, Baladi avastha, Jagradadi, Deeptadi, planetary state Vedic astrology.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["baladi","jagradadi","deeptadi"],"example":"deeptadi","description":"Return only the states of one system: \"baladi\" (5), \"jagradadi\" (3) or \"deeptadi\" (9). Omit for all 17."},"required":false,"description":"Return only the states of one system: \"baladi\" (5), \"jagradadi\" (3) or \"deeptadi\" (9). Omit for all 17.","name":"system","in":"query"}],"responses":{"200":{"description":"Avastha states with their labels and interpretations, in system order.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"jagrat","description":"Unique slug for the avastha state. It is the lowercased form of the state name the birth chart returns, so a chart value maps straight onto this record."},"name":{"type":"string","example":"Jagrat","description":"Sanskrit name of the state, exactly as it appears in the `awastha`, `jagradadi` or `deeptadi` field of a birth chart."},"system":{"type":"string","enum":["baladi","jagradadi","deeptadi"],"example":"jagradadi","description":"Which avastha system the state belongs to, and therefore which birth-chart field it appears in. \"baladi\" is the five-fold age state set by degree within the sign and appears in `awastha`. \"jagradadi\" is the three-fold waking state set by sign dignity. \"deeptadi\" is the nine-fold dispositional state. Baladi applies to every body; the other two apply to the seven classical grahas only."},"meaning":{"type":"string","example":"Awake","description":"Short label for the state, sized for a table cell beside the graha."},"interpretation":{"type":"string","example":"In its own sign or exaltation the graha is fully alert and gives its results without hindrance.","description":"What the state means for the results the graha delivers, which is the whole purpose of reading an avastha: the chart says where a graha is, the avastha says how much of its promise it can keep."}},"required":["id","name","system","meaning","interpretation"]}}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/avasthas/{id}":{"get":{"operationId":"getAvastha","tags":["Vedic Astrology"],"summary":"Get avastha by ID - Planetary State Detail","description":"Look up a single avastha state by its slug, which is the lowercased state name a birth chart returns in `awastha`, `jagradadi` or `deeptadi`. Returns the system it belongs to, a short label, and what the state means for the results the graha delivers.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["bala","kumara","yuva","vriddha","mrita","jagrat","swapna","sushupti","dipta","svastha","pramudita","shanta","dina","duhkhita","vikala","khala","kopa"],"example":"dipta","description":"Avastha slug. Baladi: bala, kumara, yuva, vriddha, mrita. Jagradadi: jagrat, swapna, sushupti. Deeptadi: dipta, svastha, pramudita, shanta, dina, duhkhita, vikala, khala, kopa."},"required":true,"description":"Avastha slug. Baladi: bala, kumara, yuva, vriddha, mrita. Jagradadi: jagrat, swapna, sushupti. Deeptadi: dipta, svastha, pramudita, shanta, dina, duhkhita, vikala, khala, kopa.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The avastha state with its system, label and interpretation.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"jagrat","description":"Unique slug for the avastha state. It is the lowercased form of the state name the birth chart returns, so a chart value maps straight onto this record."},"name":{"type":"string","example":"Jagrat","description":"Sanskrit name of the state, exactly as it appears in the `awastha`, `jagradadi` or `deeptadi` field of a birth chart."},"system":{"type":"string","enum":["baladi","jagradadi","deeptadi"],"example":"jagradadi","description":"Which avastha system the state belongs to, and therefore which birth-chart field it appears in. \"baladi\" is the five-fold age state set by degree within the sign and appears in `awastha`. \"jagradadi\" is the three-fold waking state set by sign dignity. \"deeptadi\" is the nine-fold dispositional state. Baladi applies to every body; the other two apply to the seven classical grahas only."},"meaning":{"type":"string","example":"Awake","description":"Short label for the state, sized for a table cell beside the graha."},"interpretation":{"type":"string","example":"In its own sign or exaltation the graha is fully alert and gives its results without hindrance.","description":"What the state means for the results the graha delivers, which is the whole purpose of reading an avastha: the chart says where a graha is, the avastha says how much of its promise it can keep."}},"required":["id","name","system","meaning","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No avastha state matches that slug.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/arudha":{"post":{"operationId":"calculateArudhaPadas","tags":["Vedic Astrology"],"summary":"Get the twelve Arudha padas - Arudha Lagna Calculator API","description":"Calculate the Arudha Lagna (AL) and all twelve Arudha padas of Jaimini astrology from birth details. An Arudha pada is the perceived or projected form of a bhava, so where the Lagna shows what a person is, the Arudha Lagna shows the image and status the world attaches to them. Returns each pada with the bhava lord and the count that produced it, the sign it lands in, its house from the Lagna, and a flag showing whether the classical exception moved it. Includes the Upapada (UL) read for marriage. Arudha Lagna calculator API, Jaimini pada, Upapada Lagna, Vedic astrology public image.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArudhaRequest"}}}},"responses":{"200":{"description":"All twelve Arudha padas with derivation detail, plus the Arudha Lagna and Upapada lifted to the top level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArudhaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/chara-karakas":{"post":{"operationId":"calculateCharaKarakas","tags":["Vedic Astrology"],"summary":"Get Chara Karakas including Atmakaraka - Jaimini Karaka Calculator API","description":"Calculate the Chara Karakas of Jaimini astrology from birth details: the movable significators assigned by ranking each graha on how far it has advanced into its sign. The highest becomes the Atmakaraka, the soul significator and the strongest influence in the chart, and the rest take the Amatya, Bhratri, Matri, Pitri, Putra, Gnati and Dara offices in descending order. Supports both the eight-karaka scheme, where Rahu is included with its degree reversed, and the seven-karaka scheme that excludes the nodes, because the two can name a different Atmakaraka for the same chart. Atmakaraka calculator API, Darakaraka, Jaimini chara karaka, Vedic astrology soul significator.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharaKarakaRequest"}}}},"responses":{"200":{"description":"Karaka offices in descending rank with the ranking degree for each, plus the Atmakaraka and Darakaraka lifted to the top level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharaKarakaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/bhava-bala":{"post":{"operationId":"calculateBhavaBala","tags":["Vedic Astrology"],"summary":"Get Bhava Bala (house strength) for all twelve houses - Bhava Bala Calculator API","description":"Calculate Bhava Bala (house strength) for all twelve bhavas per Brihat Parashara Hora Shastra (BPHS) and BV Raman Graha and Bhava Balas. Returns the three classical components (Bhavadhipati Bala from the house lord Shadbala, Bhava Digbala from the rashi class and direction, Bhava Drishti Bala from aspects on the bhava madhya) plus totals in virupas and rupas and a strength ranking. Bhavas are built on unequal Sripati mid-cusps, so a house near a sign boundary is measured where it actually falls. Shadbala measures which graha is strong, Bhava Bala measures which life area is strong, and reading both together is how a practitioner separates a strong planet in a weak house from a weak planet in a strong one. Bhava Bala calculator API, house strength Vedic astrology, bhava bala virupas, Bhavadhipati Bala, Bhava Digbala, Sripati bhava madhya.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BhavaBalaRequest"}}}},"responses":{"200":{"description":"Bhava Bala for all twelve houses with the three components, totals in virupas and rupas, ranking, and the localized house-theme legend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BhavaBalaResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/bhav-chalit":{"post":{"operationId":"calculateBhavChalit","tags":["Vedic Astrology"],"summary":"Get the Bhav Chalit (Chalit Kundli) cusp-based house chart - Bhav Chalit API","description":"Calculate the Bhav Chalit chart, also written Bhava Chalit or Chalit Kundli, placing every graha by unequal Sripati bhava cusps instead of by whole sign. The Rashi (D1) chart treats a whole sign as a house, so a graha a degree from a sign boundary is shown in a house it does not actually occupy; the Chalit chart resolves that by measuring from the bhava sandhis, which is why practitioners check it before reading house results, house lordship strength or transit effects. Returns the twelve bhava boundaries with their madhyas and spans, every graha in both frames, and a moved flag on the placements that differ. Bhav Chalit API, Chalit Kundli calculator, bhava chalit chart, Sripati house cusps, cusp based house chart Vedic astrology.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["general","finance"],"default":"general","example":"general","description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\"."},"required":false,"description":"Which signification vocabulary the houseThemes map returns. \"general\" gives the classical bhava significations (self, wealth, siblings, home, and so on). \"finance\" gives the money reading of the same twelve bhavas, so house 2 returns income and savings, 5 speculation and risk appetite, 8 sudden money and leverage, 11 gains and profits, and 12 expenses and capital outflow. Use \"finance\" for wealth, income, business and market timing questions in Krishnamurti Paddhati, where the significator house groups 2, 6, 10, 11 for earned income and 5, 8, 11 for speculation are read against a running dasha. Defaults to \"general\".","name":"focus","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BhavChalitRequest"}}}},"responses":{"200":{"description":"Bhav Chalit chart with the twelve Sripati bhavas, every graha in both frames, and the localized house-theme legend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BhavChalitResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/vedic-astrology/heliacal":{"post":{"operationId":"getHeliacalVisibility","tags":["Vedic Astrology"],"summary":"Heliacal rising and setting (udaya and asta) - Graha Asta Calculator API","description":"Calculate heliacal rising (udaya) and setting (asta) of the six visible grahas for any date and place, by the Surya Siddhanta rule. Returns whether each graha currently clears the solar glare, its separation from the Sun in classical degrees of time, and the dates its visibility last changed and next changes. This is the calculation behind Guru Asta and Shukra Asta, the periods classical muhurta withholds marriage and other auspicious ceremonies. Unlike a birth chart combustion flag it is location aware, because the angle the ecliptic makes with the local horizon decides how long a graha lingers after the Sun. Graha asta API, Guru Asta Shukra Asta dates, heliacal rising calculator, planetary combustion muhurta.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeliacalRequest"}}}},"responses":{"200":{"description":"Heliacal visibility and the surrounding udaya and asta events for each graha.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeliacalResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/forecast/timeline":{"post":{"operationId":"generateTimeline","tags":["Forecast"],"summary":"Cross-domain forecast timeline - Transits, ingresses, stations, dasha changes, critical days","description":"Build one time-ordered forecast for a single birth subject by merging upcoming events across three domains: western transit-to-natal aspects, sign ingresses, retrograde stations, eclipses, and new and full moons; biorhythm critical days; and vedic Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. The window is clamped to 90 days and events are capped and scored by significance. Built for what-is-coming dashboards, daily and weekly forecast feeds, and timing tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the forecast window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the forecast window in YYYY-MM-DD format. Defaults to startDate plus 30 days. The window is clamped to a maximum of 90 days from startDate."},"domains":{"type":"array","items":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days."},"example":["western","vedic","biorhythm"],"description":"Which forecast domains to include. Defaults to all three. Pass a subset to scope the timeline to one or two engines."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":0,"description":"Drop events scoring below this significance threshold from 0 to 100. Defaults to 0, keeping all events."},"domainWeights":{"type":"object","properties":{"western":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"vedic":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"biorhythm":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."}},"example":{"vedic":1.5,"biorhythm":0.5},"description":"Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Merged forecast timeline with time-ordered events across the requested domains","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"type":"number","example":-4,"description":"Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","eclipse","lunar-phase","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types."},"kind":{"type":"string","enum":["penumbral","partial","annular","total"],"example":"total","description":"For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types."},"obscuration":{"type":"number","example":0.966,"description":"For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types."},"phase":{"type":"string","enum":["new-moon","full-moon"],"example":"full-moon","description":"For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/forecast/transits":{"post":{"operationId":"forecastTransits","tags":["Forecast"],"summary":"Western astrology forecast - aspects, ingresses, stations, eclipses, moon phases","description":"Forecast the western astrology events for a single birth chart over a window up to 90 days: every transit-to-natal major aspect refined to its exact instant, every transiting planet sign ingress, every retrograde or direct station, every solar and lunar eclipse, and every New and Full Moon. Returns a time-ordered, significance-scored timeline. Built for astrology forecast feeds, transit alerts, and timing tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this transit forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the transit window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":0,"description":"Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Time-ordered western forecast events: aspects, ingresses, stations, eclipses, and moon phases","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"type":"number","example":-4,"description":"Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","eclipse","lunar-phase","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types."},"kind":{"type":"string","enum":["penumbral","partial","annular","total"],"example":"total","description":"For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types."},"obscuration":{"type":"number","example":0.966,"description":"For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types."},"phase":{"type":"string","enum":["new-moon","full-moon"],"example":"full-moon","description":"For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/forecast/significant-dates":{"post":{"operationId":"findSignificantDates","tags":["Forecast"],"summary":"Significant dates - High-significance cross-domain forecast highlights","description":"Return only the high-significance dates from the merged cross-domain forecast for a single birth subject: the rare outer-planet exact transit aspects, slow-planet sign ingresses, retrograde stations, and Vimshottari mahadasha and antardasha changes that mark genuine turning points. Defaults to a significance floor of 70 so the response is a short list of the most meaningful upcoming dates. Built for what-is-coming highlights, timing alerts, and at-a-glance forecast strips.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate."},"domains":{"type":"array","items":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days."},"example":["western","vedic","biorhythm"],"description":"Which forecast domains to consider before filtering by significance. Defaults to all three."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":70,"description":"Significance floor from 0 to 100 for what counts as a significant date. Defaults to 70."},"domainWeights":{"type":"object","properties":{"western":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"vedic":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"biorhythm":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."}},"example":{"vedic":1.5,"biorhythm":0.5},"description":"Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm."}},"required":["birthData"]}}}},"responses":{"200":{"description":"High-significance forecast events across the requested domains","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"type":"number","example":-4,"description":"Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","eclipse","lunar-phase","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types."},"kind":{"type":"string","enum":["penumbral","partial","annular","total"],"example":"total","description":"For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types."},"obscuration":{"type":"number","example":0.966,"description":"For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types."},"phase":{"type":"string","enum":["new-moon","full-moon"],"example":"full-moon","description":"For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/forecast/digest":{"post":{"operationId":"generateDigest","tags":["Forecast"],"summary":"Forecast digest - Pre-summarized next 24h, 7d, 30d, and 90d rollups","description":"Roll the cross-domain forecast for a single birth subject into four pre-summarized windows: the next 24 hours, 7 days, 30 days, and 90 days from the start date. Each window returns its event count, a per-domain count breakdown, a per-type count breakdown, and the top highest-significance events. Built for a glanceable what-is-coming strip so a caller can render the upcoming highlights without scanning the full event list.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this digest is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"Start anchor for every window in YYYY-MM-DD format. The next 24h, 7d, 30d, and 90d windows are measured forward from this date at 00:00:00 UTC. Defaults to today in UTC."},"domains":{"type":"array","items":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days."},"example":["western","vedic","biorhythm"],"description":"Which forecast domains to include before rolling up the windows. Defaults to all three."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":0,"description":"Drop events scoring below this significance threshold from 0 to 100 before the rollup. Defaults to 0."},"domainWeights":{"type":"object","properties":{"western":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"vedic":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."},"biorhythm":{"type":"number","minimum":0,"maximum":100,"example":1.5,"description":"Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it."}},"example":{"vedic":1.5,"biorhythm":0.5},"description":"Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm."},"top":{"type":"integer","minimum":0,"maximum":20,"example":3,"description":"Number of highest-significance events to surface per window. Defaults to 3, capped at 20."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Pre-summarized forecast windows: next 24h, 7d, 30d, and 90d rollups","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","format":"time","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"type":"number","example":-4,"description":"Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name."},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this digest was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"Start anchor every window is measured from."},"endDate":{"type":"string","example":"2026-08-29","description":"Last day of the resolved 90 day horizon the timeline was built over before slicing."},"windows":{"type":"array","items":{"type":"object","properties":{"days":{"type":"number","example":7,"description":"Length of this window in days forward from the start anchor. One of 1, 7, 30, 90."},"from":{"type":"string","example":"2026-06-01T00:00:00Z","description":"Inclusive lower bound of the window as an ISO-8601 UTC datetime, the start anchor."},"to":{"type":"string","example":"2026-06-08T00:00:00Z","description":"Exclusive upper bound of the window as an ISO-8601 UTC datetime, the start anchor plus the window length."},"count":{"type":"number","example":5,"description":"Number of events whose datetime falls inside this window."},"byDomain":{"type":"object","properties":{"western":{"type":"number","example":3,"description":"Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written."},"vedic":{"type":"number","example":3,"description":"Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written."},"biorhythm":{"type":"number","example":3,"description":"Number of events in this window produced by this forecast domain. Absent when the domain contributed nothing, so a zero is never written."}},"example":{"western":3,"vedic":1,"biorhythm":1},"description":"Count of events in this window broken down by domain. Only domains with at least one event in the window are present. The values sum to count."},"byType":{"type":"object","properties":{"transit-aspect":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"sign-ingress":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"retrograde-station":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"eclipse":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"lunar-phase":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"dasha-change":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."},"critical-day":{"type":"number","example":3,"description":"Number of events in this window of this event type. Absent when the type did not occur, so a zero is never written."}},"example":{"transit-aspect":3,"sign-ingress":1,"critical-day":1},"description":"Count of events in this window broken down by event type. Only types with at least one event in the window are present. The values sum to count."},"top":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","eclipse","lunar-phase","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types."},"kind":{"type":"string","enum":["penumbral","partial","annular","total"],"example":"total","description":"For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types."},"obscuration":{"type":"number","example":0.966,"description":"For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types."},"phase":{"type":"string","enum":["new-moon","full-moon"],"example":"full-moon","description":"For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The highest-significance events in this window, most significant first, up to the requested top count. The same TimelineEvent shape as the timeline endpoints."}},"required":["days","from","to","count","byDomain","byType","top"]},"description":"The four rollups in ascending window length: next 24h, 7d, 30d, and 90d from the start anchor."}},"required":["birthData","startDate","endDate","windows"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/forecast/solar-return":{"post":{"operationId":"forecastSolarReturn","tags":["Forecast"],"summary":"Solar return chart - Annual birthday forecast chart for a single subject","description":"Cast the solar return chart for one subject and year: the chart erected for the exact moment the transiting Sun returns to its natal ecliptic longitude, the foundational technique for annual astrological forecasting. Returns the full tropical chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Location-sensitive: pass the birthplace to anchor the chart to natal geography, or the current city for a relocated solar return where the houses and Ascendant shift to where you are on your birthday. Built for year-ahead forecast tools, birthday charts, and annual horoscope features.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal Sun longitude the transiting Sun returns to each year."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Pins the exact natal Sun position that defines the solar return moment."},"year":{"type":"integer","minimum":1900,"maximum":2200,"example":2026,"description":"Year to cast the solar return for. The chart is erected for the moment in this year when the transiting Sun returns to the natal Sun longitude, on or within a day of the birthday."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the solar return location in decimal degrees. The solar return is location-sensitive: use the birthplace to anchor the chart to natal geography, or the current city for a relocated solar return."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the solar return location in decimal degrees. Sets the local sidereal time, so it drives the Ascendant, Midheaven, and house cusps of the return chart."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the return chart. placidus is the Western default. whole-sign, equal, and koch are also supported."}},"required":["date","time","year","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Solar return chart cast for the requested year and location","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Echo of the birth date used to find the natal Sun longitude."},"solarReturnDate":{"type":"string","example":"2026-07-15T08:42:11","description":"Exact solar return moment, when the transiting Sun returns to the natal Sun longitude, formatted in the requested timezone. The astrological birthday for the year."},"solarReturnYear":{"type":"number","example":2026,"description":"Year of this solar return. The chart covers the period to the next birthday."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Latitude used for the return chart house cusps and Ascendant."},"longitude":{"type":"number","example":-74.006,"description":"Longitude used for local sidereal time and the Midheaven."},"timezone":{"type":"number","example":-5,"description":"Decimal timezone offset applied to the output datetime."}},"required":["latitude","longitude","timezone"],"description":"Location the return chart was cast for. The Ascendant and house cusps change with this location, the basis of the relocated solar return technique."},"natalSunPosition":{"type":"object","properties":{"longitude":{"type":"number","example":112.45,"description":"Natal Sun ecliptic longitude in degrees from 0 to 360 that the Sun returns to."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign of the natal Sun."},"degree":{"type":"number","example":22.45,"description":"Degree within the sign from 0 to 29.999 that the Sun returns to."}},"required":["longitude","sign","degree"],"description":"The natal Sun position whose annual return defines this chart."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full chart erected for the solar return moment: all bodies with house placements, the 12 house cusps, aspects, Part of Fortune, and Vertex in the tropical zodiac."}},"required":["birthDate","solarReturnDate","solarReturnYear","location","natalSunPosition","chart"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/bodygraph":{"post":{"operationId":"generateBodygraph","tags":["Human Design"],"summary":"Generate full Human Design bodygraph - Type, authority, profile, centers, channels, gates","description":"Generate a complete Human Design bodygraph from a birth date, time, and timezone. Returns the energy type, strategy, inner authority, signature, not-self theme, profile, definition, incarnation cross, all nine centers with defined state and active gates, the defined channels, and all 26 planetary activations across the Personality and Design sides. The single endpoint for a full chart in one call, built for Human Design apps, readings, and coaching tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Complete bodygraph with type, authority, profile, centers, channels, and gates","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","example":"Manifestor","description":"Human Design energy type. One of Manifestor, Generator, Manifesting Generator, Projector, Reflector. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Manifestador","description":"Energy type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeDescription":{"type":"string","example":"An initiating, impactful aura built to start things and set them in motion. Informing others before acting clears resistance and brings peace.","description":"What the aura of this type does and how it is designed to engage life. The grounding text for the type label, so a consuming agent does not have to supply the meaning itself."},"aura":{"type":"string","example":"Closed and repelling. The field pushes outward and deflects influence, so a Manifestor is felt before anything is said, and others tend to brace against energy they cannot read.","description":"The aura mechanic of the type: how the energy field itself operates, for example open and enveloping, or closed and repelling."},"strategy":{"type":"string","example":"Inform","description":"The aura strategy for engaging life correctly for this type. Always English, whatever the lang parameter says. Use strategyLocalized for anything a reader sees."},"strategyLocalized":{"type":"string","example":"Informar","description":"Strategy name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"strategyDescription":{"type":"string","example":"Inform everyone an action will affect, before taking it. This is not asking permission and not seeking approval: it removes the surprise that provokes resistance, which is what turns anger into peace.","description":"How to actually apply the strategy. The strategy field alone is a bare label such as Respond or Inform; this is the operating instruction behind it."},"authority":{"type":"string","example":"Emotional","description":"Inner authority for decision making. One of Emotional, Sacral, Splenic, Ego, Self-Projected, Mental, Lunar. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use authorityLocalized for anything a reader sees."},"authorityLocalized":{"type":"string","example":"Emocional","description":"Inner authority name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"authorityDescription":{"type":"string","example":"Decisions are made across an emotional wave rather than inside a moment. The defined Solar Plexus moves on its own rhythm between hope and pain, so no single moment carries the truth: clarity is what remains once the wave has run its course and settled toward neutral. The trap is committing at the peak, where enthusiasm reads as certainty, or at the trough, where gloom reads as insight, and treating any pressure to answer now as a reason to skip the wait.","description":"How the decision is made, the timing it requires, and the characteristic trap. Inner authority is the most actionable output of a Human Design chart, so this is the field to lean on when grounding a reading."},"signature":{"type":"string","example":"Peace","description":"The signature feeling of living in alignment with the type. Always English, whatever the lang parameter says. Use signatureLocalized for anything a reader sees."},"signatureLocalized":{"type":"string","example":"Paz","description":"Signature theme name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"notSelf":{"type":"string","example":"Anger","description":"The not-self theme, the recurring feeling that signals being out of alignment. Always English, whatever the lang parameter says. Use notSelfLocalized for anything a reader sees."},"notSelfLocalized":{"type":"string","example":"Ira","description":"Not-self theme name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"profile":{"type":"string","example":"5/1","description":"Profile in conscious/unconscious form from the Personality Sun line over the Design Sun line."},"profileKeynotes":{"type":"object","properties":{"personalityLine":{"type":"number","example":5,"description":"Line number 1 to 6 of the conscious Personality Sun, the first digit of the profile."},"designLine":{"type":"number","example":1,"description":"Line number 1 to 6 of the unconscious Design Sun, the second digit of the profile."},"personality":{"type":"string","example":"Heretic: a universalizing, practical force others project expectations onto.","description":"Keynote of the conscious Personality line. The half of the life role the person is aware of and can speak to."},"design":{"type":"string","example":"Investigator: builds a secure foundation through study before acting.","description":"Keynote of the unconscious Design line. The half of the life role others see operating in the body, which the person does not directly experience."}},"required":["personalityLine","designLine","personality","design"],"description":"The two line keynotes the profile is built from, conscious over unconscious, so the profile is readable without a separate lookup."},"profileDescription":{"type":"string","example":"Heretic over Investigator. A conscious projection field leads others to assume a solution is already at hand, and the unconscious first line quietly supplies the foundation that can actually answer. Reputation is both the currency and the risk: with real preparation the practical solution lands far beyond the personal, and without it the same projection curdles into blame.","description":"Meaning of the combined profile. A profile is not the sum of its two lines: 6/2 has its own meaning that neither the line 6 nor the line 2 keynote carries alone."},"definition":{"type":"string","example":"Split","description":"Definition type from the number of connected components among defined centers. One of None, Single, Split, Triple Split, Quadruple Split. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use definitionLocalized for anything a reader sees."},"definitionLocalized":{"type":"string","example":"Dividida","description":"Definition type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"definitionDescription":{"type":"string","example":"The defined centers fall into two groups with no channel between them, so energy is consistent inside each group and does not cross the divide. The gap is bridged by the gates other people carry, which is why particular company can make thinking suddenly feel joined up, and why that company is easily mistaken for completion rather than recognized as a temporary bridge. What the configuration needs is time for the two areas to synthesize and awareness of who is bridging them, not a rushed decision taken while the halves are still speaking separately.","description":"How energy flows through the defined centers in this configuration, and what the configuration needs. For a split, this is where the bridging gates of other people matter."},"sides":{"type":"object","additionalProperties":{"type":"string","example":"The conscious side, printed in black and calculated at the moment of birth. These activations are the mind and the sense of self: what the person recognizes as their own and can describe to someone else.","description":"What this chart side is and what it governs, localized by the lang query parameter. Render it as the legend beside the personality or design column of a bodygraph."},"example":{"personality":"The conscious side, printed in black and calculated at the moment of birth.","design":"The unconscious side, printed in red and calculated 88 degrees of solar arc before birth."},"description":"What the two chart sides are: personality is the conscious mind side, design is the unconscious body side computed 88 degrees of solar arc before birth. Returned once at the top level rather than repeated across all 26 activations."},"incarnationCross":{"type":"object","properties":{"gates":{"type":"array","items":{"type":"number"},"example":[51,57,61,62],"description":"The four cardinal gates of the cross: Personality Sun, Personality Earth, Design Sun, Design Earth."},"angle":{"type":"string","example":"Left Angle","description":"Cross angle. One of Right Angle, Juxtaposition, Left Angle. Always English, whatever the lang parameter says. Use angleLocalized for anything a reader sees."},"angleLocalized":{"type":"string","example":"Ángulo Izquierdo","description":"Cross angle name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angleCode":{"type":"string","example":"LAX","description":"Short code for the angle. One of RAX, JXT, LAX."},"name":{"type":"string","example":"Left Angle Cross of the Clarion","description":"Canonical published name of the incarnation cross, determined by the Personality Sun gate and the angle. Falls back to a name composed from the angle and the four gates if no canonical name exists."},"description":{"type":"string","example":"Shock delivered to whoever is ready for it. The reaction is often outrage, and underneath it is a change that was waiting for something to force it, which is why the shock needs a receiver.","description":"The life theme of the cross, synthesized from its four gates and the orientation the angle gives them. The same Sun gate under a different angle is a genuinely different theme: Right Angle is personal destiny, Left Angle is worked out through other people, Juxtaposition is a fixed fate."}},"required":["gates","angle","angleCode","name"],"description":"The incarnation cross built from the four cardinal gates and the profile angle."},"centers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sacral","description":"Center identifier. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root."},"name":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"defined":{"type":"boolean","example":true,"description":"Whether the center is defined. A defined center is a consistent source of energy or awareness; an undefined center is open and conditioned by others."},"motor":{"type":"boolean","example":true,"description":"Whether this is a motor center (energy source). The four motors are Heart, Sacral, Solar Plexus, and Root."},"awareness":{"type":"boolean","example":false,"description":"Whether this is an awareness center. The three awareness centers are Ajna, Solar Plexus, and Spleen."},"theme":{"type":"string","example":"Sustainable life force and work energy. A reliable gut response that guides what to engage with.","description":"Theme text describing the center in its current defined or undefined state."},"notSelfQuestion":{"type":"string","example":"Is all this talking and doing an attempt to attract attention?","description":"The conditioning trap of this center when it is open. Returned on every center so a consumer can surface it the moment `defined` is false, which is where the not-self operates."},"biology":{"type":"string","example":"The adrenal glands.","description":"The gland, organ, or system this center corresponds to in the body."},"gates":{"type":"array","items":{"type":"number"},"example":[5,14,34],"description":"Active gate numbers that sit in this center."}},"required":["id","name","defined","motor","awareness","theme","notSelfQuestion","biology","gates"]},"description":"All nine centers with their defined state and active gates."},"channels":{"type":"array","items":{"type":"object","properties":{"gateA":{"type":"number","example":20,"description":"First gate of the channel."},"gateB":{"type":"number","example":34,"description":"Second gate of the channel."},"name":{"type":"string","example":"Charisma","description":"Name of the defined channel. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Carisma","description":"Channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"circuit":{"type":"string","example":"Individual","description":"Circuit family of the channel. One of Individual, Collective, Tribal. Always English, whatever the lang parameter says. Use circuitLocalized for anything a reader sees."},"circuitLocalized":{"type":"string","example":"Individual","description":"Circuit family name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"centers":{"type":"array","items":{"type":"string"},"example":["throat","sacral"],"description":"The two centers this channel connects and defines."},"description":{"type":"string","example":"Sacral power is pushed straight to the Throat, so awareness in the present moment becomes action with almost no pause between them. The energy stays healthy only while it is busy with work it loves.","description":"What this channel wires between its two centers and the nature of the energy it carries."},"circuitDescription":{"type":"string","example":"Empowerment through mutation, carried by 15 channels. The knowing here cannot be explained or handed over, only lived, and it changes other people by exposure rather than instruction. It arrives as a pulse, never on demand.","description":"What the circuit family of this channel governs."}},"required":["gateA","gateB","name","circuit","centers","description","circuitDescription"]},"description":"The defined channels where both gates are activated."},"gates":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Activating body. One of Sun, Earth, Moon, North Node, South Node, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto. Always English, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Activating body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"side":{"type":"string","example":"personality","description":"Chart side. personality is the conscious birth-moment activation, design is the unconscious activation 88 degrees of solar arc before birth."},"gate":{"type":"number","example":51,"description":"Human Design gate number from 1 to 64 that this activation falls in."},"line":{"type":"number","example":5,"description":"Line number from 1 to 6 within the gate, setting the line keynote and the profile."},"gateName":{"type":"string","example":"Shock","description":"Human Design keynote name of the gate, describing its bodygraph function. Always English, whatever the lang parameter says. Use gateNameLocalized for anything a reader sees."},"gateNameLocalized":{"type":"string","example":"Choque","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"gateDescription":{"type":"string","example":"Willpower that shocks and competes. Sitting in the heart center, it moves first and startles, and that shock is what initiates others into a deeper connection with spirit.","description":"Bodygraph function of the gate: what it does in the center it sits in and the channel it forms. This is NOT the meaning of the I-Ching hexagram that shares its number. They share a number, not a definition."},"lineMeaning":{"type":"string","example":"The group turns to this line when everything breaks. It reads the shape of the shock and rides it, and savoring the victory is what leaves it exposed to the next one.","description":"Meaning of this gate at this specific line, one of 384. The finest interpretive layer in the chart and the one that makes a reading specific rather than generic. This is not the six abstract line archetypes: gate 41 line 3 carries its own meaning that neither the gate keynote nor the line-3 archetype holds alone."},"planetDescription":{"type":"string","example":"The dominant activation. With the Earth it carries roughly 70 percent of the imprint on the chart. The Personality Sun gate is the conscious life theme, the Design Sun is the radiance the body broadcasts before a word is spoken.","description":"What this planetary activation contributes in Human Design specifically, which is not its meaning in western astrology."},"ichingHexagram":{"type":"object","properties":{"number":{"type":"number","example":51,"description":"I-Ching hexagram number, identical to the gate number it corresponds to."},"english":{"type":"string","example":"The Arousing","description":"English name of the corresponding I-Ching hexagram."}},"required":["number","english"],"description":"Cross-reference to the I-Ching hexagram that shares this gate number."}},"required":["planet","side","gate","line","gateName","gateDescription","lineMeaning","planetDescription","ichingHexagram"]},"description":"All 26 activations, 13 Personality and 13 Design."}},"required":["type","typeDescription","aura","strategy","strategyDescription","authority","authorityDescription","signature","notSelf","profile","profileKeynotes","profileDescription","definition","definitionDescription","sides","incarnationCross","centers","channels","gates"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/connection":{"post":{"operationId":"calculateConnection","tags":["Human Design"],"summary":"Calculate Human Design connection chart - Two-person composite bodygraph compatibility","description":"Calculate a Human Design connection chart by overlaying two bodygraphs. For each of the 36 channels the dynamic between the two people is classified as electromagnetic, dominance, compromise, or companionship, the four mechanics of how two designs meet. Also returns the nine centers as defined or open in the combined bodygraph with which person defines each, the combined definition, and a count of each dynamic. Built for relationship, dating, and coaching tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"],"description":"Birth moment of the first person in the connection."},"personB":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"],"description":"Birth moment of the second person in the connection."}},"required":["personA","personB"]}}}},"responses":{"200":{"description":"Connection chart with per-channel dynamics, combined centers, definition, and a dynamic count","content":{"application/json":{"schema":{"type":"object","properties":{"totalChannels":{"type":"number","example":14,"description":"Total number of connected channels between the two people. Equals the length of channels and the sum of the summary counts."},"channels":{"type":"array","items":{"type":"object","properties":{"gateA":{"type":"number","example":34,"description":"First gate of the channel."},"gateB":{"type":"number","example":20,"description":"Second gate of the channel."},"name":{"type":"string","example":"Charisma","description":"Name of the channel whose connection dynamic is reported. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Carisma","description":"Channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"circuit":{"type":"string","example":"Individual","description":"Circuit family of the channel. One of Individual, Collective, Tribal. Always English, whatever the lang parameter says. Use circuitLocalized for anything a reader sees."},"circuitLocalized":{"type":"string","example":"Individual","description":"Circuit family name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"centers":{"type":"array","items":{"type":"string"},"example":["throat","sacral"],"description":"The two centers this channel connects in the bodygraph."},"dynamic":{"type":"string","example":"Electromagnetic","description":"Connection dynamic for this channel. Electromagnetic means each person holds one of the two gates and the channel completes only together, the classic point of attraction. Dominance means one person holds both gates and the other holds neither, a one-way conditioning. Compromise means one person holds both gates and the other holds a single hanging gate. Companionship means both people independently hold both gates, a shared and familiar frequency. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use dynamicLocalized for anything a reader sees."},"dynamicLocalized":{"type":"string","example":"Electromagnético","description":"Connection dynamic name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"personAGates":{"type":"array","items":{"type":"number"},"example":[34],"description":"Which of the channel two gates person A holds, from one to both."},"personBGates":{"type":"array","items":{"type":"number"},"example":[20],"description":"Which of the channel two gates person B holds, from one to both."}},"required":["gateA","gateB","name","circuit","centers","dynamic","personAGates","personBGates"]},"description":"Every connected channel between the two people with its dynamic. A channel is connected when the two people together hold both of its gates."},"centers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sacral","description":"Center identifier. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root."},"name":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"defined":{"type":"boolean","example":true,"description":"Whether the center is defined in the combined connection bodygraph, where a channel counts as defined when the two people together hold both of its gates."},"definedBy":{"type":"array","items":{"type":"string"},"example":["A"],"description":"Who defines this center in their own chart. A, B, both, or empty when the center is open in both individual charts."}},"required":["id","name","defined","definedBy"]},"description":"All nine centers with their defined state in the combined connection bodygraph and which person defines each."},"combinedDefinition":{"type":"string","example":"Single","description":"Definition of the combined connection bodygraph from connected components among its defined centers. One of None, Single, Split, Triple Split, Quadruple Split. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use combinedDefinitionLocalized for anything a reader sees."},"combinedDefinitionLocalized":{"type":"string","example":"Simple","description":"Combined definition name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"summary":{"type":"object","properties":{"electromagnetic":{"type":"number","example":3,"description":"Count of electromagnetic channels, the points of mutual attraction."},"dominance":{"type":"number","example":2,"description":"Count of dominance channels, where one person conditions the other one way."},"compromise":{"type":"number","example":1,"description":"Count of compromise channels, a full channel meeting a single hanging gate."},"companionship":{"type":"number","example":4,"description":"Count of companionship channels, where both people share the whole channel."}},"required":["electromagnetic","dominance","compromise","companionship"],"description":"Count of each connection dynamic across all connected channels."}},"required":["totalChannels","channels","centers","combinedDefinition","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/penta":{"post":{"operationId":"calculatePenta","tags":["Human Design"],"summary":"Calculate Human Design Penta - Small-group BG5 operating system for three to five people","description":"Calculate the Human Design Penta (BG5, Base Group 5) for a small group of three to five people. The Penta is a trans-auric form built from a fixed set of six channels running only between the Sacral, the G Center, and the Throat. It reports which of the twelve Penta gates are filled and by whom, which of the six channels are defined Strengths, the upper leadership channels versus the lower generative channels, the 2/14 material core, and the functional gaps where no member supplies a role. Built for team, family, and group analysis tools. Below three people no Penta forms and above five a second Penta emerges, so the group size must be three to five.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]},"minItems":3,"maxItems":5,"description":"Birth moments of the three to five people in the group. Below three no Penta forms; above five a second Penta emerges."}},"required":["members"]}}}},"responses":{"200":{"description":"Penta chart with per-channel Strengths, per-gate fill state, and a group summary","content":{"application/json":{"schema":{"type":"object","properties":{"memberCount":{"type":"number","example":4,"description":"Number of people in the group, always between 3 and 5."},"channels":{"type":"array","items":{"type":"object","properties":{"gateA":{"type":"number","example":2,"description":"First gate of the Penta channel."},"gateB":{"type":"number","example":14,"description":"Second gate of the Penta channel."},"name":{"type":"string","example":"The Beat","description":"Name of the Penta channel. One of The Alpha, Inspiration, The Prodigal, Rhythm, The Beat, Discovery. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"El Ritmo","description":"Penta channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"circuit":{"type":"string","example":"Individual","description":"Circuit family of the channel. One of Individual, Collective, Tribal. Always English, whatever the lang parameter says. Use circuitLocalized for anything a reader sees."},"circuitLocalized":{"type":"string","example":"Individual","description":"Circuit family name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"position":{"type":"string","example":"lower","description":"Position of the channel in the Penta. upper channels run from the G Center to the Throat and carry the leadership and how-the-group-presents roles. lower channels run from the G Center to the Sacral and carry the managed, generative, resource roles."},"isCore":{"type":"boolean","example":true,"description":"Whether this is the 2/14 Channel of the Beat, the material core of the Penta vortex: gate 2 the direction for resources, gate 14 the resources themselves."},"defined":{"type":"boolean","example":true,"description":"Whether the channel is a defined Strength: both of its gates are present somewhere in the group, so the function it governs has no gap."},"gateAHeldBy":{"type":"array","items":{"type":"number"},"example":[0,2],"description":"Zero-based indices of the members whose chart holds gate A, in member order."},"gateBHeldBy":{"type":"array","items":{"type":"number"},"example":[1],"description":"Zero-based indices of the members whose chart holds gate B, in member order."}},"required":["gateA","gateB","name","circuit","position","isCore","defined","gateAHeldBy","gateBHeldBy"]},"description":"The six channels of the Penta with their defined Strength state and which members supply each gate. Three upper channels run G to Throat (The Alpha, Inspiration, The Prodigal); three lower channels run G to Sacral (Rhythm, The Beat, Discovery)."},"gates":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"number","example":15,"description":"Penta gate number. One of 1, 2, 5, 7, 8, 13, 14, 15, 29, 31, 33, 46."},"gateName":{"type":"string","example":"Extremes","description":"Human Design keynote name of the gate, describing the role it brings to the group. Always English, whatever the lang parameter says. Use gateNameLocalized for anything a reader sees."},"gateNameLocalized":{"type":"string","example":"Extremos","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"filled":{"type":"boolean","example":true,"description":"Whether at least one member holds this gate. A gate held by nobody is a gap that conditions the group to compensate for the missing role."},"heldBy":{"type":"array","items":{"type":"number"},"example":[0],"description":"Zero-based indices of the members whose chart holds this gate. Empty when the gate is a gap."}},"required":["gate","gateName","filled","heldBy"]},"description":"The twelve Penta gates with their filled state and which members hold each."},"summary":{"type":"object","properties":{"definedChannels":{"type":"number","example":4,"description":"Count of the six Penta channels that are defined Strengths in the group."},"filledGates":{"type":"number","example":9,"description":"Count of the twelve Penta gates filled by at least one member."},"gapGates":{"type":"array","items":{"type":"number"},"example":[7,31,33],"description":"Penta gates held by no member. A non-empty list flags the functional gaps in the group."},"coreDefined":{"type":"boolean","example":true,"description":"Whether the 2/14 Channel of the Beat, the material core of the Penta, is defined across the group."}},"required":["definedChannels","filledGates","gapGates","coreDefined"],"description":"Group-level rollup of the Penta channels and gates."}},"required":["memberCount","channels","gates","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/transit":{"post":{"operationId":"generateTransit","tags":["Human Design"],"summary":"Generate Human Design transit overlay - Current planetary activations on a natal bodygraph","description":"Overlay the current or any given planetary positions on a natal Human Design bodygraph to see which channels the transit temporarily completes. Returns the 13 transiting body activations with gate and line, the channels the transit completes beyond the natal definition split into personal channels where the transit supplies the partner gate of a natal gate and educational channels where the transit supplies both gates, the natally open centers those channels temporarily define, and a short factual summary. A transit is a single moment, so there is no Design side. When date and time are omitted the overlay is computed for now in UTC. Built for daily Human Design apps, transit widgets, and notification tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"],"description":"Birth moment whose natal bodygraph the transit is overlaid on."},"date":{"type":"string","format":"date","example":"2026-05-23","description":"Transit date in YYYY-MM-DD UTC. Optional. Defaults to today in UTC when omitted, giving the just-now transit."},"time":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS UTC. Optional. Defaults to the current UTC time when omitted. Precision matters: the Moon moves through a gate in roughly half a day."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Transit overlay with transiting activations, completed channels, temporary centers, and a summary","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-05-23","description":"Date the transit overlay was computed for, in YYYY-MM-DD UTC."},"time":{"type":"string","example":"12:00:00","description":"Time the transit overlay was computed for, in HH:MM:SS UTC."},"timezone":{"type":"number","example":0,"description":"UTC offset of the transit moment. Always 0, since the transit is computed in UTC."},"activations":{"type":"array","items":{"type":"object","properties":{"body":{"type":"string","example":"Sun","description":"Transiting body whose current position lands on this gate. One of Sun, Earth, Moon, North Node, South Node, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto. Always English, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on. Use bodyLocalized for anything a reader sees."},"bodyLocalized":{"type":"string","example":"Sol","description":"Transiting body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"gate":{"type":"number","example":51,"description":"Human Design gate number from 1 to 64 this transiting body currently sits in."},"line":{"type":"number","example":3,"description":"Line number from 1 to 6 within the gate, setting the line keynote of the transit."},"gateName":{"type":"string","example":"Shock","description":"Human Design keynote name of the gate the transiting body activates. Always English, whatever the lang parameter says. Use gateNameLocalized for anything a reader sees."},"gateNameLocalized":{"type":"string","example":"Choque","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"ichingHexagram":{"type":"object","properties":{"number":{"type":"number","example":51,"description":"I-Ching hexagram number, identical to the gate number it corresponds to."},"english":{"type":"string","example":"The Arousing","description":"English name of the corresponding I-Ching hexagram."}},"required":["number","english"],"description":"Cross-reference to the I-Ching hexagram that shares this gate number."}},"required":["body","gate","line","gateName","ichingHexagram"]},"description":"The 13 transiting bodies at this moment with the gate and line each currently activates. A transit is a single instant, so there is no Design side, only current positions."},"completedChannels":{"type":"array","items":{"type":"object","properties":{"gateA":{"type":"number","example":34,"description":"First gate of the completed channel."},"gateB":{"type":"number","example":20,"description":"Second gate of the completed channel."},"name":{"type":"string","example":"Charisma","description":"Name of the channel the transit temporarily completes. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Carisma","description":"Channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"circuit":{"type":"string","example":"Individual","description":"Circuit family of the channel. One of Individual, Collective, Tribal. Always English, whatever the lang parameter says. Use circuitLocalized for anything a reader sees."},"circuitLocalized":{"type":"string","example":"Individual","description":"Circuit family name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"centers":{"type":"array","items":{"type":"string"},"example":["throat","sacral"],"description":"The two centers this channel connects and temporarily defines."},"kind":{"type":"string","example":"personal","description":"How the transit completes the channel. personal means the natal chart already holds one gate and the transit supplies the other, the classic electromagnetic completion. educational means both gates are open in the natal chart and the transit supplies both at once. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use kindLocalized for anything a reader sees."},"kindLocalized":{"type":"string","example":"personal","description":"Completion kind name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalGates":{"type":"array","items":{"type":"number"},"example":[34],"description":"Gate or gates of this channel the natal chart already holds. Empty for an educational channel."},"transitGates":{"type":"array","items":{"type":"number"},"example":[20],"description":"Gate or gates of this channel supplied by the transit. One gate for a personal channel, both gates for an educational channel."}},"required":["gateA","gateB","name","circuit","centers","kind","natalGates","transitGates"]},"description":"Channels the transit temporarily completes that the natal chart did not already define, each labelled personal or educational with the side that supplied each gate."},"temporaryCenters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sacral","description":"Center identifier. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root."},"name":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"temporarilyDefined":{"type":"boolean","example":true,"description":"Always true. The center is open in the natal chart and temporarily defined by a transit-completed channel for the duration of the transit."}},"required":["id","name","temporarilyDefined"]},"description":"Centers that are open in the natal chart and temporarily defined by a transit-completed channel."},"summary":{"type":"string","example":"This transit completes 2 channels: 1 personal channel where the transit supplies the partner gate of a natal gate and 1 educational channel where the transit supplies both gates.","description":"Short factual summary of the overlay with channel and center counts only."}},"required":["date","time","timezone","activations","completedChannels","temporaryCenters","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/type":{"post":{"operationId":"calculateType","tags":["Human Design"],"summary":"Calculate Human Design type, authority and profile","description":"Calculate the core Human Design identity from a birth moment: the energy type, the aura strategy, the inner authority, the signature and not-self themes, and the profile. The fast lookup for type-and-authority features without the full bodygraph payload. Verified against NASA JPL Horizons positions.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Type, strategy, authority, signature, not-self theme, and profile","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","example":"Manifestor","description":"Human Design energy type. One of Manifestor, Generator, Manifesting Generator, Projector, Reflector. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Manifestador","description":"Energy type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeDescription":{"type":"string","example":"An initiating, impactful aura built to start things and set them in motion. Informing others before acting clears resistance and brings peace.","description":"What the aura of this type does and how it is designed to engage life. The grounding text for the type label, so a consuming agent does not have to supply the meaning itself."},"aura":{"type":"string","example":"Closed and repelling. The field pushes outward and deflects influence, so a Manifestor is felt before anything is said, and others tend to brace against energy they cannot read.","description":"The aura mechanic of the type: how the energy field itself operates, for example open and enveloping, or closed and repelling."},"strategy":{"type":"string","example":"Inform","description":"The aura strategy for engaging life correctly for this type. Always English, whatever the lang parameter says. Use strategyLocalized for anything a reader sees."},"strategyLocalized":{"type":"string","example":"Informar","description":"Strategy name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"strategyDescription":{"type":"string","example":"Inform everyone an action will affect, before taking it. This is not asking permission and not seeking approval: it removes the surprise that provokes resistance, which is what turns anger into peace.","description":"How to actually apply the strategy. The strategy field alone is a bare label such as Respond or Inform; this is the operating instruction behind it."},"authority":{"type":"string","example":"Emotional","description":"Inner authority for decision making. One of Emotional, Sacral, Splenic, Ego, Self-Projected, Mental, Lunar. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use authorityLocalized for anything a reader sees."},"authorityLocalized":{"type":"string","example":"Emocional","description":"Inner authority name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"authorityDescription":{"type":"string","example":"Decisions are made across an emotional wave rather than inside a moment. The defined Solar Plexus moves on its own rhythm between hope and pain, so no single moment carries the truth: clarity is what remains once the wave has run its course and settled toward neutral. The trap is committing at the peak, where enthusiasm reads as certainty, or at the trough, where gloom reads as insight, and treating any pressure to answer now as a reason to skip the wait.","description":"How the decision is made, the timing it requires, and the characteristic trap. Inner authority is the most actionable output of a Human Design chart."},"signature":{"type":"string","example":"Peace","description":"The signature feeling of living in alignment. Always English, whatever the lang parameter says. Use signatureLocalized for anything a reader sees."},"signatureLocalized":{"type":"string","example":"Paz","description":"Signature theme name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"notSelf":{"type":"string","example":"Anger","description":"The not-self theme that signals being out of alignment. Always English, whatever the lang parameter says. Use notSelfLocalized for anything a reader sees."},"notSelfLocalized":{"type":"string","example":"Ira","description":"Not-self theme name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"profile":{"type":"string","example":"5/1","description":"Profile from the Personality Sun line over the Design Sun line."}},"required":["type","typeDescription","aura","strategy","strategyDescription","authority","authorityDescription","signature","notSelf","profile"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/gates":{"post":{"operationId":"calculateGates","tags":["Human Design"],"summary":"Calculate the 26 Human Design gate activations","description":"Calculate the 26 gate activations for a birth moment, split into the 13 conscious Personality activations at birth and the 13 unconscious Design activations 88 degrees of solar arc earlier. Each activation reports the planet, gate, line, gate keynote, and the matching I-Ching hexagram. Built for activation columns and detailed chart views.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Personality and Design activation lists, 13 each","content":{"application/json":{"schema":{"type":"object","properties":{"personality":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Activating body. One of Sun, Earth, Moon, North Node, South Node, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto. Always English, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Activating body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"side":{"type":"string","example":"personality","description":"Chart side. personality is the conscious birth-moment activation, design is the unconscious activation 88 degrees of solar arc before birth."},"gate":{"type":"number","example":51,"description":"Human Design gate number from 1 to 64 that this activation falls in."},"line":{"type":"number","example":5,"description":"Line number from 1 to 6 within the gate, setting the line keynote and the profile."},"gateName":{"type":"string","example":"Shock","description":"Human Design keynote name of the gate, describing its bodygraph function. Always English, whatever the lang parameter says. Use gateNameLocalized for anything a reader sees."},"gateNameLocalized":{"type":"string","example":"Choque","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"gateDescription":{"type":"string","example":"Willpower that shocks and competes. Sitting in the heart center, it moves first and startles, and that shock is what initiates others into a deeper connection with spirit.","description":"Bodygraph function of the gate: what it does in the center it sits in and the channel it forms. This is NOT the meaning of the I-Ching hexagram that shares its number. They share a number, not a definition."},"lineMeaning":{"type":"string","example":"The group turns to this line when everything breaks. It reads the shape of the shock and rides it, and savoring the victory is what leaves it exposed to the next one.","description":"Meaning of this gate at this specific line, one of 384. The finest interpretive layer in the chart and the one that makes a reading specific rather than generic. This is not the six abstract line archetypes: gate 41 line 3 carries its own meaning that neither the gate keynote nor the line-3 archetype holds alone."},"planetDescription":{"type":"string","example":"The dominant activation. With the Earth it carries roughly 70 percent of the imprint on the chart. The Personality Sun gate is the conscious life theme, the Design Sun is the radiance the body broadcasts before a word is spoken.","description":"What this planetary activation contributes in Human Design specifically, which is not its meaning in western astrology."},"ichingHexagram":{"type":"object","properties":{"number":{"type":"number","example":51,"description":"I-Ching hexagram number, identical to the gate number it corresponds to."},"english":{"type":"string","example":"The Arousing","description":"English name of the corresponding I-Ching hexagram."}},"required":["number","english"],"description":"Cross-reference to the I-Ching hexagram that shares this gate number."}},"required":["planet","side","gate","line","gateName","gateDescription","lineMeaning","planetDescription","ichingHexagram"]},"description":"The 13 conscious Personality activations computed at the exact birth moment, in black on a standard chart."},"design":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Activating body. One of Sun, Earth, Moon, North Node, South Node, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto. Always English, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Activating body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"side":{"type":"string","example":"personality","description":"Chart side. personality is the conscious birth-moment activation, design is the unconscious activation 88 degrees of solar arc before birth."},"gate":{"type":"number","example":51,"description":"Human Design gate number from 1 to 64 that this activation falls in."},"line":{"type":"number","example":5,"description":"Line number from 1 to 6 within the gate, setting the line keynote and the profile."},"gateName":{"type":"string","example":"Shock","description":"Human Design keynote name of the gate, describing its bodygraph function. Always English, whatever the lang parameter says. Use gateNameLocalized for anything a reader sees."},"gateNameLocalized":{"type":"string","example":"Choque","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"gateDescription":{"type":"string","example":"Willpower that shocks and competes. Sitting in the heart center, it moves first and startles, and that shock is what initiates others into a deeper connection with spirit.","description":"Bodygraph function of the gate: what it does in the center it sits in and the channel it forms. This is NOT the meaning of the I-Ching hexagram that shares its number. They share a number, not a definition."},"lineMeaning":{"type":"string","example":"The group turns to this line when everything breaks. It reads the shape of the shock and rides it, and savoring the victory is what leaves it exposed to the next one.","description":"Meaning of this gate at this specific line, one of 384. The finest interpretive layer in the chart and the one that makes a reading specific rather than generic. This is not the six abstract line archetypes: gate 41 line 3 carries its own meaning that neither the gate keynote nor the line-3 archetype holds alone."},"planetDescription":{"type":"string","example":"The dominant activation. With the Earth it carries roughly 70 percent of the imprint on the chart. The Personality Sun gate is the conscious life theme, the Design Sun is the radiance the body broadcasts before a word is spoken.","description":"What this planetary activation contributes in Human Design specifically, which is not its meaning in western astrology."},"ichingHexagram":{"type":"object","properties":{"number":{"type":"number","example":51,"description":"I-Ching hexagram number, identical to the gate number it corresponds to."},"english":{"type":"string","example":"The Arousing","description":"English name of the corresponding I-Ching hexagram."}},"required":["number","english"],"description":"Cross-reference to the I-Ching hexagram that shares this gate number."}},"required":["planet","side","gate","line","gateName","gateDescription","lineMeaning","planetDescription","ichingHexagram"]},"description":"The 13 unconscious Design activations computed 88 degrees of solar arc before birth, in red on a standard chart."}},"required":["personality","design"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/gates/{number}":{"get":{"operationId":"getGate","tags":["Human Design"],"summary":"Look up a Human Design gate by number","description":"Look up the static reference data for a Human Design gate by its number from 1 to 64: the gate keynote name, the center it sits in, the matching I-Ching hexagram, and the gates that form a channel with it. A pure reference endpoint with no birth data required.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":["integer","null"],"example":34,"description":"Gate number from 1 to 64."},"required":true,"description":"Gate number from 1 to 64.","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Gate reference data with center, hexagram, and channel partners","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":34,"description":"Gate number from 1 to 64."},"name":{"type":"string","example":"Power","description":"Human Design keynote name of the gate. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Poder","description":"Gate keynote name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"center":{"type":"string","example":"sacral","description":"Center the gate sits in."},"centerName":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says. Use centerNameLocalized for anything a reader sees."},"centerNameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"ichingHexagram":{"type":"object","properties":{"number":{"type":"number","example":34,"description":"I-Ching hexagram number."},"english":{"type":"string","example":"The Power of the Great","description":"Hexagram name."}},"required":["number","english"],"description":"The I-Ching hexagram that shares this gate number."},"channelPartners":{"type":"array","items":{"type":"object","properties":{"gate":{"type":"number","example":20,"description":"Partner gate number."},"channel":{"type":"string","example":"Charisma","description":"Name of the shared channel. Always English, whatever the lang parameter says. Use channelLocalized for anything a reader sees."},"channelLocalized":{"type":"string","example":"Carisma","description":"Channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["gate","channel"]},"description":"Gates that form a channel with this gate, with the channel name for each."}},"required":["number","name","center","centerName","ichingHexagram","channelPartners"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Gate number is outside the range 1 to 64","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/channels":{"post":{"operationId":"calculateChannels","tags":["Human Design"],"summary":"Calculate the defined Human Design channels","description":"Calculate the defined channels for a birth moment. A channel is defined when both of its gates are activated, and it wires together the two centers it connects. Returns each defined channel with its gates, name, circuit family, and connected centers, plus the full set of centers those channels define. Built for bodygraph rendering and definition analysis.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Defined channels with circuits and the centers they define","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"gateA":{"type":"number","example":20,"description":"First gate of the channel."},"gateB":{"type":"number","example":34,"description":"Second gate of the channel."},"name":{"type":"string","example":"Charisma","description":"Name of the defined channel. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Carisma","description":"Channel name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"circuit":{"type":"string","example":"Individual","description":"Circuit family of the channel. One of Individual, Collective, Tribal. Always English, whatever the lang parameter says. Use circuitLocalized for anything a reader sees."},"circuitLocalized":{"type":"string","example":"Individual","description":"Circuit family name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"centers":{"type":"array","items":{"type":"string"},"example":["throat","sacral"],"description":"The two centers this channel connects and defines."},"description":{"type":"string","example":"Sacral power is pushed straight to the Throat, so awareness in the present moment becomes action with almost no pause between them. The energy stays healthy only while it is busy with work it loves.","description":"What this channel wires between its two centers and the nature of the energy it carries."},"circuitDescription":{"type":"string","example":"Empowerment through mutation, carried by 15 channels. The knowing here cannot be explained or handed over, only lived, and it changes other people by exposure rather than instruction. It arrives as a pulse, never on demand.","description":"What the circuit family of this channel governs."}},"required":["gateA","gateB","name","circuit","centers","description","circuitDescription"]},"description":"The defined channels, where both gates are activated."},"total":{"type":"number","example":3,"description":"Number of defined channels in the bodygraph."},"definedCenters":{"type":"array","items":{"type":"string"},"example":["throat","sacral","g"],"description":"The centers defined by these channels."}},"required":["channels","total","definedCenters"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/centers":{"post":{"operationId":"calculateCenters","tags":["Human Design"],"summary":"Calculate the nine Human Design centers","description":"Calculate the state of all nine Human Design centers for a birth moment: whether each is defined or open, whether it is a motor or an awareness center, its theme, and the active gates it holds. The data layer behind a rendered bodygraph where defined centers are colored and open centers are white.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"All nine centers with defined state, flags, theme, and active gates","content":{"application/json":{"schema":{"type":"object","properties":{"centers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sacral","description":"Center identifier. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root."},"name":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"defined":{"type":"boolean","example":true,"description":"Whether the center is defined. A defined center is a consistent source of energy or awareness; an undefined center is open and conditioned by others."},"motor":{"type":"boolean","example":true,"description":"Whether this is a motor center (energy source). The four motors are Heart, Sacral, Solar Plexus, and Root."},"awareness":{"type":"boolean","example":false,"description":"Whether this is an awareness center. The three awareness centers are Ajna, Solar Plexus, and Spleen."},"theme":{"type":"string","example":"Sustainable life force and work energy. A reliable gut response that guides what to engage with.","description":"Theme text describing the center in its current defined or undefined state."},"notSelfQuestion":{"type":"string","example":"Is all this talking and doing an attempt to attract attention?","description":"The conditioning trap of this center when it is open. Returned on every center so a consumer can surface it the moment `defined` is false, which is where the not-self operates."},"biology":{"type":"string","example":"The adrenal glands.","description":"The gland, organ, or system this center corresponds to in the body."},"gates":{"type":"array","items":{"type":"number"},"example":[5,14,34],"description":"Active gate numbers that sit in this center."}},"required":["id","name","defined","motor","awareness","theme","notSelfQuestion","biology","gates"]},"description":"All nine centers with their defined state and active gates."},"definedCount":{"type":"number","example":4,"description":"How many of the nine centers are defined."}},"required":["centers","definedCount"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/centers/{id}":{"get":{"operationId":"getCenter","tags":["Human Design"],"summary":"Look up a Human Design center by id","description":"Look up the static reference data for one of the nine Human Design centers by its id: the display name, whether it is a motor or awareness center, and what it means both defined and undefined. A pure reference endpoint with no birth data required.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["head","ajna","throat","g","heart","sacral","solar-plexus","spleen","root"],"example":"sacral","description":"Center id. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root."},"required":true,"description":"Center id. One of head, ajna, throat, g, heart, sacral, solar-plexus, spleen, root.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Center reference data with defined and undefined meanings","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"sacral","description":"Center identifier."},"name":{"type":"string","example":"Sacral","description":"Display name of the center. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sacro","description":"Center name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"motor":{"type":"boolean","example":true,"description":"Whether this is a motor center."},"awareness":{"type":"boolean","example":false,"description":"Whether this is an awareness center."},"definedMeaning":{"type":"string","example":"Sustainable life force and work energy. A reliable gut response that guides what to engage with.","description":"What this center means when defined: a consistent, reliable energy or awareness."},"undefinedMeaning":{"type":"string","example":"No consistent access to work energy. Learns when enough is enough rather than driving to exhaustion.","description":"What this center means when undefined and open: a place of conditioning and learning."}},"required":["id","name","motor","awareness","definedMeaning","undefinedMeaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/profile":{"post":{"operationId":"calculateProfile","tags":["Human Design"],"summary":"Calculate the Human Design profile and line keynotes","description":"Calculate the Human Design profile for a birth moment: the conscious Personality Sun line over the unconscious Design Sun line, with the keynote for each. The profile is the geometry of the life role, for example 5/1 the Heretic Investigator. Verified against NASA JPL Horizons positions.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"Profile string, the two line numbers, and line keynotes","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"string","example":"5/1","description":"Profile in conscious/unconscious form, the Personality Sun line over the Design Sun line."},"personalityLine":{"type":"number","example":5,"description":"Line number from 1 to 6 of the conscious Personality Sun."},"designLine":{"type":"number","example":1,"description":"Line number from 1 to 6 of the unconscious Design Sun."},"personalityKeynote":{"type":"string","example":"Heretic: a universalizing, practical force others project expectations onto.","description":"Keynote of the Personality line, the conscious half of the profile."},"designKeynote":{"type":"string","example":"Investigator: builds a secure foundation through study before acting.","description":"Keynote of the Design line, the unconscious half of the profile."}},"required":["profile","personalityLine","designLine","personalityKeynote","designKeynote"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/human-design/variables":{"post":{"operationId":"calculateVariables","tags":["Human Design"],"summary":"Calculate Human Design Variables - The four arrows and Color, Tone, Base substructure","description":"Calculate the four Human Design Variable arrows for a birth moment: Determination and Environment on the design side, Perspective and Motivation on the personality side. Each arrow returns its Color, Tone, and Base numbers from the hexagram-line substructure, the left or right direction set by the Tone, and the sourced Color and direction labels. This is the advanced Rave Variables and Primary Health System layer beneath Type, Strategy, Authority, and Profile. Color, Tone, and Base shift with tiny differences in birth time, so each arrow carries a confidence flag that turns false near a Color or Tone boundary, and a precise birth time is essential. Built for Human Design apps offering PHS, diet, environment, and Rave Psychology readings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. The anchor for both the Personality activations at birth and the Design activations 88 degrees of solar arc earlier."},"time":{"type":"string","format":"time","example":"13:00:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters: the profile lines and gate boundaries shift with the exact minute of birth."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the bodygraph, which depends only on ecliptic longitudes. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the bodygraph. Defaults to 0."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node activations. True is what professional Human Design software uses (HumanDesign.ai, Total Human Design) and is the value RoxyAPI verifies against, so leave it unset for a standard chart. It matters only when a node sits on a gate boundary, where the choice can move a node gate and, rarely, change the completed channels and therefore the type, authority or definition. If another calculator shows a different type, it is almost certainly using the mean node: pass \"mean\" to match it. Defaults to \"true\"."}},"required":["date","time","timezone"]}}}},"responses":{"200":{"description":"The four Variable arrows with substructure numbers, labels, and confidence flags","content":{"application/json":{"schema":{"type":"object","properties":{"arrows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"determination","description":"Stable arrow identifier. One of determination, environment, perspective, motivation."},"name":{"type":"string","example":"Determination","description":"Arrow name. Determination is the top-left arrow governing the Primary Health System and digestion, Environment the bottom-left arrow, Perspective the bottom-right arrow also called View, and Motivation the top-right arrow. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Determinación","description":"Arrow name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"layer":{"type":"string","example":"Primary Health System","description":"Which half of the advanced layer the arrow belongs to. Primary Health System covers the body-side Determination and Environment arrows, Rave Psychology covers the mind-side Perspective and Motivation arrows. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use layerLocalized for anything a reader sees."},"layerLocalized":{"type":"string","example":"Sistema de Salud Primario","description":"Layer name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"position":{"type":"string","example":"Top left","description":"Position of the arrow at the head of the bodygraph. One of Top left, Bottom left, Top right, Bottom right. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use positionLocalized for anything a reader sees."},"positionLocalized":{"type":"string","example":"Superior izquierda","description":"Arrow position name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"activation":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Activating body whose substructure feeds this arrow. Determination and Motivation come from the Sun, Environment and Perspective from the North Node. Always English, whatever the lang parameter says, so it stays safe to compare against in code and to key a glyph table on. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Activating body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"side":{"type":"string","example":"design","description":"Chart side of the activation. Determination and Environment come from the design side, Perspective and Motivation from the personality side. Always English, whatever the lang parameter says, so it stays safe to compare against in code."}},"required":["planet","side"],"description":"The single activation, body and chart side, that this arrow is derived from."},"color":{"type":"number","example":4,"description":"Color number from 1 to 6, the substructure level one octave finer than the line. Color selects the arrow theme, for example the determination family or the motivation."},"tone":{"type":"number","example":1,"description":"Tone number from 1 to 6, the substructure level beneath Color. Tone sets the arrow direction: tones 1 to 3 face left, tones 4 to 6 face right."},"base":{"type":"number","example":4,"description":"Base number from 1 to 5, the finest published subdivision of the wheel. Returned for completeness but treated as informational, since it is finer than most birth times can resolve."},"direction":{"type":"string","example":"left","description":"Arrow direction derived from the Tone. left for tones 1 to 3, right for tones 4 to 6."},"colorLabel":{"type":"string","example":"Touch","description":"Name of the Color theme for this arrow, for example a determination family such as Touch, an environment such as Mountains, a perspective such as Personal, or a motivation such as Hope. Always English, whatever the lang parameter says. Use colorLabelLocalized for anything a reader sees."},"colorLabelLocalized":{"type":"string","example":"Tacto","description":"Color theme name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"directionLabel":{"type":"string","example":"Active","description":"Keynote of the arrow direction for this arrow, for example Active or Passive for Determination, Focused or Peripheral for Perspective. Always English, whatever the lang parameter says. Use directionLabelLocalized for anything a reader sees."},"directionLabelLocalized":{"type":"string","example":"Activo","description":"Arrow direction keynote in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"description":{"type":"string","example":"The top left arrow, fed by the design Sun and Earth. It describes how the body is built to take in and break down nourishment, sensation, and information, and it sets the cognitive potential that rests on that intake.","description":"What this arrow is and what it governs."},"layerDescription":{"type":"string","example":"The body-side half of Variable, covering the Determination and Environment arrows. It addresses the form: the conditions under which the vehicle digests nourishment, and the place in which it meets least resistance.","description":"What the layer this arrow belongs to governs, the body side or the mind side."},"colorMeaning":{"type":"string","example":"Touch. Intake governed by contact and physical circumstance. What the body handles, and the state of the space it eats in, decide whether nourishment is absorbed or refused.","description":"Meaning of the Color for THIS arrow. The same Color number means something different under Determination than under Motivation, so this is the reading of colorLabel in context, not a generic gloss."},"toneMeaning":{"type":"string","example":"Security. The tonal architecture rests on a baseline of safety. What is sound, familiar, and survivable registers first, and everything built above it stands on that footing.","description":"Meaning of the Tone. The six Tones are shared across all four arrows: the arrow does not change the Tone, it changes what the Tone qualifies."},"directionMeaning":{"type":"string","example":"Active. Intake is filtered on the way in. The body engages nourishment and information with focus and structure, and works best under specific, deliberate conditions rather than open-ended variety.","description":"Meaning of the left or right direction for THIS arrow, the reading of directionLabel."},"baseName":{"type":"string","example":"Progressive","description":"Name of the Base. Informational only: the Base is finer than any civil birth time can resolve. Always English, whatever the lang parameter says. Use baseNameLocalized for anything a reader sees."},"baseNameLocalized":{"type":"string","example":"Progresivo","description":"Base name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"cognition":{"type":"object","properties":{"label":{"type":"string","example":"Smell","description":"Name of the Cognition, the strongest sense. One of six read off the Determination Tone: Smell, Taste, Outer Vision, Inner Vision, Feeling, Touch. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use labelLocalized for anything a reader sees."},"labelLocalized":{"type":"string","example":"Olfato","description":"Cognition name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"description":{"type":"string","example":"Smell. Immediate, pre-verbal recognition through the nose. The body reads safety and suitability in an instant, and does best taking in one source at a time rather than a crowded field.","description":"How this Cognition discriminates what is correct for the body, and the conditions that sharpen it. Renderable as the Cognition paragraph of a Variables or Primary Health System report."}},"required":["label","description"],"description":"Cognition, the strongest sense, read off the Determination Tone. Present on the determination arrow ONLY: no authority supports reading Cognition from the other three arrows, so it is omitted rather than invented."},"confident":{"type":"boolean","example":true,"description":"Whether this arrow is far enough from a Color or Tone boundary to be reliable. When false the activation sits on a knife edge where the Color label or the arrow direction could flip with a more precise birth time, and the arrow should not be presented as fact."}},"required":["key","name","layer","position","activation","color","tone","base","direction","colorLabel","directionLabel","description","layerDescription","colorMeaning","toneMeaning","directionMeaning","baseName","confident"]},"description":"The four Variable arrows: Determination and Environment from the design side, Perspective and Motivation from the personality side. Together they form the Rave Variables / Primary Health System layer that sits beneath Type, Strategy, Authority, and Profile."},"confident":{"type":"boolean","example":true,"description":"True only when all four arrows are confident. A single knife-edge arrow makes the whole configuration uncertain."},"confidenceMarginDeg":{"type":"number","example":0.00274,"description":"Boundary margin in degrees of ecliptic longitude used for the per-arrow confidence flag, the solar arc over a few minutes of clock time. An activation within this distance of a Color or Tone boundary is flagged low-confidence."},"baseDescription":{"type":"string","example":"The finest substructure layer: one of five facets of the Personality Crystal, and the entry point for the imprint Tone and Color build on. Fixed across incarnation, and finer than any civil birth time resolves, so it is informational only.","description":"What the Base layer is. Returned once at the top level rather than repeated on every arrow, since the Base layer is the same concept for all four. No per-Base meaning is returned: every one in circulation traces back to a single origin, so it fails the two-source bar this package holds."}},"required":["arrows","confident","confidenceMarginDeg","baseDescription"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/life-path":{"post":{"operationId":"calculateLifePath","tags":["Numerology"],"summary":"Calculate Life Path number - Most important numerology calculation","description":"Calculate your Life Path number from your birth date using Pythagorean numerology. This is the most significant number in your numerology chart, revealing your life purpose, natural talents, and destiny path. Automatically detects Master Numbers (11, 22, 33) and Karmic Debt numbers (13, 14, 16, 19). Returns comprehensive interpretation including personality traits, strengths, challenges, career guidance, relationship compatibility, and spiritual insights. Perfect for numerology apps, birth chart calculators, life purpose discovery tools, personal development platforms, and astrology services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1-31)"}},"required":["year","month","day"]}}}},"responses":{"200":{"description":"Successfully calculated Life Path number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":5,"description":"Your Life Path number, the single most important number in Pythagorean numerology. Values range from 1 to 9 for single digits, or 11, 22, 33 for Master Numbers."},"calculation":{"type":"string","example":"Month: 7, Day: 15 → 1+5 = 6, Year: 1990 → 1+9+9+0 = 19 → 1+9 = 10 → 1+0 = 1 → 7+6+1=14 → 5","description":"Full step-by-step breakdown of the 3-Cycle Pythagorean reduction. Shows how month, day, and year each reduce independently before combining into the final Life Path number."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22, 33). Master Numbers carry amplified spiritual significance and are never reduced further."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Indicates whether a Karmic Debt number (13, 14, 16, or 19) appeared during the reduction chain. Karmic Debt reveals past-life challenges carried into this lifetime."},"karmicDebtNumber":{"type":"number","example":14,"description":"The specific Karmic Debt number detected during reduction, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life lesson requiring resolution."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Abuse of Freedom","description":"Title describing the karmic debt theme and core past-life pattern."},"challenge":{"type":"string","example":"Past life misuse of personal freedom, possibly through excess or manipulation.","description":"The specific challenge or pattern from past lives that must be confronted."},"resolution":{"type":"string","example":"Learn balance, moderation, and responsible use of freedom.","description":"Practical guidance for resolving the karmic debt and transforming the challenge into growth."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Adventurer","description":"Numerology archetype name for this Life Path number. Encapsulates the core identity and energy in a single phrase, such as \"The Leader\" for 1 or \"The Master Builder\" for 22."},"keywords":{"type":"array","items":{"type":"string"},"example":["adventurous","freedom","versatile","dynamic","curious"],"description":"Ten defining personality traits and energetic themes associated with this number. Useful for quick personality snapshots, tag clouds, and compatibility matching."},"description":{"type":"string","example":"In the span of single-digit numbers 1 to 9, 5 is the number in the exact middle. It acts as a go-between and a pivotal point of change...","description":"In-depth 300 to 500 word interpretation covering personality, purpose, and life themes. Written by numerology experts with decades of practice. Suitable for full-page readings and detailed reports."},"strengths":{"type":"array","items":{"type":"string"},"example":["Curious","Adaptable","Social"],"description":"Core strengths and positive qualities. Each entry includes a trait name followed by a detailed explanation of how it manifests in daily life."},"challenges":{"type":"array","items":{"type":"string"},"example":["Non-committal","Unreliable","Directionless"],"description":"Growth areas and shadow qualities to be aware of. Each entry names the challenge and explains its root cause and how to work through it constructively."},"career":{"type":"string","example":"Life Path 5 thrives in careers that offer freedom, variety, and constant stimulation...","description":"Tailored career guidance covering ideal industries, roles, and work environments. Includes specific job titles and explains why certain professional paths align with this number."},"relationships":{"type":"string","example":"Life Path 5 individuals are exciting, charming, and freedom-loving partners...","description":"Love, friendship, and family dynamics. Covers romantic compatibility with other Life Path numbers, communication style, and the key relationship lessons for this number."},"spirituality":{"type":"string","example":"Five is the rebel, the traveler, the agent of change. It vibrates with adventure and liberation...","description":"Spiritual path, soul lessons, and recommended practices. Explores the deeper purpose behind this number and offers guidance for personal growth and inner alignment."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/expression":{"post":{"operationId":"calculateExpression","tags":["Numerology"],"summary":"Calculate Expression number - Natural talents and life goals","description":"Calculate your Expression (Destiny) number from your full birth name using Pythagorean numerology. This number reveals your natural talents, abilities, and life goals. It shows what you came here to do and what tools you have to accomplish your life purpose. Returns comprehensive interpretation including personality traits, career paths, relationship dynamics, and spiritual insights. Automatically detects Master Numbers (11, 22, 33). Perfect for name numerology apps, career guidance tools, personal development platforms, and talent assessment services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name (first, middle, last)"}},"required":["fullName"]}}}},"responses":{"200":{"description":"Successfully calculated Expression number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":7,"description":"Expression number (also called Destiny number) derived from all letters in the full birth name. Reveals natural talents, abilities, and the goals you are meant to achieve. Values: 1 to 9, 11, 22, or 33."},"calculation":{"type":"string","example":"1+6+8+5 + 5+9+3+3+9+1+4 + 1+4+9+2+8 = 78 → 7+8 = 15 → 1+5 = 6","description":"Full Pythagorean letter-to-number conversion showing every letter value in the birth name, grouped by word, then summed and reduced to the final Expression number."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Single-digit (1 to 9) or Master Number (11, 22, 33). Master Numbers in the Expression position indicate extraordinary innate talent that demands conscious development."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Whether a Karmic Debt number (13, 14, 16, 19) appeared during the name reduction. Indicates inherited challenges embedded in your given name."},"karmicDebtNumber":{"type":"number","example":14,"description":"Specific Karmic Debt number found during reduction. Each debt (13, 14, 16, 19) points to a distinct lesson woven into the talents your name bestows."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Abuse of Freedom","description":"Title describing the karmic debt theme. Identifies the core past-life pattern that this debt number carries forward."},"challenge":{"type":"string","example":"Past life misuse of personal freedom, possibly through excess or manipulation.","description":"The specific challenge or pattern from past lives that must be confronted. Explains the root cause of recurring obstacles."},"resolution":{"type":"string","example":"Learn balance, moderation, and responsible use of freedom.","description":"Practical guidance for resolving the karmic debt. Actionable steps for transforming the inherited challenge into growth."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Includes the debt theme, the inherited challenge, and guidance for resolution. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Seeker","description":"Numerology archetype for this Expression number. Captures the essence of your natural abilities, such as \"The Communicator\" for 3 or \"The Master Intuitive\" for 11."},"keywords":{"type":"array","items":{"type":"string"},"example":["analytical","spiritual","wise","introspective","perfectionist"],"description":"Defining traits and talent themes for this Expression number. Ideal for personality profiles, compatibility engines, and talent-matching features."},"description":{"type":"string","example":"People with a 7 Expression number have a natural gift for analysis and investigation...","description":"Expert-written 300 to 500 word interpretation of the natural abilities, life mission, and destiny encoded in your birth name. Covers how these talents manifest across life stages."},"strengths":{"type":"array","items":{"type":"string"},"example":["Deep thinking","Intuition","Research ability","Spiritual insight"],"description":"Natural talents and innate gifts. Each strength includes a detailed explanation of how it shows up in work, relationships, and personal growth."},"challenges":{"type":"array","items":{"type":"string"},"example":["Aloofness","Over-analysis","Skepticism"],"description":"Shadow side of your talents and areas requiring conscious effort. Each challenge explains its root cause and practical strategies for transformation."},"career":{"type":"string","example":"Life Path 7 excels in careers that reward deep thinking, research, and intellectual exploration...","description":"Professional guidance aligned with your natural Expression talents. Covers ideal industries, specific roles, and the work environments where you will thrive."},"relationships":{"type":"string","example":"Life Path 7 individuals are introspective, thoughtful partners who seek deep connections...","description":"How your Expression number shapes love, friendship, and family bonds. Includes compatibility insights with other numbers and communication patterns."},"spirituality":{"type":"string","example":"Seven is on a great quest for truth and meaning, the most spiritual of all numbers...","description":"The spiritual dimension of your Expression energy. Explores soul lessons, recommended practices, and the deeper purpose your talents are meant to serve."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/bridge":{"post":{"operationId":"calculateBridgeNumbers","tags":["Numerology"],"summary":"Calculate Bridge Numbers - Harmonize different aspects of personality","description":"Calculate three Bridge Numbers that reveal the adjustments needed to create harmony between different aspects of your numerology profile. Bridge Numbers are the absolute difference between pairs of core numbers: Life Path and Expression, Expression and Personality, Expression and Soul Urge. A Bridge of 0 means the two aspects are already aligned. Higher bridges (1 to 8) indicate greater tension and provide specific guidance on what changes to make. Bridge Numbers are essential for personal development, coaching applications, self-improvement platforms, and AI-powered personality analysis tools. Requires both a full birth name and birth date to calculate all four core numbers (Life Path, Expression, Soul Urge, Personality) internally before deriving the bridges.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full legal birth name as it appears on the birth certificate. Used to calculate Expression, Soul Urge, and Personality numbers. Include first, middle, and last names separated by spaces."},"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year between 100 and 2100. Used to calculate the Life Path number via Pythagorean reduction."},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1 to 12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1 to 31)"}},"required":["fullName","year","month","day"]}}}},"responses":{"200":{"description":"Successfully calculated three Bridge Numbers with actionable harmony guidance","content":{"application/json":{"schema":{"type":"object","properties":{"lifePathExpression":{"type":"object","properties":{"bridge":{"type":"integer","minimum":0,"maximum":8,"example":3,"description":"Bridge number (0 to 8). The absolute difference between two core numerology numbers after reducing master numbers to single digits. 0 means the two aspects are already in natural harmony. Higher values indicate greater tension requiring conscious adjustment."},"from":{"type":"object","properties":{"name":{"type":"string","example":"Life Path","description":"Name of the first core number in this bridge pair. Identifies which aspect of personality or destiny is being compared."},"number":{"type":"number","example":5,"description":"The reduced single-digit value (1 to 9) of the first core number used in the bridge calculation."}},"required":["name","number"]},"to":{"type":"object","properties":{"name":{"type":"string","example":"Expression","description":"Name of the second core number in this bridge pair. Identifies the other aspect of personality or destiny being compared."},"number":{"type":"number","example":8,"description":"The reduced single-digit value (1 to 9) of the second core number used in the bridge calculation."}},"required":["name","number"]},"meaning":{"type":"string","example":"Focus on developing self-discipline and a consistent work ethic. Channel your creative ideas into structured plans with clear milestones. Regular routines and organized habits will help you align your inner vision with your outer expression.","description":"Actionable guidance for bridging the gap between these two aspects of your numerology profile. Explains what adjustments to make to bring these energies into harmony."}},"required":["bridge","from","to","meaning"],"description":"Bridge between Life Path and Expression numbers. Reveals the gap between your destined life purpose (from birth date) and your natural talents and abilities (from birth name). A high bridge here means your innate skills may not directly serve your life mission without conscious effort."},"expressionPersonality":{"type":"object","properties":{"bridge":{"type":"integer","minimum":0,"maximum":8,"example":3,"description":"Bridge number (0 to 8). The absolute difference between two core numerology numbers after reducing master numbers to single digits. 0 means the two aspects are already in natural harmony. Higher values indicate greater tension requiring conscious adjustment."},"from":{"type":"object","properties":{"name":{"type":"string","example":"Life Path","description":"Name of the first core number in this bridge pair. Identifies which aspect of personality or destiny is being compared."},"number":{"type":"number","example":5,"description":"The reduced single-digit value (1 to 9) of the first core number used in the bridge calculation."}},"required":["name","number"]},"to":{"type":"object","properties":{"name":{"type":"string","example":"Expression","description":"Name of the second core number in this bridge pair. Identifies the other aspect of personality or destiny being compared."},"number":{"type":"number","example":8,"description":"The reduced single-digit value (1 to 9) of the second core number used in the bridge calculation."}},"required":["name","number"]},"meaning":{"type":"string","example":"Focus on developing self-discipline and a consistent work ethic. Channel your creative ideas into structured plans with clear milestones. Regular routines and organized habits will help you align your inner vision with your outer expression.","description":"Actionable guidance for bridging the gap between these two aspects of your numerology profile. Explains what adjustments to make to bring these energies into harmony."}},"required":["bridge","from","to","meaning"],"description":"Bridge between Expression and Personality numbers. Reveals the gap between your true talents (all letters) and how others perceive you (consonants only). A high bridge means others may not see your real capabilities, requiring you to present yourself more authentically."},"expressionSoulUrge":{"type":"object","properties":{"bridge":{"type":"integer","minimum":0,"maximum":8,"example":3,"description":"Bridge number (0 to 8). The absolute difference between two core numerology numbers after reducing master numbers to single digits. 0 means the two aspects are already in natural harmony. Higher values indicate greater tension requiring conscious adjustment."},"from":{"type":"object","properties":{"name":{"type":"string","example":"Life Path","description":"Name of the first core number in this bridge pair. Identifies which aspect of personality or destiny is being compared."},"number":{"type":"number","example":5,"description":"The reduced single-digit value (1 to 9) of the first core number used in the bridge calculation."}},"required":["name","number"]},"to":{"type":"object","properties":{"name":{"type":"string","example":"Expression","description":"Name of the second core number in this bridge pair. Identifies the other aspect of personality or destiny being compared."},"number":{"type":"number","example":8,"description":"The reduced single-digit value (1 to 9) of the second core number used in the bridge calculation."}},"required":["name","number"]},"meaning":{"type":"string","example":"Focus on developing self-discipline and a consistent work ethic. Channel your creative ideas into structured plans with clear milestones. Regular routines and organized habits will help you align your inner vision with your outer expression.","description":"Actionable guidance for bridging the gap between these two aspects of your numerology profile. Explains what adjustments to make to bring these energies into harmony."}},"required":["bridge","from","to","meaning"],"description":"Bridge between Expression and Soul Urge numbers. Reveals the gap between your outward talents (all letters) and your deepest inner desires (vowels only). A high bridge means what you are good at may differ from what your soul truly craves, calling for realignment."}},"required":["lifePathExpression","expressionPersonality","expressionSoulUrge"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/soul-urge":{"post":{"operationId":"calculateSoulUrge","tags":["Numerology"],"summary":"Calculate Soul Urge number - Inner motivations and desires","description":"Calculate your Soul Urge (Heart Desire) number from the vowels in your birth name using Pythagorean numerology. This number reveals your innermost desires, motivations, and what your soul truly wants to experience. It shows what drives you from within, your emotional needs, and what brings you fulfillment. Returns comprehensive interpretation including personality traits, emotional needs, relationship desires, and spiritual longings. Automatically detects Master Numbers (11, 22, 33). Perfect for self-discovery apps, emotional intelligence tools, relationship counseling platforms, and personal development services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name (vowels will be extracted)"}},"required":["fullName"]}}}},"responses":{"200":{"description":"Successfully calculated Soul Urge number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":6,"description":"Your Soul Urge number (also called Heart Desire number), revealing your innermost motivations and what your soul truly craves. Values range from 1 to 9 for single digits, or 11, 22, 33 for Master Numbers."},"calculation":{"type":"string","example":"6+9+1 + 9+9+1 + 9 = 44 → 4+4 = 8","description":"Full step-by-step Pythagorean reduction using only the vowels (A, E, I, O, U) from the birth name. Shows each vowel mapped to its numeric value, grouped by word, then summed and reduced to the final Soul Urge number."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22, 33). Master Numbers in the Soul Urge position indicate a soul with amplified spiritual longing and heightened inner sensitivity."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Indicates whether a Karmic Debt number (13, 14, 16, or 19) appeared during the vowel reduction chain. Karmic Debt in the Soul Urge reveals past-life emotional patterns and unresolved inner desires carried into this lifetime."},"karmicDebtNumber":{"type":"number","example":13,"description":"The specific Karmic Debt number detected during the vowel reduction, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life emotional lesson that influences your deepest desires and motivations."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Laziness and Negativity","description":"Title describing the karmic debt theme and core past-life pattern."},"challenge":{"type":"string","example":"Past life tendency toward shortcuts and laziness.","description":"The specific challenge from past lives that must be confronted."},"resolution":{"type":"string","example":"Learn discipline, hard work, and persistence.","description":"Practical guidance for resolving the karmic debt."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Nurturer","description":"Numerology archetype for this Soul Urge number. Reveals the deepest inner motivation, such as \"The Seeker\" for 7 or \"The Master Teacher\" for 33."},"keywords":{"type":"array","items":{"type":"string"},"example":["caring","responsible","harmonious","protective","service"],"description":"Core emotional drives and inner motivations for this Soul Urge. Useful for understanding hidden desires, emotional needs, and what truly fulfills someone at the deepest level."},"description":{"type":"string","example":"People with a 6 Soul Urge number have a deep desire to nurture and care for others...","description":"Expert-written 300 to 500 word exploration of the inner self, hidden desires, and emotional landscape. Reveals what the heart truly craves beneath the surface persona."},"strengths":{"type":"array","items":{"type":"string"},"example":["Compassion","Responsibility","Harmony creation","Service orientation"],"description":"Emotional superpowers and inner gifts. Each strength describes how it shapes decision-making, relationships, and the pursuit of personal fulfillment."},"challenges":{"type":"array","items":{"type":"string"},"example":["Over-responsibility","Martyrdom","Interference"],"description":"Inner shadows and emotional patterns to balance. Explains how each challenge manifests when the Soul Urge energy is overextended or repressed."},"career":{"type":"string","example":"Life Path 6 excels in careers built around service, nurturing, and creating harmony...","description":"Career paths that satisfy your deepest emotional needs. Focuses on work that feeds the soul rather than just the resume, aligned with inner fulfillment."},"relationships":{"type":"string","example":"Life Path 6 individuals are devoted, nurturing, and deeply romantic partners...","description":"How your Soul Urge shapes what you need from love, friendship, and family. Covers emotional compatibility, attachment style, and the key to feeling truly seen."},"spirituality":{"type":"string","example":"With the beautiful number 6, it is all about love and unconditional compassion...","description":"The spiritual hunger at your core. Explores what your soul is seeking in this lifetime and the practices that bring you closest to inner peace and alignment."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/personality":{"post":{"operationId":"calculatePersonality","tags":["Numerology"],"summary":"Calculate Personality number - How others perceive you","description":"Calculate your Personality number from the consonants in your birth name using Pythagorean numerology. This number reveals how others perceive you, your outer personality, and first impressions you make. It represents the mask you show the world and your social persona. Returns comprehensive interpretation including public image, social dynamics, professional presence, and relationship first impressions. Automatically detects Master Numbers (11, 22, 33). Perfect for personal branding apps, social skills training, professional development platforms, and communication coaching services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name (consonants will be extracted)"}},"required":["fullName"]}}}},"responses":{"200":{"description":"Successfully calculated Personality number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":9,"description":"Your Personality number, derived from the consonants in your birth name. Reveals how others perceive you, your outer persona, and the first impression you project. Values range from 1 to 9 for single digits, or 11, 22, 33 for Master Numbers."},"calculation":{"type":"string","example":"1+8+5 + 5+3+3+4 + 1+4+2+8 = 44 → 4+4 = 8","description":"Full step-by-step Pythagorean reduction using only the consonants from the birth name. Shows each consonant mapped to its numeric value, grouped by word, then summed and reduced to the final Personality number."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22, 33). Master Numbers in the Personality position indicate a powerful outer presence that others immediately sense, carrying heightened charisma and public influence."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Indicates whether a Karmic Debt number (13, 14, 16, or 19) appeared during the consonant reduction chain. Karmic Debt in the Personality position reveals past-life patterns that influence how others perceive you and the social challenges you must overcome."},"karmicDebtNumber":{"type":"number","example":16,"description":"The specific Karmic Debt number detected during the consonant reduction, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life lesson that shapes your public image and social interactions."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Ego and Relationships","description":"Title describing the karmic debt theme and core past-life pattern."},"challenge":{"type":"string","example":"Past life issues with ego, pride, or relationship destruction.","description":"The specific challenge from past lives that must be confronted."},"resolution":{"type":"string","example":"Learn humility, compassion, and authentic connection.","description":"Practical guidance for resolving the karmic debt."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Humanitarian","description":"Numerology archetype for this Personality number. Represents the outer mask you show the world, such as \"The Builder\" for 4 or \"The Powerhouse\" for 8."},"keywords":{"type":"array","items":{"type":"string"},"example":["compassionate","charismatic","idealistic","generous","wise"],"description":"Traits that define your public persona and first impression. These are the qualities others perceive before they get to know the real you."},"description":{"type":"string","example":"People with a 9 Personality number project warmth and compassion to others...","description":"Expert-written 300 to 500 word analysis of the outer personality, social presence, and the image you project to the world. Reveals the gap between how others see you and who you truly are."},"strengths":{"type":"array","items":{"type":"string"},"example":["Charisma","Compassion","Wisdom","Universal understanding"],"description":"Your strongest social assets and public-facing gifts. These qualities shape how you are received in professional settings, social gatherings, and first meetings."},"challenges":{"type":"array","items":{"type":"string"},"example":["Emotional distance","Impracticality","Scattered energy"],"description":"Blind spots in your public persona. Patterns others notice that you may not, including defense mechanisms and image-management tendencies that can limit authentic connection."},"career":{"type":"string","example":"Life Path 9 excels in careers that serve the greater good and allow creative expression...","description":"How your outward presence shapes professional opportunities. Covers the industries, roles, and environments where your public image creates the greatest advantage."},"relationships":{"type":"string","example":"Life Path 9 individuals are compassionate, devoted, and emotionally generous partners...","description":"First impressions in love and social dynamics. Explores how your Personality number attracts certain partners, sets relationship expectations, and influences group dynamics."},"spirituality":{"type":"string","example":"The number 9 shines its light of love and wisdom into the world, guiding others toward awakening...","description":"The spiritual energy you radiate to others. Explores how your outer presence serves as a channel for deeper purpose, and what your public path reveals about your soul mission."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/birth-day":{"post":{"operationId":"calculateBirthDay","tags":["Numerology"],"summary":"Calculate Birth Day number - Special talents from day of birth","description":"Calculate your Birth Day number from the day you were born (1-31) using Pythagorean numerology. This number reveals special talents and abilities you possess from birth. It shows natural gifts that can help you achieve your life purpose. Returns comprehensive interpretation including innate talents, natural abilities, career advantages, and how to leverage your special gifts. Automatically detects Master Numbers (11, 22) and reduces double-digit days. Perfect for talent discovery apps, career counseling platforms, personal development services, and skill assessment tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, and 22.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":31,"example":23,"description":"Day of birth (1-31)"}},"required":["day"]}}}},"responses":{"200":{"description":"Successfully calculated Birth Day number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":5,"description":"Your Birth Day number, revealing the special talents and innate abilities you carry from the day you were born. Values range from 1 to 9 for single digits, or 11, 22 for Master Numbers (days 11 and 22 are never reduced)."},"calculation":{"type":"string","example":"23 → 2+3 = 5","description":"Step-by-step digit reduction of the birth day. Single-digit days (1 to 9) remain as-is, Master Number days (11, 22) are preserved, and all other double-digit days are reduced by summing their digits."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22). Master Numbers in the Birth Day position indicate extraordinary innate gifts that are available from birth and demand conscious development."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Indicates whether a Karmic Debt number (13, 14, 16, or 19) corresponds to the birth day. Karmic Debt in the Birth Day position reveals past-life challenges woven directly into your natural talents, influencing how your gifts manifest."},"karmicDebtNumber":{"type":"number","example":19,"description":"The specific Karmic Debt number detected from the birth day, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life lesson embedded in the talents your birth day bestows."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Power Abuse","description":"Title describing the karmic debt theme and core past-life pattern."},"challenge":{"type":"string","example":"Past life misuse of power or authority, possibly selfishness.","description":"The specific challenge from past lives that must be confronted."},"resolution":{"type":"string","example":"Learn to use power wisely and share it with others.","description":"Practical guidance for resolving the karmic debt."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Adventurer","description":"Numerology archetype for this Birth Day number. Represents the specific talent or gift you brought into this life, like \"The Nurturer\" for 6 or \"The Seeker\" for 7."},"keywords":{"type":"array","items":{"type":"string"},"example":["versatile","adaptable","communicative","adventurous","dynamic"],"description":"Innate talents and natural aptitudes encoded in your birth day. These gifts are available from birth and become more refined with age."},"description":{"type":"string","example":"People born on a 5 Birth Day have natural versatility and adaptability...","description":"Expert-written 300 to 500 word reading of the special abilities your birth day bestows. Covers how these gifts complement your Life Path and Expression numbers."},"strengths":{"type":"array","items":{"type":"string"},"example":["Adaptability","Communication","Quick learning","Versatility"],"description":"Natural-born strengths that come effortlessly. These are the talents you can rely on even without formal training or conscious development."},"challenges":{"type":"array","items":{"type":"string"},"example":["Restlessness","Scattered energy","Commitment avoidance"],"description":"The flip side of your gifts. Each challenge explains how an overreliance on natural talent can become a liability without conscious balance."},"career":{"type":"string","example":"Life Path 5 thrives in careers that offer freedom, variety, and constant stimulation...","description":"Professional paths where your birth day talents create an immediate advantage. Covers specific roles, industries, and work styles that align with your innate abilities."},"relationships":{"type":"string","example":"Life Path 5 individuals are exciting, charming, and freedom-loving partners...","description":"How your birth day gifts shape the way you connect with others. Covers romantic chemistry, friendship dynamics, and the relationship patterns rooted in your natural temperament."},"spirituality":{"type":"string","example":"Five is the rebel, the traveler, the agent of change...","description":"The spiritual dimension of your natural gifts. Explores how your birth day talents serve a higher purpose and the practices that help you channel them with intention."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/maturity":{"post":{"operationId":"calculateMaturity","tags":["Numerology"],"summary":"Calculate Maturity number - Who you become in later life","description":"Calculate your Maturity (Realization) number by adding Life Path and Expression numbers using Pythagorean numerology. This number reveals who you become in the second half of life, typically manifesting after age 35-40. It shows the ultimate goal of personal development and mature self-expression. Returns comprehensive interpretation including life transformation, mature personality, later-life purpose, and wisdom development. Automatically detects Master Numbers (11, 22, 33). Perfect for life coaching apps, midlife guidance platforms, personal development services, and aging wisdom tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lifePath":{"type":"integer","minimum":1,"maximum":33,"example":5,"description":"Your Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided."},"expression":{"type":"integer","minimum":1,"maximum":33,"example":7,"description":"Your Expression number (1-9, 11, 22, 33). Optional if fullName is provided."},"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name to calculate Expression number automatically. Use instead of passing expression directly."},"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly."},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12). Required with year and day for automatic Life Path calculation."},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1-31). Required with year and month for automatic Life Path calculation."}}}}}},"responses":{"200":{"description":"Successfully calculated Maturity number with detailed interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":3,"description":"Your Maturity number (also called Realization number), revealing who you are becoming in the second half of life. Derived from the sum of your Life Path and Expression numbers. Values range from 1 to 9 for single digits, or 11, 22, 33 for Master Numbers."},"calculation":{"type":"string","example":"5 + 7 = 12 → 1+2 = 3","description":"Full step-by-step reduction showing Life Path plus Expression combined and reduced to the final Maturity number. This synthesis represents the convergence of your life purpose and natural talents into mature wisdom."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22, 33). Master Numbers in the Maturity position indicate a powerful late-life awakening with extraordinary potential for spiritual leadership and legacy."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Indicates whether a Karmic Debt number (13, 14, 16, or 19) appeared during the Life Path plus Expression reduction. Karmic Debt in the Maturity position reveals past-life lessons that surface during midlife transformation, typically after age 35 to 40."},"karmicDebtNumber":{"type":"number","example":14,"description":"The specific Karmic Debt number detected during the Maturity reduction, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life challenge that becomes especially prominent as you enter the second half of life."},"karmicDebtMeaning":{"type":"object","properties":{"description":{"type":"string","example":"Karmic Debt of Abuse of Freedom","description":"Title describing the karmic debt theme and core past-life pattern."},"challenge":{"type":"string","example":"Past life misuse of personal freedom, possibly through excess or manipulation.","description":"The specific challenge from past lives that must be confronted."},"resolution":{"type":"string","example":"Learn balance, moderation, and responsible use of freedom.","description":"Practical guidance for resolving the karmic debt."}},"required":["description","challenge","resolution"],"description":"Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Communicator","description":"Numerology archetype for the Maturity number. Reveals who you are becoming in the second half of life, such as \"The Builder\" for 4 or \"The Humanitarian\" for 9."},"keywords":{"type":"array","items":{"type":"string"},"example":["expressive","creative","joyful","communicative","optimistic"],"description":"Emerging traits and qualities that strengthen after age 35 to 40. These energies gradually integrate into your personality as you mature."},"description":{"type":"string","example":"People with a 3 Maturity number grow into creative and joyful expression...","description":"Expert-written 300 to 500 word guide to the person you are evolving into. The Maturity number is the sum of Life Path and Expression, representing the wisdom gained through lived experience."},"strengths":{"type":"array","items":{"type":"string"},"example":["Creative expression","Communication","Joy","Social charm"],"description":"Late-blooming strengths that emerge with age and experience. These are the gifts that become your greatest assets in the second half of life."},"challenges":{"type":"array","items":{"type":"string"},"example":["Scattered energy","Superficiality","Over-sensitivity"],"description":"Growth areas to watch as Maturity energy intensifies. Understanding these early helps you navigate the transition with awareness and grace."},"career":{"type":"string","example":"Life Path 3 thrives in creative fields where self-expression and communication take center stage...","description":"Career evolution and professional reinvention for the second act. Covers industries, roles, and pursuits that align with your mature energy and accumulated wisdom."},"relationships":{"type":"string","example":"Life Path 3 individuals are charming, playful, and expressive partners...","description":"How your relationships deepen and transform as Maturity energy takes hold. Covers evolving partnership needs, family dynamics, and the relationship wisdom that comes with age."},"spirituality":{"type":"string","example":"Three vibrates with the energy of the Divine Child: playful, imaginative, and endlessly curious...","description":"Spiritual awakening in the mature years. Explores the deeper meaning that emerges when life experience meets the Maturity number, and practices for this transformative phase."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","calculation","type","hasKarmicDebt","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/karmic-lessons":{"post":{"operationId":"analyzeKarmicLessons","tags":["Numerology"],"summary":"Analyze Karmic Lessons - Life lessons from missing numbers","description":"Analyze your Karmic Lessons from your birth name using Pythagorean numerology. Karmic lessons are indicated by numbers missing from your name (numbers 1-9 that do not appear). These represent challenges you came to learn and skills you need to develop in this lifetime. Returns comprehensive analysis including missing numbers, specific lessons for each, challenges to overcome, and practical guidance for development. Perfect for spiritual growth apps, personal development platforms, life coaching services, and self-improvement tools. Get detailed lesson descriptions, development strategies, and practical exercises for each missing number.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name to analyze for missing numbers"}},"required":["fullName"]}}}},"responses":{"200":{"description":"Successfully analyzed karmic lessons with development guidance","content":{"application/json":{"schema":{"type":"object","properties":{"missingNumbers":{"type":"array","items":{"type":"number"},"example":[2,4,8],"description":"Numbers missing from name (karmic lessons)"},"lessons":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":2,"description":"Missing number"},"lesson":{"type":"string","example":"Learn cooperation, patience, and sensitivity","description":"Core lesson summary"},"description":{"type":"string","example":"Missing number 2 indicates challenges with teamwork and relationships...","description":"Detailed lesson explanation"},"howToOvercome":{"type":"string","example":"Practice active listening, work on group projects, develop empathy...","description":"Practical guidance for developing this quality"}},"required":["number","lesson","description","howToOvercome"]}},"presentNumbers":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"How many letters of the full birth name reduce to this number. A number absent from the map has a count of zero, which is exactly what makes it a karmic lesson."},"example":{"1":3,"3":2,"5":4,"6":1,"7":2,"9":2},"description":"Count of each number present in name"}},"required":["missingNumbers","lessons","presentNumbers"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/karmic-debt":{"post":{"operationId":"checkKarmicDebt","tags":["Numerology"],"summary":"Detect Karmic Debt numbers - Past life challenges (13, 14, 16, 19)","description":"Check for Karmic Debt numbers (13, 14, 16, 19) in Life Path, Expression, Soul Urge, or Personality calculations using Pythagorean numerology. Karmic debt indicates challenges carried from past lives that must be resolved in this lifetime. These numbers appear during reduction and represent specific lessons and tests. Returns comprehensive analysis including debt descriptions, challenges to overcome, and resolution guidance. Perfect for spiritual growth apps, karmic astrology platforms, past life exploration services, and personal transformation tools. Get detailed meanings for all four karmic debt numbers with practical resolution strategies.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year (checks Life Path)"},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (checks Life Path)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (checks Life Path)"},"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name (checks Expression, Soul Urge, Personality)"}}}}}},"responses":{"200":{"description":"Successfully detected karmic debt with detailed meanings","content":{"application/json":{"schema":{"type":"object","properties":{"hasKarmicDebt":{"type":"boolean","example":true,"description":"Whether any karmic debt numbers were detected"},"debtNumbers":{"type":"array","items":{"type":"number"},"example":[14,16],"description":"All karmic debt numbers found (13, 14, 16, 19)"},"meanings":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":14,"description":"Karmic debt number"},"description":{"type":"string","example":"Karmic Debt of Abuse of Freedom","description":"Debt title and nature"},"challenge":{"type":"string","example":"Past life misuse of personal freedom through excess or manipulation...","description":"Detailed explanation of past life issue and current challenges"},"resolution":{"type":"string","example":"Learn balance, moderation, and responsible use of freedom...","description":"Guidance for resolving karmic debt in this lifetime"}},"required":["number","description","challenge","resolution"]}},"message":{"type":"string","example":"Karmic debt is present in the core numbers: 14, 16. Each of these represents a concentrated area of unresolved experience carried from prior incarnations, requiring deliberate attention and sustained work in this lifetime to move through.","description":"Human-readable summary. Explains what the karmic debt findings mean or provides a positive affirmation when no debt is found."}},"required":["hasKarmicDebt","debtNumbers","meanings","message"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/personal-day":{"post":{"operationId":"calculatePersonalDay","tags":["Numerology"],"summary":"Calculate Personal Day - Daily personalized numerology forecast","description":"Calculate your Personal Day number from birth month, day, and a target date. Personal Day is the most granular cycle in Pythagorean numerology, revealing the specific energy and theme for a single calendar day personalized to you. Unlike generic daily numbers, this is based on YOUR birth data combined with the calendar date. Returns the daily theme, actionable guidance, and parent month and year context. Perfect for daily push notifications, morning briefings, calendar widget integrations, daily content generation, and life coaching tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":18,"description":"Birth day (1-31)"},"targetDate":{"type":"string","format":"date","example":"2026-04-04","description":"Target date in YYYY-MM-DD format. Defaults to today (UTC)."}},"required":["month","day"]}}}},"responses":{"200":{"description":"Successfully calculated Personal Day with forecast","content":{"application/json":{"schema":{"type":"object","properties":{"personalDay":{"type":"number","example":7,"description":"Personal Day number (1-9). The most granular numerology cycle, revealing the energy and theme for this specific day based on your birth data."},"theme":{"type":"string","example":"Rest and Reflection","description":"Central theme for this Personal Day. A concise label capturing the dominant energy of the day."},"guidance":{"type":"string","example":"Step back from external demands and go inward. Reflect, meditate, study, or simply rest.","description":"Actionable daily guidance. Specific advice for how to work with the energy of this Personal Day."},"targetDate":{"type":"string","example":"2026-04-04","description":"The calendar date this forecast applies to in YYYY-MM-DD format."},"personalMonth":{"type":"number","example":3,"description":"The parent Personal Month number this day falls within."},"personalMonthTheme":{"type":"string","example":"Creative Expression","description":"Theme of the parent Personal Month, providing broader context for the daily forecast."},"personalYear":{"type":"number","example":8,"description":"The parent Personal Year number this day falls within."},"personalYearTheme":{"type":"string","example":"Power and Achievement","description":"Theme of the parent Personal Year, providing the broadest cycle context."}},"required":["personalDay","theme","guidance","targetDate","personalMonth","personalMonthTheme","personalYear","personalYearTheme"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/personal-month":{"post":{"operationId":"calculatePersonalMonth","tags":["Numerology"],"summary":"Calculate Personal Month - Monthly numerology forecast","description":"Calculate your Personal Month number from birth month, day, and a target year and month. Personal Month reveals the specific theme and energy influencing each calendar month within your Personal Year cycle. Returns the monthly theme, practical focus guidance, and the parent Personal Year context. Perfect for monthly forecast features, push notification content, calendar integrations, editorial monthly columns, and life coaching tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":18,"description":"Birth day (1-31)"},"year":{"type":"integer","minimum":2020,"maximum":2100,"example":2026,"description":"Target year for calculation (defaults to current year)"},"targetMonth":{"type":"integer","minimum":1,"maximum":12,"example":4,"description":"Target calendar month to forecast (1-12, defaults to current month)"}},"required":["month","day"]}}}},"responses":{"200":{"description":"Successfully calculated Personal Month with forecast","content":{"application/json":{"schema":{"type":"object","properties":{"personalMonth":{"type":"number","example":3,"description":"Personal Month number (1-9). Each month in the cycle carries specific energy and themes that guide decisions and focus."},"theme":{"type":"string","example":"Creative Expression","description":"Central theme for this Personal Month. A concise label capturing the dominant energy."},"focus":{"type":"string","example":"Express yourself creatively, socialize, and communicate. Writing, art, and public speaking are favored.","description":"Practical guidance for this month. Specific actions, areas of focus, and advice for making the most of this monthly energy."},"calendarMonth":{"type":"number","example":4,"description":"The calendar month this forecast applies to (1-12)."},"personalYear":{"type":"number","example":8,"description":"The parent Personal Year number this month falls within."},"personalYearTheme":{"type":"string","example":"Power and Achievement","description":"Theme of the parent Personal Year, providing broader context for the monthly forecast."}},"required":["personalMonth","theme","focus","calendarMonth","personalYear","personalYearTheme"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/personal-year":{"post":{"operationId":"calculatePersonalYear","tags":["Numerology"],"summary":"Calculate Personal Year - Annual cycle and forecast for current year","description":"Calculate your Personal Year number from your birth month, day, and current year using Pythagorean numerology. Personal Year runs in 9-year cycles (1-9) and reveals the theme, opportunities, and challenges for the current year. Each year has a specific energy and lessons. Returns comprehensive annual forecast including year theme, opportunities, challenges, and actionable advice. Perfect for yearly planning apps, life coaching platforms, astrology services, and personal development tools. Get detailed forecasts for all 9 Personal Year cycles with practical guidance.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1-31)"},"year":{"type":"integer","minimum":2020,"maximum":2100,"example":2025,"description":"Year to calculate (defaults to current year)"}},"required":["month","day"]}}}},"responses":{"200":{"description":"Successfully calculated Personal Year with forecast","content":{"application/json":{"schema":{"type":"object","properties":{"personalYear":{"type":"number","example":5,"description":"Personal Year number (1-9)"},"cycle":{"type":"string","example":"Year 5 of 9","description":"Position in the 9-year cycle"},"theme":{"type":"string","example":"Freedom and Change","description":"Main theme of the year"},"forecast":{"type":"string","example":"This is a year of freedom, change, and unexpected opportunities. You will feel restless and eager for new experiences...","description":"Detailed year forecast (200-300 words)"},"opportunities":{"type":"array","items":{"type":"string"},"example":["Travel and adventure","Career changes","New connections","Learning"],"description":"Key opportunities in this year"},"challenges":{"type":"array","items":{"type":"string"},"example":["Restlessness","Scattered energy","Impulsive decisions"],"description":"Challenges to navigate"},"advice":{"type":"string","example":"Embrace change and new experiences but maintain some stability. Stay flexible and open-minded...","description":"Practical guidance for navigating the year"}},"required":["personalYear","cycle","theme","forecast","opportunities","challenges","advice"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/compatibility":{"post":{"operationId":"calculateNumCompatibility","tags":["Numerology"],"summary":"Calculate Compatibility - Relationship dynamics between two people","description":"Calculate numerology compatibility between two people using Pythagorean numerology. Accepts two input modes per person: pre-calculated Life Path, Expression, and Soul Urge numbers, or raw name and birthdate for automatic calculation. You can mix modes across persons (e.g. numbers for person1, raw inputs for person2). Provides comprehensive relationship analysis with overall compatibility score (0-100), individual aspect compatibility (Life Path 50% weight, Expression 30%, Soul Urge 20%), relationship strengths, challenges, and practical advice. Uses detailed compatibility matrix for all number combinations. Perfect for dating apps, relationship counseling platforms, matchmaking services, and compatibility tools. Get actionable insights for improving relationship dynamics.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"lifePath":{"type":"integer","minimum":1,"maximum":33,"example":5,"description":"Person 1 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided."},"expression":{"type":"integer","minimum":1,"maximum":33,"example":7,"description":"Person 1 Expression number (1-9, 11, 22, 33). Optional if fullName is provided."},"soulUrge":{"type":"integer","minimum":1,"maximum":33,"example":6,"description":"Person 1 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided."},"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly."},"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly."},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12). Required with year and day for automatic Life Path calculation."},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1-31). Required with year and month for automatic Life Path calculation."}}},"person2":{"type":"object","properties":{"lifePath":{"type":"integer","minimum":1,"maximum":33,"example":3,"description":"Person 2 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided."},"expression":{"type":"integer","minimum":1,"maximum":33,"example":9,"description":"Person 2 Expression number (1-9, 11, 22, 33). Optional if fullName is provided."},"soulUrge":{"type":"integer","minimum":1,"maximum":33,"example":2,"description":"Person 2 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided."},"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"Jane Marie Doe","description":"Full birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly."},"year":{"type":"integer","minimum":100,"maximum":2100,"example":1992,"description":"Birth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly."},"month":{"type":"integer","minimum":1,"maximum":12,"example":3,"description":"Birth month (1-12). Required with year and day for automatic Life Path calculation."},"day":{"type":"integer","minimum":1,"maximum":31,"example":22,"description":"Birth day (1-31). Required with year and month for automatic Life Path calculation."}}}},"required":["person1","person2"]}}}},"responses":{"200":{"description":"Successfully calculated compatibility with detailed analysis","content":{"application/json":{"schema":{"type":"object","properties":{"overallScore":{"type":"number","example":78,"description":"Overall compatibility score (0-100)"},"rating":{"type":"string","example":"Very Compatible","description":"Compatibility rating: Highly Compatible, Very Compatible, Compatible, Moderately Compatible, or Challenging."},"lifePath":{"type":"object","properties":{"person1":{"type":"number","example":5,"description":"Person 1 Life Path number"},"person2":{"type":"number","example":3,"description":"Person 2 Life Path number"},"compatibility":{"type":"number","example":85,"description":"Life Path compatibility score (0-100)"},"description":{"type":"string","example":"5 and 3 create an exciting dynamic partnership...","description":"Detailed Life Path compatibility analysis"}},"required":["person1","person2","compatibility","description"]},"expression":{"type":"object","properties":{"person1":{"type":"number","example":7,"description":"Person 1 Expression number"},"person2":{"type":"number","example":9,"description":"Person 2 Expression number"},"compatibility":{"type":"number","example":70,"description":"Expression compatibility score (0-100)"},"description":{"type":"string","example":"7 and 9 share spiritual depth...","description":"Detailed Expression compatibility analysis"}},"required":["person1","person2","compatibility","description"]},"soulUrge":{"type":"object","properties":{"person1":{"type":"number","example":6,"description":"Person 1 Soul Urge number"},"person2":{"type":"number","example":2,"description":"Person 2 Soul Urge number"},"compatibility":{"type":"number","example":90,"description":"Soul Urge compatibility score (0-100)"},"description":{"type":"string","example":"6 and 2 have complementary emotional needs...","description":"Detailed Soul Urge compatibility analysis"}},"required":["person1","person2","compatibility","description"]},"strengths":{"type":"array","items":{"type":"string"},"example":["Complementary personalities","Shared values","Mutual growth support","Emotional harmony"],"description":"Key relationship strengths"},"challenges":{"type":"array","items":{"type":"string"},"example":["Different communication styles","Need for independence vs togetherness","Pace of life differences"],"description":"Potential relationship challenges"},"advice":{"type":"string","example":"This relationship thrives on mutual respect and space for individual growth. Focus on...","description":"Practical relationship advice"}},"required":["overallScore","rating","lifePath","expression","soulUrge","strengths","challenges","advice"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/chart":{"post":{"operationId":"generateNumerologyChart","tags":["Numerology"],"summary":"Generate Complete Numerology Chart - Full profile analysis","description":"Generate a comprehensive numerology chart combining all major calculations: Life Path, Expression, Soul Urge, Personality, Birth Day, Maturity, Karmic Lessons, Karmic Debt, and Personal Year. This single endpoint provides everything needed for a full numerology reading. Returns detailed interpretations for all numbers, karmic analysis, yearly forecast, and holistic summary. Perfect for numerology apps, complete reading services, birth chart generators, and comprehensive analysis tools. Save multiple API calls by getting the full chart in one request. Ideal for generating PDF reports or detailed user profiles.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"John William Smith","description":"Full birth name as it appears on the birth certificate. Used for all letter-based Pythagorean numerology calculations including Expression, Soul Urge, Personality, and Karmic Lessons."},"year":{"type":"integer","minimum":100,"maximum":2100,"example":1990,"description":"Birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Birth month (1-12)"},"day":{"type":"integer","minimum":1,"maximum":31,"example":15,"description":"Birth day (1-31)"},"currentYear":{"type":"integer","minimum":2020,"maximum":2100,"example":2025,"description":"Year for Personal Year calculation (defaults to current year)"}},"required":["fullName","year","month","day"]}}}},"responses":{"200":{"description":"Successfully generated complete numerology chart","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"name":{"type":"string","example":"John William Smith","description":"Full birth name used for letter-based calculations (Expression, Soul Urge, Personality)."},"birthdate":{"type":"string","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format."}},"required":["name","birthdate"],"description":"Input profile data used to generate the chart."},"coreNumbers":{"type":"object","properties":{"lifePath":{"type":"object","properties":{"number":{"type":"number","example":5,"description":"Life Path number (1-9, 11, 22, 33). The most important number in numerology, derived from birth date. Reveals life purpose and destiny."},"calculation":{"type":"string","example":"Month: 7, Day: 15 → 1+5 = 6, Year: 1990 → 1+9+9+0 = 19 → 1+9 = 10 → 1+0 = 1 → 7+6+1=14 → 5","description":"Step-by-step calculation showing how the Life Path number was derived from the birth date."},"type":{"type":"string","enum":["single","master"],"description":"Whether this is a single digit (1-9) or master number (11, 22, 33). Master numbers carry amplified spiritual significance."},"hasKarmicDebt":{"type":"boolean","example":true,"description":"True if the reduction passed through a karmic debt number (13, 14, 16, 19)."},"karmicDebtNumber":{"type":"number","example":14,"description":"The karmic debt number encountered during reduction, if any."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Adventurer","description":"Numerology archetype name for this Life Path number. A defining phrase that captures the core identity, such as \"The Leader\" for 1 or \"The Humanitarian\" for 9."},"keywords":{"type":"array","items":{"type":"string"},"example":["freedom","adventure","change","versatility","curiosity"],"description":"Defining personality traits and energetic themes for this Life Path. Useful for compatibility matching, personality snapshots, and building numerology profile summaries."},"description":{"type":"string","example":"The 5 is the most kinetic of all single-digit numbers. It is in constant motion, oriented toward what is new, and constitutionally resistant to the kind of settled routine that other numbers find stabilizing...","description":"Authoritative 300 to 500 word interpretation covering personality, life purpose, and core themes. Written by numerology experts and suitable for full-page readings or PDF report generation."},"strengths":{"type":"array","items":{"type":"string"},"example":["Adaptable: The 5 adjusts to new conditions with a fluidity that most other numbers find difficult to achieve...","Resourceful: When conventional approaches do not serve, the 5 draws on a broad repertoire of experience to find an alternative...","Socially fluent: The 5 moves easily across different social contexts, adapting its communication style to connect with a wide range of people..."],"description":"Core strengths and positive qualities. Each entry pairs a trait with a detailed explanation of how it manifests in everyday life and decision-making."},"challenges":{"type":"array","items":{"type":"string"},"example":["Unreliable: The same mobility that makes the 5 effective can make it difficult to count on...","Impulsive: The preference for direct experience over careful planning means the 5 often acts before considering consequences...","Directionless: The abundance of interests available to the 5 can produce a life that is wide but not deep..."],"description":"Growth areas and shadow qualities to work through. Each entry explains the root cause, how it surfaces in behavior, and constructive strategies for personal development."},"career":{"type":"string","example":"The 5 requires variety, autonomy, and stimulation in its professional life. Sales, journalism, public relations, travel-related work, entrepreneurship...","description":"Tailored career guidance covering ideal industries, roles, and work environments. Includes specific job titles and explains why certain professional paths resonate with this Life Path energy."},"relationships":{"type":"string","example":"The 5 brings vitality and spontaneity to relationships but requires genuine freedom within them to function well. It is more loyal than it initially appears...","description":"Love, friendship, and family dynamics shaped by this Life Path. Covers romantic compatibility with other numbers, communication style, and the key relationship lessons for lasting partnerships."},"spirituality":{"type":"string","example":"The 5 encounters the sacred primarily through direct experience rather than formal practice. Travel, conversation with diverse people, and immersion in unfamiliar environments are all forms of spiritual inquiry...","description":"Spiritual path, soul lessons, and recommended practices. Explores the deeper purpose behind this Life Path number and guidance for personal growth and inner transformation."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Life Path number with archetype, traits, career guidance, relationship insights, and spiritual direction."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Life Path. The most significant core number, revealing life purpose and destiny path."},"expression":{"type":"object","properties":{"number":{"type":"number","example":6,"description":"Expression (Destiny) number derived from full birth name using Pythagorean numerology."},"calculation":{"type":"string","example":"J=1, O=6, H=8, N=5, W=5, I=9, L=3, L=3, I=9, A=1, M=4, S=1, M=4, I=9, T=2, H=8 → 1+6+8+5+5+9+3+3+9+1+4+1+4+9+2+8 = 78 → 15 → 1+5 = 6","description":"Letter-to-number conversion showing how the Expression number was calculated."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Whether karmic debt was encountered during calculation."},"karmicDebtNumber":{"type":"number","example":16,"description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Nurturer","description":"Numerology archetype for this Expression number. Reveals the natural talent blueprint, such as \"The Communicator\" for 3 or \"The Master Builder\" for 22."},"keywords":{"type":"array","items":{"type":"string"},"example":["love","harmony","responsibility","nurturing","service"],"description":"Natural talents and abilities encoded in the birth name. These define your innate skill set, creative potential, and the gifts available to you throughout life."},"description":{"type":"string","example":"The 6 is the most relationship-oriented of the single-digit numbers, organized around a genuine drive to care for those within its sphere...","description":"Expert-written 300 to 500 word analysis of natural abilities, life goals, and the talents your birth name reveals. Suitable for detailed readings and personality assessments."},"strengths":{"type":"array","items":{"type":"string"},"example":["Supportive: The 6 offers support that is attentive and real rather than general and reflexive...","Protective: The 6 is quietly fierce in defense of those it cares for...","Responsible: The 6 takes its obligations seriously and follows through on them without requiring external pressure..."],"description":"Natural-born talents and creative gifts. Each strength describes a specific ability that comes effortlessly and how it contributes to personal and professional success."},"challenges":{"type":"array","items":{"type":"string"},"example":["Overprotective: The care the 6 offers can tip into control when it becomes convinced that its judgment about what others need is more reliable than their own...","Self-neglecting: The 6 prioritizes others so consistently that its own needs are regularly deferred or ignored entirely...","Idealistic: The 6 holds a vision of how relationships and communities ought to function..."],"description":"Growth areas where natural talent can become a liability without conscious balance. Explains how each challenge manifests and practical ways to work through it."},"career":{"type":"string","example":"The 6 is most effective in roles where its capacity for care and its aesthetic sensibility can both find expression. Healthcare, counseling, teaching, social work, and community organizing fit this number naturally...","description":"Career paths where your Expression number talents create the greatest professional advantage. Covers specific industries, creative pursuits, and work styles aligned with your name vibration."},"relationships":{"type":"string","example":"The 6 is a devoted and attentive partner who brings warmth, stability, and genuine investment to its closest relationships. Its love is expressed through consistent action rather than declaration...","description":"How your Expression number shapes the way you communicate, connect, and express love. Covers partnership dynamics, social style, and the relationship patterns rooted in your name energy."},"spirituality":{"type":"string","example":"The spiritual life of the 6 is inseparable from its relational life. It finds the sacred in acts of genuine service, in the beauty of natural and created environments...","description":"The spiritual dimension of your natural gifts. Explores how your Expression number talents serve a higher purpose and the creative practices that deepen self-expression."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Expression number with archetype, talents, career paths, relationship dynamics, and spiritual expression."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Expression (Destiny) number. Reveals natural talents, abilities, and life goals derived from the full birth name."},"soulUrge":{"type":"object","properties":{"number":{"type":"number","example":7,"description":"Soul Urge (Heart Desire) number from vowels in birth name."},"calculation":{"type":"string","example":"Vowels: O=6, I=9, I=9, A=1, I=9 → 6+9+9+1+9 = 34 → 7","description":"Vowel extraction and reduction calculation."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","example":13,"description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Seeker","description":"Numerology archetype for this Soul Urge number. Reveals the deepest inner motivation, such as \"The Seeker\" for 7 or \"The Master Teacher\" for 33."},"keywords":{"type":"array","items":{"type":"string"},"example":["wisdom","introspection","analysis","solitude","truth-seeking"],"description":"Core emotional drives and inner motivations. These define what truly fulfills you at the deepest level, beyond surface-level desires and social expectations."},"description":{"type":"string","example":"The 7 is the most internally-oriented of the single-digit numbers. While other numbers are engaged primarily with the external world of action, relationship, and material achievement, the 7 is fundamentally concerned with the interior world of understanding...","description":"Expert-written 300 to 500 word exploration of the inner self, hidden desires, and emotional landscape. Reveals what the heart truly craves beneath the surface persona."},"strengths":{"type":"array","items":{"type":"string"},"example":["Analytical: The 7 is skilled at separating what is essential from what is incidental, and at identifying patterns that others overlook...","Spiritually perceptive: The 7 has access to intuitive knowledge that supplements and sometimes outpaces its logical reasoning...","Depth of focus: When the 7 commits its attention to a subject, the quality of that attention is substantial..."],"description":"Emotional superpowers and inner gifts. Each strength describes how it shapes decision-making, relationships, and the pursuit of personal fulfillment."},"challenges":{"type":"array","items":{"type":"string"},"example":["Withdrawn: The 7 spends much of its mental life in internal territory, and this can produce a social distance...","Overly private: The 7 holds its interior world closely and is reluctant to share what it thinks and feels...","Skeptical to excess: The drive of the 7 to examine things beneath the surface can become a disposition that finds complication where none exists..."],"description":"Inner shadows and emotional patterns to balance. Explains how each challenge manifests when the Soul Urge energy is overextended or repressed."},"career":{"type":"string","example":"The 7 performs at its highest level in roles that reward solitary investigation, analytical depth, and the pursuit of non-obvious insight. Research science, philosophy, data analysis, writing, psychology, and investigative fields of all kinds draw on the best qualities of this number...","description":"Career paths that satisfy your deepest emotional needs. Focuses on work that feeds the soul rather than just the resume, aligned with lasting inner fulfillment."},"relationships":{"type":"string","example":"The 7 forms relationships with care and some difficulty, opening its interior world slowly and only to those who have demonstrated patience and genuine interest...","description":"How your Soul Urge shapes what you need from love, friendship, and family. Covers emotional compatibility, attachment style, and the key to feeling truly seen and understood."},"spirituality":{"type":"string","example":"The 7 is the most naturally spiritual of the single-digit numbers, not in a doctrinal sense but in its persistent orientation toward what lies beneath surface experience...","description":"The spiritual hunger at your core. Explores what your soul is seeking in this lifetime and the contemplative practices that bring you closest to inner peace and alignment."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Soul Urge number with archetype, emotional drives, relationship needs, and spiritual direction."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Soul Urge (Heart Desire) number. Reveals innermost desires, motivations, and what truly makes you happy. Calculated from vowels."},"personality":{"type":"object","properties":{"number":{"type":"number","example":8,"description":"Personality number from consonants in birth name."},"calculation":{"type":"string","example":"Consonants: J=1, H=8, N=5, W=5, L=3, L=3, M=4, S=1, M=4, T=2, H=8 → 1+8+5+5+3+3+4+1+4+2+8 = 44 → 8","description":"Consonant extraction and reduction calculation."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","example":19,"description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Powerhouse","description":"Numerology archetype for this Personality number. Represents the outer mask you show the world, such as \"The Builder\" for 4 or \"The Powerhouse\" for 8."},"keywords":{"type":"array","items":{"type":"string"},"example":["achievement","authority","abundance","ambition","resilience"],"description":"Traits that define your public persona and first impression. These are the qualities others perceive before they get to know the real you."},"description":{"type":"string","example":"The 8 is the number most directly associated with material mastery and the exercise of authority in the world. It is oriented toward achievement, and it brings to that orientation an uncommon combination of strategic intelligence, organizational capability, and physical endurance...","description":"Expert-written 300 to 500 word analysis of the outer personality, social presence, and the image you project to the world. Reveals the gap between perception and inner truth."},"strengths":{"type":"array","items":{"type":"string"},"example":["Ambitious: The 8 sets high targets and organizes its resources around reaching them...","Resilient: The 8 does not interpret setback as failure...","Organizationally capable: The 8 thinks in systems..."],"description":"Your strongest social assets and public-facing gifts. These qualities shape how you are received in professional settings, social gatherings, and first meetings."},"challenges":{"type":"array","items":{"type":"string"},"example":["Controlling: The 8 has strong convictions about how things should be managed and can find it genuinely difficult to delegate...","Status-oriented: The 8 can become overly invested in the visible markers of success: titles, possessions, and professional recognition...","Imbalanced in personal life: The drive to achieve in the external world can come at significant cost to the interior life of the 8..."],"description":"Blind spots in your public persona. Patterns others notice that you may not, including defense mechanisms and image-management tendencies that can limit authentic connection."},"career":{"type":"string","example":"The 8 is drawn to professional domains where strategic intelligence and organizational capability produce measurable results. Corporate leadership, finance, real estate, law, and high-level management suit it well...","description":"How your outward presence shapes professional opportunities. Covers the industries, roles, and environments where your public image creates the greatest advantage."},"relationships":{"type":"string","example":"The 8 is loyal and reliable in close relationships, and it expresses care primarily through provision and practical support rather than through emotional expressiveness...","description":"First impressions in love and social dynamics. Explores how your Personality number attracts certain partners, sets relationship expectations, and influences group dynamics."},"spirituality":{"type":"string","example":"The spiritual path of the 8 runs through its engagement with material life rather than away from it. Its core lesson concerns the relationship between power and integrity...","description":"The spiritual energy you radiate to others. Explores how your outer presence serves as a channel for deeper purpose and what your public path reveals about your soul mission."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Personality number with archetype, social traits, professional image, and first-impression dynamics."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Personality number. The outer you, how the world perceives you. Calculated from consonants in the birth name."},"birthDay":{"type":"object","properties":{"number":{"type":"number","example":6,"description":"Birth Day number (1-31). A special talent number based on the day of the month you were born."},"calculation":{"type":"string","example":"15 → 6","description":"Step-by-step calculation showing how the Birth Day number was reduced from the calendar day of birth."},"type":{"type":"string","enum":["single","master"],"description":"Whether this is a single digit (1-9) or master number (11, 22). Birth days of 11 and 22 are preserved as master numbers."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"True if the birth day is a karmic debt number (13, 14, 16, 19)."},"karmicDebtNumber":{"type":"number","example":13,"description":"The karmic debt number if the birth day carries one (13, 14, 16, or 19)."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Nurturer","description":"Numerology archetype for this Birth Day number. Represents the specific talent or gift you brought into this life, like \"The Nurturer\" for 6 or \"The Seeker\" for 7."},"keywords":{"type":"array","items":{"type":"string"},"example":["compassion","healing","family","beauty","devotion"],"description":"Innate talents and natural aptitudes encoded in your birth day. These gifts are available from birth and become more refined with age and experience."},"description":{"type":"string","example":"Its instinct is to tend: to notice when someone needs support and to provide it in ways that are practical and consistent rather than occasional and showy...","description":"Expert-written 300 to 500 word reading of the special abilities your birth day bestows. Covers how these gifts complement your Life Path and Expression numbers."},"strengths":{"type":"array","items":{"type":"string"},"example":["Supportive: It pays close attention to what others actually need, and its response is calibrated to the specific situation...","Protective: Its warmth does not preclude assertiveness; when the people or values it holds most closely are at risk, the 6 will respond with a directness that can surprise...","Responsible: Whether the commitment is to a family member, a colleague, or a cause, the 6 does what it said it would do..."],"description":"Natural-born strengths that come effortlessly. These are the talents you can rely on even without formal training or conscious development."},"challenges":{"type":"array","items":{"type":"string"},"example":["Overprotective: This overreach, always well-intentioned, denies others the opportunity to navigate difficulty independently...","Self-neglecting: The result is a gradual depletion that the 6 is often slow to recognize...","Idealistic: It can experience significant distress when reality falls consistently short of that vision..."],"description":"The flip side of your gifts. Each challenge explains how an overreliance on natural talent can become a liability without conscious balance."},"career":{"type":"string","example":"Its eye for beauty and harmony also serves it in interior design, hospitality, and the arts. The 6 is most fulfilled when it can see a direct connection between its daily work and the wellbeing of the people or environments it serves.","description":"Professional paths where your birth day talents create an immediate advantage. Covers specific roles, industries, and work styles aligned with your innate abilities."},"relationships":{"type":"string","example":"The risk is a tendency to over-function for others while under-attending to its own needs, creating an imbalance that strains the relationship over time...","description":"How your birth day gifts shape the way you connect with others. Covers romantic chemistry, friendship dynamics, and the relationship patterns rooted in your natural temperament."},"spirituality":{"type":"string","example":"Its spiritual lesson is that real service is sustainable only when the 6 first acknowledges its own needs as legitimate...","description":"The spiritual dimension of your natural gifts. Explores how your birth day talents serve a higher purpose and the practices that help you channel them with intention."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Birth Day number with archetype, innate talents, career advantages, and relationship dynamics."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Birth Day number. Reveals a special talent or gift based on the calendar day of birth."},"maturity":{"type":"object","properties":{"number":{"type":"number","example":11,"description":"Maturity number (Life Path + Expression). Becomes active around age 35-40."},"calculation":{"type":"string","example":"Life Path 5 + Expression 6 = 11","description":"Shows Life Path + Expression reduction."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","example":false,"description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","example":14,"description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Master Intuitive","description":"Numerology archetype for the Maturity number. Reveals who you are becoming in the second half of life, such as \"The Builder\" for 4 or \"The Humanitarian\" for 9."},"keywords":{"type":"array","items":{"type":"string"},"example":["intuition","spiritual sensitivity","illumination","inner wisdom","heightened awareness"],"description":"Emerging traits and qualities that strengthen after age 35 to 40. These energies gradually integrate into your personality as you mature and gain life experience."},"description":{"type":"string","example":"Eleven operates on a fundamentally different frequency than the single-digit numbers. The foundation of 2 is present: the need to relate, to listen, to balance, to work alongside others. But 11 adds a perceptive capacity that transcends ordinary observation...","description":"Expert-written 300 to 500 word guide to the person you are evolving into. The Maturity number represents the wisdom gained through lived experience and reveals your ultimate destination."},"strengths":{"type":"array","items":{"type":"string"},"example":["Perceptive depth: The capacity to read a situation, a person, or a group dynamic at a level that exceeds what is visible on the surface...","Inspirational presence: Eleven draws people toward it without calculated effort...","Bridging capacity: The 11 can hold two apparently opposing positions long enough to find the underlying commonality..."],"description":"Late-blooming strengths that emerge with age and experience. These are the gifts that become your greatest assets in the second half of life."},"challenges":{"type":"array","items":{"type":"string"},"example":["Perceptual overload: Harsh environments, interpersonal conflict, and sustained criticism land harder than they would for most numbers...","Chronic self-doubt: The gap between what 11 perceives and what it can prove rationally generates ongoing uncertainty...","Unrealized potential: The heightened energy of a master number is not automatically expressed..."],"description":"Growth areas to watch as Maturity energy intensifies. Understanding these early helps you navigate the transition into your mature self with awareness and grace."},"career":{"type":"string","example":"Eleven is most effective in roles where insight and sensitivity are the primary instrument rather than a liability to be managed. Counseling, therapeutic practice, spiritual direction, and teaching are natural alignments...","description":"Career evolution and professional reinvention for the second act. Covers industries, roles, and pursuits that align with your mature energy and accumulated wisdom."},"relationships":{"type":"string","example":"Eleven brings unusual attentiveness to partnership. It registers the emotional undercurrents of a relationship with precision, which can be an extraordinary quality and an occasional source of friction...","description":"How your relationships deepen and transform as Maturity energy takes hold. Covers evolving partnership needs, family dynamics, and the relationship wisdom that comes with age."},"spirituality":{"type":"string","example":"The spiritual dimension of 11 is inseparable from its everyday functioning. The perceptive quality that appears in a counseling session or a difficult conversation is what contemplative traditions call spiritual receptivity...","description":"Spiritual awakening in the mature years. Explores the deeper meaning that emerges when life experience meets the Maturity number and practices for this transformative phase."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"],"description":"Complete interpretation of the Maturity number with archetype, emerging traits, career evolution, and spiritual awakening."}},"required":["number","calculation","type","hasKarmicDebt","meaning"],"description":"Maturity number. The person you are becoming. Sum of Life Path and Expression, activates around age 35-40."}},"required":["lifePath","expression","soulUrge","personality","birthDay","maturity"],"description":"Six core numerology numbers with full interpretations. The foundation of any complete numerology reading."},"additionalInsights":{"type":"object","properties":{"karmicLessons":{"type":"object","properties":{"missingNumbers":{"type":"array","items":{"type":"number"},"example":[7],"description":"Numbers (1-9) missing from the birth name. Each missing number represents a karmic lesson to learn in this lifetime."},"lessons":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":7,"description":"The missing number representing this karmic lesson."},"lesson":{"type":"string","example":"Develop inner life, reflective depth, and trust in introspective knowledge","description":"Karmic lesson title identifying the core quality or virtue this soul needs to develop in the current lifetime."},"description":{"type":"string","example":"Absence of the number 7 indicates an underdeveloped inner life and a tendency to remain on the surface of experience without deeper reflection...","description":"What this missing number means for personal growth. Explains the life patterns, recurring situations, and soul-level work required to integrate this energy."},"howToOvercome":{"type":"string","example":"Develop a regular practice of reflection, whether through writing, meditation, study, or deliberate time in solitude...","description":"Actionable guidance for mastering this karmic lesson. Includes specific behaviors, mindset shifts, and daily practices that build the missing quality over time."}},"required":["number","lesson","description","howToOvercome"]},"description":"Detailed karmic lessons for each missing number."},"presentNumbers":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"How many letters of the full birth name reduce to this number. A number absent from the map has a count of zero, which is exactly what makes it a karmic lesson."},"example":{"1":3,"3":2,"5":4,"6":1,"7":2,"9":2},"description":"Count of each number (1-9) present in the birth name. High counts indicate natural strengths."}},"required":["missingNumbers","lessons","presentNumbers"],"description":"Karmic Lessons analysis. Identifies lessons the soul needs to learn based on missing numbers in the birth name."},"karmicDebt":{"type":"object","properties":{"hasKarmicDebt":{"type":"boolean","example":true,"description":"True if any core number reduces through a karmic debt number (13, 14, 16, 19)."},"debtNumbers":{"type":"array","items":{"type":"number"},"example":[14],"description":"List of karmic debt numbers found (13=laziness, 14=abuse of freedom, 16=ego destruction, 19=selfishness)."},"meanings":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":14,"description":"Karmic debt number (13, 14, 16, or 19). Each represents a specific pattern of unresolved karma from past lives that demands conscious attention."},"description":{"type":"string","example":"Accumulated Obligation of Moderation and Stability","description":"What this karmic debt means for your current lifetime. Explains the past-life pattern, how it manifests today, and why certain struggles keep recurring."},"challenge":{"type":"string","example":"A past pattern of misusing personal freedom, whether through overindulgence, excess, or the manipulation of others...","description":"The central life challenge this debt creates. Identifies the repeating obstacle pattern and the emotional or behavioral trap to watch for."},"resolution":{"type":"string","example":"Develop moderation as a practiced discipline rather than a reactive restriction. Build and honor commitments in measured increments...","description":"How to resolve and transcend this karmic debt. Provides the spiritual lesson, practical steps, and the transformative shift that breaks the cycle."}},"required":["number","description","challenge","resolution"]},"description":"Detailed meanings for each karmic debt number found."}},"required":["hasKarmicDebt","debtNumbers","meanings"],"description":"Karmic Debt analysis. Identifies unresolved karma from past lives carried through specific numbers (13, 14, 16, 19)."},"personalYear":{"type":"object","properties":{"personalYear":{"type":"number","example":4,"description":"Personal Year number (1-9). Each year in the 9-year cycle has distinct themes and energies."},"cycle":{"type":"string","example":"Year 4 of 9","description":"Position in the 9-year numerology cycle (e.g., \"Year 5 of 9\"). Each position carries distinct energy that shapes the entire year."},"theme":{"type":"string","example":"Work and Foundation","description":"Central theme and energy defining this Personal Year. Provides a one-line summary of the dominant vibration influencing all areas of life."},"forecast":{"type":"string","example":"The Personal Year 4 introduces the most demanding work period of the cycle. After three years of initiation, cooperation, and expression, the numerological current now insists on structure, discipline, and the unglamorous labor of building something durable...","description":"Detailed yearly forecast covering what to expect across career, relationships, health, and personal development. Provides month-by-month energy shifts and key turning points."},"opportunities":{"type":"array","items":{"type":"string"},"example":["Building durable professional and personal foundations that will last","Establishing effective systems and routines that reduce friction over time","Developing technical or practical expertise through focused application","Financial consolidation and disciplined saving toward defined goals"],"description":"Key opportunities available during this Personal Year. Each entry identifies a specific area of life where conditions are favorable for growth and forward momentum."},"challenges":{"type":"array","items":{"type":"string"},"example":["Feelings of restriction and limited freedom of movement under the slower energy","Frustration with the pace of visible results in methodical, long-horizon work","Overwork and physical exhaustion from sustained practical effort without rest","Resistance to structural changes that require dismantling familiar systems"],"description":"Potential challenges to navigate during this cycle. Each entry identifies a recurring theme or obstacle and how to work with the energy rather than against it."},"advice":{"type":"string","example":"Commit to the unglamorous work of building. Systems, routines, and disciplined follow-through are not merely means to an end this year. Do not mistake slowness for failure...","description":"Strategic guidance for making the most of this Personal Year. Covers timing decisions, areas to focus on, and the mindset that aligns with the current numerological energy."},"personalMonth":{"type":"object","properties":{"personalMonth":{"type":"number","example":3,"description":"Personal Month number (1-9)."},"theme":{"type":"string","example":"Expression and Connection","description":"Central theme for this Personal Month."},"focus":{"type":"string","example":"Creative and communicative work finds its best conditions. Reach out to people, put ideas into visible form, and allow social engagement to open professional doors that direct effort cannot.","description":"Practical focus and guidance for this month."}},"required":["personalMonth","theme","focus"],"description":"Personal Month forecast nested within the Personal Year cycle."}},"required":["personalYear","cycle","theme","forecast","opportunities","challenges","advice","personalMonth"],"description":"Personal Year forecast with nested Personal Month. Yearly and monthly numerology cycles."},"pinnacles":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Pinnacle position (1-4). Four major life phases."},"number":{"type":"number","example":4,"description":"Pinnacle number (1-9, 11, 22, 33). Defines the theme of this life phase."},"startAge":{"type":"number","example":0,"description":"Age when this Pinnacle phase begins."},"endAge":{"type":["number","null"],"example":31,"description":"Age when this phase ends. Null for the 4th Pinnacle (lasts rest of life)."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"Foundation Building and Disciplined Effort","description":"Pinnacle phase title."},"description":{"type":"string","example":"A Pinnacle under the number 4 centers on the construction of durable foundations: in career, finances, living conditions, and the structure of daily life...","description":"What this Pinnacle phase brings to your life."},"opportunities":{"type":"array","items":{"type":"string"},"example":["Establishing stable career foundations, acquiring property, or building financial structures with long-term durability","Developing sophisticated organizational habits and planning systems that improve across the entire phase","Earning the sustained respect of colleagues and institutions through demonstrated reliability and competence"],"description":"Key opportunities during this phase."},"challenges":{"type":"array","items":{"type":"string"},"example":["Feeling confined or depleted by the demands of sustained routine over an extended period","Rigidity in method and resistance to modifying approaches even when circumstances shift","Physical or mental exhaustion from maintaining effort without adequate rest or recovery"],"description":"Challenges to navigate during this phase."}},"required":["title","description","opportunities","challenges"],"description":"Meaning and interpretation for this Pinnacle number."}},"required":["position","number","startAge","endAge","meaning"]},"description":"Four Pinnacle numbers representing major life phases with age ranges and meanings."},"challenges":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Challenge position (1-4). Four life obstacle periods."},"number":{"type":"number","example":1,"description":"Challenge number (0-8). Defines the obstacle of this period."},"startAge":{"type":"number","example":0,"description":"Age when this Challenge period begins."},"endAge":{"type":["number","null"],"example":31,"description":"Age when this period ends. Null for the 4th Challenge."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Independence Challenge","description":"Challenge title."},"description":{"type":"string","example":"The 1 Challenge calls for the sustained development of genuine self-reliance. Life repeatedly constructs situations in which the individual must choose between standing on personal judgment and deferring to the expectations or authority of others...","description":"What this Challenge demands you overcome."},"lesson":{"type":"string","example":"Developing authentic self-reliance and the confidence to act from personal conviction rather than either external permission or reactive defiance.","description":"Core lesson to learn during this period."},"howToOvercome":{"type":"string","example":"Begin with smaller decisions made entirely independently, then build toward larger ones. Resist the pattern of seeking approval before acting...","description":"Actionable guidance for working through this Challenge."}},"required":["title","description","lesson","howToOvercome"],"description":"Meaning and resolution guidance for this Challenge number."}},"required":["position","number","startAge","endAge","meaning"]},"description":"Four Challenge numbers representing life obstacles aligned with Pinnacle timing."},"hiddenPassion":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hidden Passion number (1-9). The most frequently occurring number in the birth name."},"count":{"type":"number","example":3,"description":"How many times this number appears in the name."},"allPassions":{"type":"array","items":{"type":"number"},"example":[1,9],"description":"All numbers tied for highest frequency (usually one, sometimes multiple)."},"title":{"type":"string","example":"Compulsion Toward Leadership","description":"Archetype title for this Hidden Passion."},"description":{"type":"string","example":"The number 1 appearing most often in a name produces a persistent need for originality and self-direction. This person feels most fully expressed when operating independently and setting direction for others...","description":"What this dominant number drive reveals about latent talents and obsessions."}},"required":["number","count","allPassions","title","description"],"description":"Hidden Passion number. The most frequent number in the name revealing an overwhelming drive or talent."},"subconsciousSelf":{"type":"object","properties":{"number":{"type":"number","example":8,"description":"Subconscious Self number (1-9). Count of unique numbers present in the name."},"uniqueNumbers":{"type":"array","items":{"type":"number"},"example":[1,2,3,4,5,6,8,9],"description":"Which numbers (1-9) are present in the birth name."},"title":{"type":"string","example":"Near-Complete Resourcefulness","description":"Archetype title for this Subconscious Self level."},"description":{"type":"string","example":"With 8 of 9 number values present, almost no situation triggers the feeling of being unprepared. A vast experiential base is available to draw on in difficulty...","description":"How you handle emergencies and unexpected challenges based on the breadth of numbers in your name."}},"required":["number","uniqueNumbers","title","description"],"description":"Subconscious Self number. Reveals inner confidence and emergency response style."},"nameLetters":{"type":"object","properties":{"cornerstone":{"type":"object","properties":{"letter":{"type":"string","example":"J","description":"First letter of the first name."},"number":{"type":"number","example":1,"description":"Pythagorean number value of the Cornerstone letter."},"meaning":{"type":"string","example":"The approach to new beginnings is direct and self-directed. The default instinct is to take initiative rather than wait for consensus, to assess a situation independently, and to engage on personal terms.","description":"How you approach new situations and initiate action."}},"required":["letter","number","meaning"],"description":"Cornerstone letter analysis. Reveals approach to new situations."},"capstone":{"type":"object","properties":{"letter":{"type":"string","example":"N","description":"Last letter of the first name."},"number":{"type":"number","example":5,"description":"Pythagorean number value of the Capstone letter."},"meaning":{"type":"string","example":"Endings are handled quickly and without extended backward glance. Protracted closing phases generate impatience, and a clean break is consistently preferred over gradual transition.","description":"How you complete tasks and handle endings."}},"required":["letter","number","meaning"],"description":"Capstone letter analysis. Reveals completion and follow-through style."},"firstVowel":{"type":"object","properties":{"letter":{"type":"string","example":"O","description":"First vowel in the full name (A, E, I, O, or U)."},"meaning":{"type":"string","example":"The instinctive emotional response is principled and measured. Reactions are filtered through a sense of what is right and appropriate before full expression occurs.","description":"Instinctive emotional response and inner reaction style."}},"required":["letter","meaning"],"description":"First Vowel analysis. Reveals instinctive emotional reactions."}},"required":["cornerstone","capstone","firstVowel"],"description":"Name letter analysis: Cornerstone, Capstone, and First Vowel."}},"required":["karmicLessons","karmicDebt","personalYear","pinnacles","challenges","hiddenPassion","subconsciousSelf","nameLetters"],"description":"Additional numerology insights: karmic analysis, yearly/monthly forecasts, pinnacles, challenges, hidden passion, subconscious self, and name letter analysis."},"birthDayProfile":{"type":"object","properties":{"day":{"type":"number","example":15,"description":"Calendar day of birth (1-31)."},"reducesTo":{"type":"number","example":6,"description":"Single digit or master number this day reduces to."},"title":{"type":"string","example":"The Magnetic Artist","description":"Unique archetype title for this specific birth day."},"keywords":{"type":"array","items":{"type":"string"},"example":["magnetism","artistic sensibility","language facility","nurturing responsibility","determination"],"description":"Personality traits specific to this birth day."},"description":{"type":"string","example":"The 15th combines the forward drive of 1, the versatility and appetite for experience of 5, and the care-centered orientation of the reduced 6. The result is one of the more immediately compelling birth day numbers...","description":"Detailed personality profile unique to this calendar day, not just the reduced digit."},"strengths":{"type":"array","items":{"type":"string"},"example":["Personal magnetism that creates immediate and lasting impressions","Genuine facility with language and visual aesthetic expression","Deep compassion grounded in practical capability rather than sentiment alone","Tenacious commitment once a course of action is chosen"],"description":"Strengths specific to this birth day."},"challenges":{"type":"array","items":{"type":"string"},"example":["Stubbornness that continues past the point where flexibility would be more useful","Susceptibility to emotional overwhelm when carrying the burdens of others","Impatience when results do not arrive on their preferred timeline","Sensitivity to criticism that can stall otherwise strong creative momentum"],"description":"Challenges specific to this birth day."},"career":{"type":"string","example":"Healthcare, counseling, social work, teaching, and any direct-service role align with their nurturing orientation and practical capability. Their artistic inclinations open additional paths in visual arts, design, photography, and creative direction...","description":"Career guidance for this specific birth day."},"relationships":{"type":"string","example":"Those born on the 15th offer devoted, attentive partnership that combines emotional warmth with practical support. They are drawn to partners who are genuinely engaged in their own lives and purposes...","description":"Relationship dynamics for this birth day."}},"required":["day","reducesTo","title","keywords","description","strengths","challenges","career","relationships"],"description":"Birth Day profile with day-specific meaning (1-31). Unlike the core Birth Day number, this provides unique interpretation per calendar day."},"maturityStatus":{"type":"object","properties":{"isActive":{"type":"boolean","example":true,"description":"Whether the Maturity number is currently active (typically activates around age 35-40)."},"currentAge":{"type":"number","example":36,"description":"Current age calculated from the birth year."},"activationRange":{"type":"string","example":"35-40","description":"Age range when the Maturity number typically activates (35-40)."}},"required":["isActive","currentAge","activationRange"],"description":"Maturity number activation status based on current age."},"luckyAssociations":{"type":"object","properties":{"colors":{"type":"array","items":{"type":"string"},"example":["Green","Turquoise","Light Brown"],"description":"Lucky colors associated with the Life Path number."},"gemstones":{"type":"array","items":{"type":"string"},"example":["Emerald","Aquamarine","Diamond"],"description":"Lucky gemstones aligned to the ruling planet."},"day":{"type":"string","example":"Wednesday","description":"Lucky day of the week."},"element":{"type":"string","example":"Air","description":"Classical element (Fire, Water, Earth, Air)."},"rulingPlanet":{"type":"string","example":"Mercury","description":"Ruling planet for this Life Path number."},"compatibleNumbers":{"type":"array","items":{"type":"number"},"example":[1,3,5,7,9],"description":"Most compatible Life Path numbers."},"incompatibleNumbers":{"type":"array","items":{"type":"number"},"example":[2,4,6],"description":"Least compatible Life Path numbers."}},"required":["colors","gemstones","day","element","rulingPlanet","compatibleNumbers","incompatibleNumbers"],"description":"Lucky associations based on Life Path number: colors, gemstones, day, element, planet, and compatibility."},"summary":{"type":"string","example":"Your numerology chart reveals a Life Path 5 personality seeking freedom and adventure...","description":"AI-ready holistic summary weaving all core numbers, karmic insights, and yearly forecast into a cohesive narrative. Ideal for generating personalized reports, chatbot responses, or one-page numerology overviews."}},"required":["profile","coreNumbers","additionalInsights","maturityStatus","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/meanings/{number}":{"get":{"operationId":"getNumberMeaning","tags":["Numerology"],"summary":"Get Number Meaning - Interpretation for any number 1-9, 11, 22, 33","description":"Get the complete meaning and interpretation for any numerology number (1-9, 11, 22, 33) using Pythagorean numerology. Returns comprehensive description including archetype title, keywords, personality traits, strengths, weaknesses, career guidance, relationship dynamics, and spiritual insights. Master numbers (11, 22, 33) include amplified meanings with their reduced base number. Perfect for numerology reference tools, educational apps, quick lookups, and building custom numerology calculators. Get detailed 300-500 word expert-written meanings for all 12 valid numerology numbers.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^(1|2|3|4|5|6|7|8|9|11|22|33)$","example":"5","description":"Numerology number (1-9, 11, 22, 33)"},"required":true,"description":"Numerology number (1-9, 11, 22, 33)","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved number meaning","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":5,"description":"Requested number"},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Number type"},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Adventurer","description":"Numerology archetype name. A single phrase capturing the core identity of this number, such as \"The Leader\" for 1 or \"The Master Builder\" for 22."},"keywords":{"type":"array","items":{"type":"string"},"example":["freedom","adventure","versatile","dynamic","curious"],"description":"Ten defining personality traits and energetic themes. Useful for personality snapshots, compatibility matching, and building numerology profile summaries."},"description":{"type":"string","example":"In the span of single-digit numbers 1 to 9, 5 is the number in the exact middle...","description":"Authoritative 300 to 500 word interpretation covering personality, life purpose, and core themes. Written by numerology experts and suitable for full-page readings."},"strengths":{"type":"array","items":{"type":"string"},"example":["Curious","Adaptable","Social"],"description":"Core strengths and positive qualities. Each entry pairs a trait name with a detailed explanation of how it manifests in real life."},"challenges":{"type":"array","items":{"type":"string"},"example":["Non-committal","Unreliable","Directionless"],"description":"Growth areas and shadow qualities. Each entry explains the root cause, how it surfaces, and constructive strategies for working through it."},"career":{"type":"string","example":"Life Path 5 thrives in careers that offer freedom, variety, and constant stimulation...","description":"Tailored career guidance with specific job titles, industries, and work environments. Explains why certain professional paths resonate with this number."},"relationships":{"type":"string","example":"Life Path 5 individuals are exciting, charming, and freedom-loving partners...","description":"Love, friendship, and family dynamics. Covers romantic compatibility with other numbers, communication style, and the key relationship lessons."},"spirituality":{"type":"string","example":"Five is the rebel, the traveler, the agent of change...","description":"Spiritual path, soul lessons, and recommended practices. Explores the deeper purpose behind this number and guidance for personal growth."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["number","type","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Number meaning not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/daily":{"post":{"operationId":"getDailyNumber","tags":["Numerology"],"summary":"Get daily numerology number - Number of the Day with interpretation","description":"Receive a daily numerology number (1-9, 11, 22, 33) for guidance and reflection. Uses seeded randomness so the same seed gets the same number on the same date, perfect for \"Number of the Day\" features in numerology apps, wellness platforms, and daily guidance tools. Returns the number with full interpretation including archetype, keywords, strengths, challenges, career, relationships, and spiritual insights. Ideal for daily push notifications, morning briefings, and personalized numerology experiences.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same number every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily numerology number with full interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-03-06","description":"Date this daily number is for (YYYY-MM-DD, UTC)."},"seed":{"type":"string","example":"user123-2026-03-06","description":"Computed seed used for this reading. Same seed always produces the same number."},"number":{"type":"number","example":7,"description":"Daily numerology number (1-9, 11, 22, 33). Represents the dominant energy and theme for this day."},"type":{"type":"string","enum":["single","master"],"example":"single","description":"Whether this is a single-digit number (1-9) or a Master Number (11, 22, 33). Master Number days carry amplified spiritual significance."},"dailyMessage":{"type":"string","example":"Your number for 2026-03-06 is 7 (The Seeker). Focus on introspection, analysis, and spiritual growth today.","description":"Concise daily guidance message combining the number archetype with practical advice for the day."},"meaning":{"type":"object","properties":{"title":{"type":"string","example":"The Seeker","description":"Numerology archetype for this number. Captures the core energy of the day in a single phrase."},"keywords":{"type":"array","items":{"type":"string"},"example":["analytical","spiritual","wise","introspective","perfectionist"],"description":"Defining traits and energetic themes active today. Useful for daily affirmations, journaling prompts, and focus areas."},"description":{"type":"string","example":"The 7 is the most internally-oriented of the single-digit numbers. While other numbers are engaged primarily with the external world of action, relationship, and material achievement, the 7 is fundamentally concerned with the interior world of understanding...","description":"Expert-written 300 to 500 word interpretation of the daily energy. Covers personality resonance, life themes, and how this number influences the day."},"strengths":{"type":"array","items":{"type":"string"},"example":["Analytical: The 7 is skilled at separating what is essential from what is incidental, and at identifying patterns that others overlook...","Spiritually perceptive: The 7 has access to intuitive knowledge that supplements and sometimes outpaces its logical reasoning...","Depth of focus: When the 7 commits its attention to a subject, the quality of that attention is substantial..."],"description":"Qualities that are amplified and accessible today. Lean into these for maximum alignment with the daily energy."},"challenges":{"type":"array","items":{"type":"string"},"example":["Withdrawn: The 7 spends much of its mental life in internal territory, and this can produce a social distance...","Overly private: The 7 holds its interior world closely and is reluctant to share what it thinks and feels...","Skeptical to excess: The drive of the 7 to examine things beneath the surface can become a disposition that finds complication where none exists..."],"description":"Shadow patterns to watch for today. Awareness of these helps navigate the day with intention and balance."},"career":{"type":"string","example":"The 7 performs at its highest level in roles that reward solitary investigation, analytical depth, and the pursuit of non-obvious insight. Research science, philosophy, data analysis, writing, psychology, and investigative fields of all kinds draw on the best qualities of this number...","description":"Professional guidance tuned to the daily energy. Suggests optimal work strategies, meeting approaches, and productivity focus areas."},"relationships":{"type":"string","example":"The 7 forms relationships with care and some difficulty, opening its interior world slowly and only to those who have demonstrated patience and genuine interest...","description":"Relationship dynamics influenced by the daily number. Covers communication style, social energy, and partnership awareness for the day."},"spirituality":{"type":"string","example":"The 7 is the most naturally spiritual of the single-digit numbers, not in a doctrinal sense but in its persistent orientation toward what lies beneath surface experience...","description":"Spiritual theme of the day. Suggests meditation focus, contemplative practices, and the deeper lesson available today."}},"required":["title","keywords","description","strengths","challenges","career","relationships","spirituality"]}},"required":["date","seed","number","type","dailyMessage","meaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/chaldean":{"post":{"operationId":"calculateChaldean","tags":["Numerology"],"summary":"Chaldean numerology name reading - Destiny, compound number, planetary ruler","description":"Calculate a complete Chaldean numerology reading for a name. The older Chaldean system maps letters to values 1 to 8 by vibration (the number 9 is sacred and never assigned to a letter) and reads the unreduced two-digit compound number (10 to 52, also called a fadic number, defined by Cheiro) in addition to the single-digit root. Returns the Destiny or name number from all letters, the Soul Urge from vowels, and the Personality from consonants, each with its compound number, root, and Cheiro compound interpretation, plus the planetary ruler of the Destiny root and a caution flag for the karmic numbers 4 and 8. Perfect for Chaldean numerology calculators, name analysis tools, and AI numerology assistants that need both the compound and root layers in one call.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Helen","description":"The name to analyze. Chaldean tradition uses the name a person is most known by, not necessarily the full legal birth name."}},"required":["name"]}}}},"responses":{"200":{"description":"Successfully calculated the Chaldean name reading","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Helen","description":"The name analyzed."},"destiny":{"type":"object","properties":{"total":{"type":"number","example":23,"description":"Raw sum of the Chaldean letter values before any reduction."},"compound":{"type":["number","null"],"example":23,"description":"The interpretable compound number (10 to 52), the hidden influence behind the name, or null when the total resolves below 10."},"root":{"type":"number","example":5,"description":"The single-digit root (1 to 9), the outward expression. Chaldean does not preserve master numbers."},"calculation":{"type":"string","example":"H=5, E=5, L=3, E=5, N=5 = 23 → 5","description":"Letter-by-letter Chaldean breakdown summed to the total, then to compound and root."},"compoundMeaning":{"type":["object","null"],"properties":{"number":{"type":"number","example":23,"description":"The compound number (10 to 52)."},"name":{"type":["string","null"],"example":"The Royal Star of the Lion","description":"Classical symbolic title from Cheiro, or null when the number has no named symbol."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"fortunate","description":"Overall tenor of the compound. \"mixed\" covers conditional numbers that are fortunate only alongside a favorable single number or in a specific domain."},"meaning":{"type":"string","example":"A promise of success, help from superiors and protection from those in high places.","description":"Cheiro interpretation of the hidden influence carried by this compound number."},"sameAs":{"type":"number","example":24,"description":"For numbers 33 to 52, the lower compound in the same series whose meaning this number shares."}},"required":["number","name","nature","meaning"],"description":"Cheiro compound-number interpretation when the aspect carries a compound layer."}},"required":["total","compound","root","calculation","compoundMeaning"],"description":"The Destiny or name number from all letters. The primary Chaldean number, revealing the overall direction encoded in the name."},"soulUrge":{"type":"object","properties":{"total":{"type":"number","example":23,"description":"Raw sum of the Chaldean letter values before any reduction."},"compound":{"type":["number","null"],"example":23,"description":"The interpretable compound number (10 to 52), the hidden influence behind the name, or null when the total resolves below 10."},"root":{"type":"number","example":5,"description":"The single-digit root (1 to 9), the outward expression. Chaldean does not preserve master numbers."},"calculation":{"type":"string","example":"H=5, E=5, L=3, E=5, N=5 = 23 → 5","description":"Letter-by-letter Chaldean breakdown summed to the total, then to compound and root."},"compoundMeaning":{"type":["object","null"],"properties":{"number":{"type":"number","example":23,"description":"The compound number (10 to 52)."},"name":{"type":["string","null"],"example":"The Royal Star of the Lion","description":"Classical symbolic title from Cheiro, or null when the number has no named symbol."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"fortunate","description":"Overall tenor of the compound. \"mixed\" covers conditional numbers that are fortunate only alongside a favorable single number or in a specific domain."},"meaning":{"type":"string","example":"A promise of success, help from superiors and protection from those in high places.","description":"Cheiro interpretation of the hidden influence carried by this compound number."},"sameAs":{"type":"number","example":24,"description":"For numbers 33 to 52, the lower compound in the same series whose meaning this number shares."}},"required":["number","name","nature","meaning"],"description":"Cheiro compound-number interpretation when the aspect carries a compound layer."}},"required":["total","compound","root","calculation","compoundMeaning"],"description":"The Soul Urge number from the vowels, revealing inner desire. Root may be 0 when the name has no vowels."},"personality":{"type":"object","properties":{"total":{"type":"number","example":23,"description":"Raw sum of the Chaldean letter values before any reduction."},"compound":{"type":["number","null"],"example":23,"description":"The interpretable compound number (10 to 52), the hidden influence behind the name, or null when the total resolves below 10."},"root":{"type":"number","example":5,"description":"The single-digit root (1 to 9), the outward expression. Chaldean does not preserve master numbers."},"calculation":{"type":"string","example":"H=5, E=5, L=3, E=5, N=5 = 23 → 5","description":"Letter-by-letter Chaldean breakdown summed to the total, then to compound and root."},"compoundMeaning":{"type":["object","null"],"properties":{"number":{"type":"number","example":23,"description":"The compound number (10 to 52)."},"name":{"type":["string","null"],"example":"The Royal Star of the Lion","description":"Classical symbolic title from Cheiro, or null when the number has no named symbol."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"fortunate","description":"Overall tenor of the compound. \"mixed\" covers conditional numbers that are fortunate only alongside a favorable single number or in a specific domain."},"meaning":{"type":"string","example":"A promise of success, help from superiors and protection from those in high places.","description":"Cheiro interpretation of the hidden influence carried by this compound number."},"sameAs":{"type":"number","example":24,"description":"For numbers 33 to 52, the lower compound in the same series whose meaning this number shares."}},"required":["number","name","nature","meaning"],"description":"Cheiro compound-number interpretation when the aspect carries a compound layer."}},"required":["total","compound","root","calculation","compoundMeaning"],"description":"The Personality number from the consonants, revealing the outer impression. Root may be 0 when the name has no consonants."},"numberMeaning":{"type":"object","properties":{"number":{"type":"number","example":5,"description":"The Destiny root (1 to 9)."},"planet":{"type":"string","example":"Mercury","description":"Ruling planet."},"title":{"type":"string","example":"The Communicator","description":"Archetype of the root number."},"keywords":{"type":"array","items":{"type":"string"},"example":["versatility","communication","commerce","quick thinking","adaptability"],"description":"Core themes of the Destiny root."},"caution":{"type":"boolean","example":false,"description":"True for roots 4 and 8, the two numbers Cheiro counsels caution with."},"meaning":{"type":"string","example":"Ruled by Mercury. Mercurial, adaptable and clever, the 5 thrives on trade, travel and communication.","description":"Planetary interpretation of the Destiny root number."}},"required":["number","planet","title","keywords","caution","meaning"]},"caution":{"type":"boolean","example":false,"description":"True when the Destiny root is 4 or 8, the karmic numbers Cheiro advises adjusting a name away from for material success."},"summary":{"type":"string","example":"The name Helen carries a Chaldean Destiny root of 5 (The Communicator), ruled by Mercury, with a compound number of 23.","description":"One-line plain-language summary of the Chaldean reading."}},"required":["name","destiny","soulUrge","personality","numberMeaning","caution","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/compound-number/{number}":{"get":{"operationId":"getCompoundNumber","tags":["Numerology"],"summary":"Compound number meaning - Cheiro Chaldean interpretation 10 to 52","description":"Get the classical Chaldean interpretation of a compound number (also called a fadic number) from 10 to 52, as defined by Cheiro in the Book of Numbers. Compound numbers are the unreduced two-digit numbers that reveal the hidden influence behind a name or date, beyond the single-digit root. Each returns its symbolic title (such as The Wheel of Fortune for 10, The Star of the Magi for 17, or The Crown of the Magi for 21), its nature (fortunate, unfortunate, or mixed), and a full interpretation. Numbers 33 to 52 share the meaning of a lower number in their series, returned with a sameAs pointer. Perfect for Chaldean numerology references, compound number lookups, and AI numerology tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^(1\\d|2\\d|3\\d|4\\d|5[0-2])$","example":"23","description":"Compound number from 10 to 52."},"required":true,"description":"Compound number from 10 to 52.","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved the compound number meaning","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":23,"description":"The compound number (10 to 52)."},"name":{"type":["string","null"],"example":"The Royal Star of the Lion","description":"Classical symbolic title from Cheiro, or null when none is given."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"fortunate","description":"Overall tenor of the number. \"mixed\" marks conditional numbers, fortunate only with a favorable single number or in one domain."},"meaning":{"type":"string","example":"A promise of success, help from superiors and protection from those in high places.","description":"Cheiro interpretation of the hidden influence carried by this compound number."},"root":{"type":"number","example":5,"description":"The single-digit root the compound reduces to (1 to 9)."},"sameAs":{"type":"number","example":24,"description":"For numbers 33 to 52, the lower compound in the same series whose meaning this number shares."}},"required":["number","name","nature","meaning","root"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/dual":{"post":{"operationId":"calculateDual","tags":["Numerology"],"summary":"Dual numerology - Pythagorean and Chaldean name numbers in one call","description":"Calculate a name number in both major numerology systems at once and compare them. The Pythagorean system maps letters 1 to 9 in alphabetical order and preserves master numbers (11, 22, 33), giving the Expression or Destiny number used in modern Western numerology. The Chaldean system maps letters 1 to 8 by vibration, reads the compound number (10 to 52), and reduces to a root 1 to 9. Returns both results with their interpretations, plus an agreement flag showing whether the two systems point to the same single-digit energy. The only numerology API that returns Pythagorean and Chaldean for a name in a single request, ideal for comparison tools and AI numerology assistants.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"David","description":"The name to analyze in both systems."}},"required":["name"]}}}},"responses":{"200":{"description":"Successfully calculated the name in both numerology systems","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"David","description":"The name analyzed."},"pythagorean":{"type":"object","properties":{"number":{"type":"number","example":22,"description":"Pythagorean Expression number (1 to 9, 11, 22, 33)."},"type":{"type":"string","enum":["single","master"],"example":"master","description":"Single digit or preserved master number."},"calculation":{"type":"string","example":"D=4, A=1, V=4, I=9, D=4 → 4+1+4+9+4 = 22","description":"Pythagorean letter breakdown and reduction."},"title":{"type":"string","example":"The Master Builder","description":"Archetype of the number."},"keywords":{"type":"array","items":{"type":"string"},"example":["master builder","manifestation","visionary thinking","practicality","determination"],"description":"Core themes in the Pythagorean reading."}},"required":["number","type","calculation","title","keywords"]},"chaldean":{"type":"object","properties":{"compound":{"type":["number","null"],"example":16,"description":"Chaldean compound number (10 to 52), the hidden influence, or null."},"root":{"type":"number","example":7,"description":"Chaldean root (1 to 9)."},"total":{"type":"number","example":16,"description":"Raw Chaldean letter total."},"calculation":{"type":"string","example":"D=4, A=1, V=6, I=1, D=4 = 16 → 7","description":"Chaldean letter breakdown to compound and root."},"planet":{"type":"string","example":"Neptune","description":"Planetary ruler of the Chaldean root."},"title":{"type":"string","example":"The Seeker","description":"Archetype of the Chaldean root."},"caution":{"type":"boolean","example":false,"description":"True when the Chaldean root is 4 or 8, the numbers of caution."},"compoundMeaning":{"type":["object","null"],"properties":{"number":{"type":"number","example":16,"description":"The compound number."},"name":{"type":["string","null"],"example":"The Shattered Citadel","description":"Symbolic title."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"unfortunate","description":"Tenor of the compound."},"meaning":{"type":"string","example":"Pictured as a tower struck by lightning from which a man falls with a crown on his head. It warns of a strange fatality, accidents and the defeat of plans.","description":"Cheiro interpretation."},"sameAs":{"type":"number","example":24,"description":"Series equivalent for 33 to 52."}},"required":["number","name","nature","meaning"],"description":"Cheiro compound interpretation when present."}},"required":["compound","root","total","calculation","planet","title","caution","compoundMeaning"]},"agreement":{"type":"boolean","example":false,"description":"True when both systems reduce to the same single-digit energy (Pythagorean number reduced to one digit equals the Chaldean root). Agreement is read as a name whose vibrations are in harmony."},"note":{"type":"string","example":"The two systems diverge for this name: Pythagorean points to 22 while Chaldean points to 7.","description":"Plain-language comparison of the two systems for this name."}},"required":["name","pythagorean","chaldean","agreement","note"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/numerology/business-name":{"post":{"operationId":"calculateBusinessName","tags":["Numerology"],"summary":"Business name numerology - Chaldean brand name analysis and lucky numbers","description":"Analyze a business or brand name with Chaldean numerology, the system practitioners use for trade names. Returns the name number (compound and root), its planetary ruler, an overall business rating, the industries the number favors, and whether the compound is one of Cheiro fortunate compounds. The most favorable business roots are 1 (leadership), 3 (expansion), 5 (commerce) and 6 (beauty and hospitality); the numbers 4 and 8 carry caution as the karmic numbers of instability and heavy demand. Use it to vet a company name, compare brand options, or guide a naming decision. This is positioning guidance layered over the fundamentals of a memorable, available name, not a guarantee.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Ford","description":"The business or brand name to evaluate."}},"required":["name"]}}}},"responses":{"200":{"description":"Successfully analyzed the business name","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Ford","description":"The business name analyzed."},"total":{"type":"number","example":21,"description":"Raw Chaldean letter total of the name."},"compound":{"type":["number","null"],"example":21,"description":"Chaldean compound number (10 to 52), the hidden influence, or null."},"root":{"type":"number","example":3,"description":"Single-digit business root (1 to 9), the outward commercial expression."},"planet":{"type":"string","example":"Jupiter","description":"Planetary ruler of the business root."},"rating":{"type":"string","enum":["excellent","good","caution","avoid"],"example":"excellent","description":"Overall favorability of the root for business. excellent and good are growth-friendly; caution (7, 8) and avoid (4) flag the demanding and unstable roots."},"favorableCompound":{"type":"boolean","example":true,"description":"True when the compound number is one of Cheiro fortunate compounds, an extra positive signal layered over the root rating."},"industries":{"type":"array","items":{"type":"string"},"example":["Media and content","Education and training","Finance and advisory","Creative services"],"description":"Industries the business root favors."},"guidance":{"type":"string","example":"An expansive vibration ruled by Jupiter. Excellent for growth, communication and creativity, favoring brands built on expertise, advice and reputation.","description":"Plain-language guidance for using this number as a brand."},"calculation":{"type":"string","example":"F=8, O=7, R=2, D=4 = 21 → 3","description":"Chaldean letter breakdown of the business name."},"compoundMeaning":{"type":["object","null"],"properties":{"number":{"type":"number","example":21,"description":"The compound number."},"name":{"type":["string","null"],"example":"The Crown of the Magi","description":"Symbolic title, if any."},"nature":{"type":"string","enum":["fortunate","unfortunate","mixed"],"example":"fortunate","description":"Tenor of the compound."},"meaning":{"type":"string","example":"Symbolized by the Universe. A number of advancement, honors, elevation and general success, meaning victory after long initiation and tests of determination.","description":"Cheiro interpretation."},"sameAs":{"type":"number","example":24,"description":"Series equivalent for 33 to 52."}},"required":["number","name","nature","meaning"],"description":"Cheiro compound interpretation when present."},"summary":{"type":"string","example":"Ford has a Chaldean business root of 3 (excellent). An expansive vibration ruled by Jupiter. Excellent for growth, communication and creativity, favoring brands built on expertise, advice and reputation.","description":"One-line plain-language verdict for the business name."}},"required":["name","total","compound","root","planet","rating","favorableCompound","industries","guidance","calculation","compoundMeaning","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/cards":{"get":{"operationId":"listCards","tags":["Tarot"],"summary":"List all 78 tarot cards","description":"Retrieve the complete Rider-Waite-Smith tarot deck of 78 cards: 22 Major Arcana (numbered 0-21, representing life lessons, spiritual themes, and karmic influences like The Fool, Death, The Tower) plus 56 Minor Arcana (4 suits × 14 cards each for daily situations and practical matters). Filter by arcana type (major for spiritual guidance, minor for everyday concerns), suit (cups for emotions and relationships, wands for creativity and passion, swords for intellect and conflict, pentacles for material wealth and finances), or card number (Ace=1 for new beginnings, 2-10 for progression, Page=11 for messages, Knight=12 for action, Queen=13 for mastery, King=14 for authority). Returns lightweight basic card data - use GET /cards/:id for full upright and reversed interpretations with keywords. Perfect for building tarot reference libraries, card databases, learning applications, or browsing the complete traditional deck used by professional tarot readers worldwide.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-100, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"},{"schema":{"type":"string","enum":["major","minor"],"example":"major","description":"Filter by arcana type. Major arcana (0-21) represents life lessons and spiritual themes. Minor arcana (Ace-King in 4 suits) represents daily situations and practical matters."},"required":false,"description":"Filter by arcana type. Major arcana (0-21) represents life lessons and spiritual themes. Minor arcana (Ace-King in 4 suits) represents daily situations and practical matters.","name":"arcana","in":"query"},{"schema":{"type":"string","enum":["cups","wands","swords","pentacles"],"example":"cups","description":"Filter minor arcana by suit. Cups=emotions/relationships, Wands=creativity/passion, Swords=intellect/conflict, Pentacles=material/finances. Only applies to minor arcana cards."},"required":false,"description":"Filter minor arcana by suit. Cups=emotions/relationships, Wands=creativity/passion, Swords=intellect/conflict, Pentacles=material/finances. Only applies to minor arcana cards.","name":"suit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":21,"example":1,"description":"Filter by card number. Major Arcana: 0 (The Fool) through 21 (The World). Minor Arcana: 1 (Ace) through 14 (King). Combine with arcana or suit filters for precise results."},"required":false,"description":"Filter by card number. Major Arcana: 0 (The Fool) through 21 (The World). Minor Arcana: 1 (Ace) through 14 (King). Combine with arcana or suit filters for precise results.","name":"number","in":"query"}],"responses":{"200":{"description":"List of tarot cards with basic information. Use GET /cards/:id for full details.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":78,"description":"Total number of tarot cards matching the applied filters. 78 for the full deck, 22 for Major Arcana, 56 for Minor Arcana, 14 per suit."},"limit":{"type":"number","example":20,"description":"Maximum items returned per page."},"offset":{"type":"number","example":0,"description":"Number of items skipped from the start of the result set."},"cards":{"type":"array","items":{"$ref":"#/components/schemas/BasicCard"},"description":"Array of tarot cards with basic metadata. Use GET /cards/:id for full upright and reversed interpretations."}},"required":["total","limit","offset","cards"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/cards/{id}":{"get":{"operationId":"getCard","tags":["Tarot"],"summary":"Get detailed tarot card information","description":"Retrieve comprehensive details for a specific tarot card from the traditional Rider-Waite-Smith deck including complete upright meanings (card drawn normally) and reversed meanings (inverted/upside down interpretations for nuanced guidance). Each card provides keywords for quick reference, full interpretations (400+ words each for upright and reversed orientations), and guidance across life domains: love and relationships, career and professional growth, finances and material success, health and wellbeing, spirituality and personal development. Major Arcana cards (0-21) reveal deep spiritual lessons and life-changing themes. Minor Arcana cards (Ace through King in Cups, Wands, Swords, Pentacles) address practical daily situations and specific challenges. Use card ID in kebab-case format: Major Arcana like \"fool\", \"magician\", \"death\", \"tower\", or Minor Arcana like \"ace-of-cups\", \"seven-of-wands\", \"queen-of-swords\", \"king-of-pentacles\". Essential for detailed tarot study, reading interpretations, divination apps, fortune-telling platforms, spiritual guidance tools, and professional tarot learning applications.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"fool","description":"Unique card identifier in kebab-case. Major arcana: \"fool\", \"magician\", \"death\", etc. Minor arcana: \"ace-of-cups\", \"seven-of-wands\", \"queen-of-swords\", \"king-of-pentacles\", etc."},"required":true,"description":"Unique card identifier in kebab-case. Major arcana: \"fool\", \"magician\", \"death\", etc. Minor arcana: \"ace-of-cups\", \"seven-of-wands\", \"queen-of-swords\", \"king-of-pentacles\", etc.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Card details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/draw":{"post":{"operationId":"drawCards","tags":["Tarot"],"summary":"Draw random tarot cards with reproducible results","description":"Draw 1-78 tarot cards from the complete Rider-Waite-Smith deck with seeded reproducibility for consistent personalized readings. Provide an optional seed string (like \"user123-2025-12-27\" or \"readingId\") to ensure the same seed always returns identical cards in the exact same order - essential for daily tarot features, personalized user experiences, shareable readings, or reproducible testing. Omit seed for true random draws each time. Control card reversals (upright vs reversed/inverted orientations - reversed cards provide alternative meanings when drawn upside down) and duplicates (traditional deck draws each of 78 cards once, or oracle-style allows repeating same card). Each drawn card includes position number, reversal state (boolean), keywords for quick interpretation, full meaning text (400+ words), authentic Rider-Waite imagery, and card metadata. Perfect for custom spread builders, random card generators, automated tarot reading platforms, daily card features, meditation apps, journaling prompts, divination tools, and any application requiring reproducible or random tarot draws from the industry-standard 78-card deck (22 Major Arcana spiritual lessons + 56 Minor Arcana practical guidance across 4 suits).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","minimum":1,"maximum":78,"example":3,"description":"Number of cards to draw (1-78). Common values: 1 for daily card, 3 for past-present-future, 5 for relationship spread, 10 for Celtic Cross. Drawing 78 returns the entire shuffled deck."},"seed":{"type":"string","example":"user123-2025-12-27","description":"Optional seed for reproducible results. Same seed = same cards in same order. Use format like \"userId-date\" for daily consistency, or \"readingId\" for shareable readings. Omit for true randomness."},"allowReversals":{"type":"boolean","default":true,"example":true,"description":"Whether cards can appear reversed (upside down). Reversed cards have different meanings. Set false for upright-only readings. Default: true (50% chance of reversal per card)."},"allowDuplicates":{"type":"boolean","default":false,"example":false,"description":"Whether same card can be drawn multiple times. Set false for traditional deck behavior (each card drawn only once). Set true for statistical analysis or oracle-style readings. Default: false."}},"required":["count"]}}}},"responses":{"200":{"description":"Drawn cards","content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123-2025-12-27","description":"Seed used for this reading, if one was provided. Same seed reproduces identical draw results for consistent tarot readings."},"cards":{"type":"array","items":{"$ref":"#/components/schemas/DrawnCard"},"description":"Array of drawn tarot cards in draw order, each with orientation, keywords, and full meaning for divination."}},"required":["cards"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/daily":{"post":{"operationId":"getDailyCard","tags":["Tarot"],"summary":"Get daily tarot card reading","description":"Receive a single tarot card for daily guidance and reflection. This endpoint uses seeded randomness to ensure the same seed gets the same card on the same day - perfect for \"Card of the Day\" features. Provide a seed (userId, email hash, session token) for reproducible consistency, or omit for anonymous daily draws. Returns card with keywords, full meaning, and a daily message summary. Great for tarot apps, wellness platforms, morning ritual apps, and journaling tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same card every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily card reading","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-03-06","description":"Date of the daily tarot reading in YYYY-MM-DD format (UTC). Determines which card is drawn for seeded readings."},"seed":{"type":"string","example":"user123-2026-03-06","description":"Seed used for this daily reading. Same seed on the same date always produces the identical card for reproducible daily divination."},"card":{"$ref":"#/components/schemas/DrawnCard"},"dailyMessage":{"type":"string","example":"Your card for 2026-03-06: Knight of Pentacles (reversed). stagnation, stubbornness, boredom, overcaution. Reversed, the Knight of Pentacles shows his steady virtues tipping into excess, and the surrounding cards reveal which way. Waite gave the reversal as inertia, idleness, stagnation, and discouragement...","description":"Concise daily tarot message summarizing the card, its orientation, key themes, and brief guidance for the day."}},"required":["date","seed","card","dailyMessage"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Failed to draw card","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}}}}},"/tarot/yes-no":{"post":{"operationId":"castYesNo","tags":["Tarot"],"summary":"Get yes/no answer to your question","description":"Ask a specific question and receive a yes, no, or maybe answer based on a single tarot card draw. Upright cards indicate \"Yes\" with positive energy, reversed cards indicate \"No\" with caution, and certain inherently ambiguous cards (The Hanged Man, Wheel of Fortune, Temperance, Two of Swords, Four of Swords) return \"Maybe\" regardless of orientation since their energy signals pause, reflection, or shifting circumstances. Major Arcana cards give strong definitive answers, Minor Arcana cards give qualified nuanced answers. Returns the answer, strength level, drawn card details, and a contextual interpretation explaining why. Perfect for decision-making apps, quick guidance tools, fortune-telling chatbots, and interactive tarot experiences. Optionally provide a seed for reproducible answers.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"Should I accept the job offer?","description":"Your specific yes/no question. Be clear and focused. Good: \"Should I move to a new city?\" Bad: \"What should I do about my life?\" The more specific the question, the more useful the tarot guidance."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. Same seed + same question = same answer. Useful for testing, sharing readings, or ensuring consistency. Omit for random draws each time."}}}}}},"responses":{"200":{"description":"Yes/No answer with interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"Should I accept the job offer?","description":"The querent question that was asked, if one was provided."},"seed":{"type":"string","example":"user123-question1","description":"The seed used for this draw, echoed back when one was supplied. Present only if the request carried a seed. Makes a cached or forwarded response self describing, so a reading can be reproduced or shared without the original request beside it."},"answer":{"type":"string","enum":["Yes","No","Maybe"],"description":"Tarot-derived answer. Yes = upright card supports a positive outcome. No = reversed card suggests obstacles. Maybe = inherently ambiguous card drawn (The Hanged Man, Wheel of Fortune, Temperance, Two of Swords, Four of Swords) signaling pause, reflection, or shifting circumstances."},"strength":{"type":"string","enum":["Strong","Qualified"],"description":"Confidence level of the answer. Strong = Major Arcana card drawn (powerful, definitive cosmic energy). Qualified = Minor Arcana card drawn (nuanced, situational guidance)."},"card":{"type":"object","properties":{"id":{"type":"string","example":"world","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","example":"The World","description":"Display name of the tarot card."},"arcana":{"type":"string","enum":["major","minor"],"description":"Whether this card belongs to the Major Arcana (22 trump cards, major life themes) or Minor Arcana (56 suit cards, daily situations)."},"reversed":{"type":"boolean","example":false,"description":"True if the card was drawn reversed (upside down). Reversed cards carry modified or blocked energy compared to upright position."},"keywords":{"type":"array","items":{"type":"string"},"example":["completion","fulfilment","integration","accomplishment","travel"],"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"imageUrl":{"type":"string","example":"https://roxyapi.com/img/tarot/major/world.jpg","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","imageUrl"]},"interpretation":{"type":"string","example":"Strong Yes: The World suggests forward momentum. The World is the final card of the Major Arcana, the close of the journey that began with The Fool. In the Rider-Waite-Smith image, a dancing figure m...","description":"Contextual narrative explaining why this card answers the question with this result. Connects card meaning, orientation, and arcana strength into actionable guidance."}},"required":["answer","strength","card","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Failed to draw card","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}}}}},"/tarot/spreads/three-card":{"post":{"operationId":"castThreeCard","tags":["Tarot"],"summary":"Three-Card Spread: Past, Present, Future","description":"Perform the classic three-card tarot spread revealing Past (what led to this situation), Present (current energy and circumstances), and Future (likely outcome if current path continues). The most popular beginner-friendly spread, perfect for quick insights, daily guidance, or exploring specific questions. Each position includes a drawn card with reversal state, keywords, full meaning, and position-specific interpretation. Returns a summary connecting all three cards. Ideal for tarot reading apps, decision-making tools, and personal growth platforms. Optionally provide a seed for reproducible readings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"What do I need to know about my career?","description":"Optional specific question to focus the reading. Examples: \"What should I know about my relationship?\", \"How can I improve my finances?\", \"What is blocking my creative growth?\" Leave empty for general guidance."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. Same seed = same 3 cards in same positions. Useful for sharing readings, testing, or ensuring users get consistent results. Omit for random draws."}}}}}},"responses":{"200":{"description":"Three-card spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","example":"Three-Card","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","example":"What do I need to know about my career?","description":"The querent question, if one was provided."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Seed used for this reading, if one was provided. Same seed reproduces identical results."},"positions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Position number in the spread layout (1-based)."},"name":{"type":"string","example":"Past","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","example":"What has led to this situation and the foundational influences at play. Shows the events, decisions, and energies that have brought you to where you are now. Understanding the past provides context for the present.","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"$ref":"#/components/schemas/DrawnCard"}},"required":["position","name","interpretation","card"]},"description":"Array of spread positions, each containing a drawn card with position-specific tarot interpretation."},"summary":{"type":"string","example":"Your past (Eight of Wands) has shaped your present situation (Four of Swords reversed). The future (The Lovers reversed) suggests challenges to overcome if you continue on this path.","description":"Narrative summary that connects the cards drawn across the spread positions into one cohesive reading."}},"required":["spread","positions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/spreads/celtic-cross":{"post":{"operationId":"castCelticCross","tags":["Tarot"],"summary":"Celtic Cross Spread (10 cards)","description":"Perform the legendary Celtic Cross spread - the most comprehensive and detailed tarot reading available, used by professional tarot readers worldwide for over a century. This 10-card layout reveals the complete picture of any situation through distinct positions: Present Situation (what is happening now), Challenge (obstacles crossing your path), Distant Past (root causes), Recent Past (recent influences), Best Outcome (potential positive result), Near Future (what is approaching in weeks ahead), Your Approach (your attitude and self-perception), External Influences (environment and other people impact), Hopes and Fears (your desires and anxieties), and Final Outcome (where everything is headed). Perfect for life-changing decisions, complex relationship questions, career transitions, spiritual guidance, and deep self-discovery. Ideal for professional tarot apps, life coaching platforms, spiritual wellness websites, and divination tools requiring authoritative comprehensive readings. Each card position provides layered insight combining traditional tarot wisdom with modern psychological interpretation for actionable guidance.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"What should I know about this situation?","description":"Optional querent question to focus the Celtic Cross. It is echoed back on the reading and gives the ten positions their context. Omit for a general reading of the situation."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. The same seed always draws the same ten cards into the same Celtic Cross positions, which is what lets a reading be shared or re-rendered. Omit for a random draw."}}}}}},"responses":{"200":{"description":"Celtic Cross spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","example":"Celtic Cross","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","example":"What should I know about this situation?","description":"The querent question, if one was provided."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Seed used for this reading, if one was provided. Same seed reproduces identical results."},"positions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Position number in the spread layout (1-based)."},"name":{"type":"string","example":"Past","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","example":"What has led to this situation and the foundational influences at play. Shows the events, decisions, and energies that have brought you to where you are now. Understanding the past provides context for the present.","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"$ref":"#/components/schemas/DrawnCard"}},"required":["position","name","interpretation","card"]},"description":"Array of 10 spread positions forming the complete Celtic Cross layout, each with a drawn card and position-specific interpretation."},"summary":{"type":"string","example":"The Celtic Cross provides deep insight into your situation, revealing past influences, present challenges, and future possibilities.","description":"Narrative summary that connects the cards drawn across the spread positions into one cohesive reading."}},"required":["spread","positions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/spreads/love":{"post":{"operationId":"castLoveSpread","tags":["Tarot"],"summary":"Love Spread (5 cards)","description":"Perform a specialized 5-card relationship tarot spread analyzing romantic connections, emotional dynamics, and partnership potential. This love-focused reading examines five crucial relationship aspects: You (your current emotional state, needs, and what you bring to the relationship), Partner/Other (their emotional perspective, desires, and energy), Relationship Dynamic (the current energy and connection between you both), Challenge (obstacles needing attention, healing, or communication), and Outcome (where this romantic connection is naturally heading). Perfect for dating apps, relationship counseling platforms, matchmaking services, wellness apps, and romantic guidance tools. Provides deep insight into new relationships, existing partnerships, potential connections, breakup recovery, or self-love journeys. Ideal for understanding compatibility, resolving conflicts, strengthening bonds, or deciding whether to pursue or continue a relationship. Each position reveals emotional truths combining traditional tarot relationship wisdom with modern relationship psychology. Use for individual readings or couples readings to gain perspective on romantic situations from singleness to marriage.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"What do I need to know about my relationship?","description":"Optional querent question to focus the love spread. It is echoed back on the reading and gives the five relationship positions their context. Omit for general relationship guidance."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. The same seed always draws the same five cards into the same love positions, which is what lets a reading be shared or re-rendered. Omit for a random draw."}}}}}},"responses":{"200":{"description":"Love spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","example":"Love Spread","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","example":"What do I need to know about my relationship?","description":"The querent question, if one was provided."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Seed used for this reading, if one was provided. Same seed reproduces identical results."},"positions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Position number in the spread layout (1-based)."},"name":{"type":"string","example":"Past","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","example":"What has led to this situation and the foundational influences at play. Shows the events, decisions, and energies that have brought you to where you are now. Understanding the past provides context for the present.","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"$ref":"#/components/schemas/DrawnCard"}},"required":["position","name","interpretation","card"]},"description":"Array of 5 love spread positions exploring relationship dynamics, each with a drawn card and position-specific interpretation."},"summary":{"type":"string","example":"This spread reveals the emotional landscape of your relationship and offers guidance for deepening connection.","description":"Narrative summary that connects the cards drawn across the spread positions into one cohesive reading."}},"required":["spread","positions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/spreads/career":{"post":{"operationId":"castCareerSpread","tags":["Tarot"],"summary":"Career Spread (7 cards)","description":"Perform a comprehensive 7-card career tarot spread using SWOT analysis framework (Strengths, Weaknesses, Opportunities, Threats) for professional guidance, business decisions, and vocational clarity. This career-focused reading examines seven strategic business aspects: Current Situation (your present professional position and workplace energy), Strengths (your professional assets, talents, and competitive advantages), Weaknesses (areas needing development, skill gaps, or limiting beliefs), Opportunities (potential growth paths, new ventures, or doors opening), Threats (obstacles, competition, or external challenges), Advice (actionable guidance for navigating your career path), and Outcome (where your professional journey is heading if you follow the guidance). Perfect for career coaching platforms, professional development apps, business consulting tools, job search websites, entrepreneurship platforms, and executive coaching services. Use for career transitions, job offers evaluation, promotion decisions, starting a business, workplace conflicts, finding your calling, or strategic career planning. Combines traditional tarot wisdom with modern SWOT business analysis for practical professional insight. Ideal for employees, entrepreneurs, freelancers, career changers, and anyone seeking vocational direction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","example":"What do I need to know about my career path?","description":"Optional querent question to focus the career spread. It is echoed back on the reading and gives the seven career positions their context. Omit for general work and vocation guidance."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. The same seed always draws the same seven cards into the same career positions, which is what lets a reading be shared or re-rendered. Omit for a random draw."}}}}}},"responses":{"200":{"description":"Career spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","example":"Career Spread","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","example":"What do I need to know about my career path?","description":"The querent question, if one was provided."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Seed used for this reading, if one was provided. Same seed reproduces identical results."},"positions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Position number in the spread layout (1-based)."},"name":{"type":"string","example":"Past","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","example":"What has led to this situation and the foundational influences at play. Shows the events, decisions, and energies that have brought you to where you are now. Understanding the past provides context for the present.","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"$ref":"#/components/schemas/DrawnCard"}},"required":["position","name","interpretation","card"]},"description":"Array of 7 career spread positions using SWOT framework, each with a drawn card and position-specific interpretation."},"summary":{"type":"string","example":"This SWOT-based spread provides comprehensive career guidance and identifies growth opportunities.","description":"Narrative summary that connects the cards drawn across the spread positions into one cohesive reading."}},"required":["spread","positions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tarot/spreads/custom":{"post":{"operationId":"castCustomSpread","tags":["Tarot"],"summary":"Custom Spread Builder","description":"Build and perform your own custom tarot spread with personalized positions and interpretations (1-10 cards). This flexible endpoint lets you create unique spread layouts for any purpose - define your own position names, meanings, and card count to match your specific needs or therapeutic framework. Perfect for therapists using tarot in counseling, coaches creating signature spreads, app developers building custom reading features, spiritual practitioners with proprietary methods, or anyone wanting to design specialized layouts beyond traditional spreads. Create spreads for specific themes like chakra readings (7 cards), lunar phases (8 cards), elements (4 cards), goals setting (any count), shadow work, inner child healing, decision matrices, or creative problem-solving. Each position requires a name and interpretation - you define what each card position represents in your reading. The API draws the exact number of cards you specify and maps them to your custom positions. No pre-generated summary provided - you interpret the reading based on your framework. Ideal for innovative tarot apps, therapeutic tools, personal development platforms, spiritual coaching services, or experimental divination methods. Maximum 10 positions to maintain reading clarity and practical interpretation time.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spreadName":{"type":"string","example":"My Custom Spread","description":"Optional name for your custom tarot spread layout. Used as the spread identifier in the response."},"positions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Core Issue","description":"Name for this position in the spread (e.g. Core Issue, Hidden Factor, Best Action). Defines what aspect of the reading this card represents."},"interpretation":{"type":"string","example":"What is really going on","description":"Description of what this position reveals in the reading. Guides the tarot interpretation for the card drawn in this slot."}},"required":["name","interpretation"]},"minItems":1,"maxItems":10,"description":"Array of 1-10 custom position definitions for your tarot spread. Each position gets one drawn card with a position-specific interpretation.","example":[{"name":"Core Issue","interpretation":"What is really going on"},{"name":"Hidden Factor","interpretation":"What you cannot see"},{"name":"Best Action","interpretation":"What to do next"}]},"question":{"type":"string","example":"How do I move forward with this project?","description":"Optional querent question to focus the custom tarot reading. Provides context for position-specific interpretations."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Optional seed for reproducible results. Same seed with the same positions produces identical card draws for consistent divination."}},"required":["positions"]}}}},"responses":{"200":{"description":"Custom spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","example":"My Custom Spread","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","example":"How do I move forward with this project?","description":"The querent question, if one was provided."},"seed":{"type":"string","example":"reading-2f9c1a","description":"Seed used for this reading, if one was provided. Same seed reproduces identical results."},"positions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number","example":1,"description":"Position number in the spread layout (1-based)."},"name":{"type":"string","example":"Past","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","example":"What has led to this situation and the foundational influences at play. Shows the events, decisions, and energies that have brought you to where you are now. Understanding the past provides context for the present.","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"$ref":"#/components/schemas/DrawnCard"}},"required":["position","name","interpretation","card"]},"description":"Array of custom spread positions matching your defined layout, each with a drawn card and position-specific interpretation."}},"required":["spread","positions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/reading":{"post":{"operationId":"getReading","tags":["Biorhythm"],"summary":"Get biorhythm reading - Complete cycle analysis for any date","description":"Calculate a complete biorhythm reading for a given birth date and target date. Returns all 10 cycle values (physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom), phase detection with 8 distinct states, energy rating (1-10), overall phase assessment, editorial-grade interpretation, actionable advice, and critical day alerts. Perfect for wellness apps, dating platforms, productivity tools, and AI chatbot integrations that need structured biorhythm data.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format. This is the anchor for all biorhythm cycle calculations."},"targetDate":{"type":"string","format":"date","example":"2026-04-10","description":"Date to calculate the reading for in YYYY-MM-DD format. Defaults to today (UTC) if omitted."}},"required":["birthDate"]}}}},"responses":{"200":{"description":"Complete biorhythm reading with all 10 cycles, energy rating, interpretation, and critical alerts","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Birth date used for this calculation (YYYY-MM-DD)."},"targetDate":{"type":"string","example":"2026-04-10","description":"Date this reading is for (YYYY-MM-DD)."},"daysSinceBirth":{"type":"number","example":13049,"description":"Total days alive from birth date to target date. This is the basis for all cycle calculations."},"cycles":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number","example":74,"description":"Percentage position in the cycle from -100 (trough) to 100 (peak). 0 represents a critical zero crossing."},"rawValue":{"type":"number","example":0.74,"description":"Raw sine wave value before percentage conversion, ranging from -1.0 to 1.0."},"phase":{"type":"string","example":"high","description":"Current phase of the cycle. One of: peak, high, rising, critical_ascending, critical_descending, falling, low, trough."},"phaseLabel":{"type":"string","example":"High Energy","description":"Human-readable phase name for display in UIs, dashboards, and reports."},"dayInCycle":{"type":"number","example":8,"description":"Current day position within the cycle (1-based). Ranges from 1 to the cycle period length."},"daysUntilPeak":{"type":"number","example":3,"description":"Number of days until the next peak (100%) in this cycle."},"daysUntilTrough":{"type":"number","example":14,"description":"Number of days until the next trough (-100%) in this cycle."},"daysUntilCritical":{"type":"number","example":9,"description":"Number of days until the next zero crossing in this cycle."},"trend":{"type":"string","example":"rising","description":"Short-term direction of the cycle. One of: rising, falling, peaking, bottoming."},"interpretation":{"type":"string","example":"Your physical energy is strong and building. Endurance and coordination are above average. Good conditions for exercise, physical projects, and activities requiring sustained effort.","description":"Editorial 2-3 sentence reading specific to this cycle at its current phase position."}},"required":["value","rawValue","phase","phaseLabel","dayInCycle","daysUntilPeak","daysUntilTrough","daysUntilCritical","trend","interpretation"]},"description":"All 10 biorhythm cycle readings. Keys: physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom."},"energyRating":{"type":"number","example":7,"description":"Overall energy score from 1 (deep recovery) to 10 (peak performance), derived from the three primary cycle positions."},"overallPhase":{"type":"string","example":"high_energy","description":"Summary phase label. One of: high_energy, mixed, recovery, critical."},"interpretation":{"type":"string","example":"Your physical energy is strong and building. Endurance and coordination are above average. Good conditions for exercise, physical projects, and activities requiring sustained effort. Your emotional energy is also elevated, supporting your overall capacity.","description":"Editorial 3-5 sentence reading combining all cycle states into a coherent daily assessment."},"advice":{"type":"string","example":"Tackle physically demanding tasks while your energy remains elevated.","description":"Actionable 1-2 sentence guidance for the day based on the combined cycle analysis."},"criticalAlerts":{"type":"array","items":{"type":"object","properties":{"cycle":{"type":"string","example":"physical","description":"Which cycle is at or near zero crossing."},"type":{"type":"string","example":"zero_crossing","description":"Alert type. zero_crossing when a cycle crosses zero, approaching_critical when within 1 day of zero."},"direction":{"type":"string","example":"ascending","description":"Whether the cycle is rising through zero (ascending) or falling through zero (descending)."},"advisory":{"type":"string","example":"physical cycle crosses zero while ascending. Transition from recovery to active phase.","description":"Specific advisory text for this critical alert."}},"required":["cycle","type","direction","advisory"]},"description":"Critical day alerts. Present only when one or more primary cycles are at or near zero crossing."}},"required":["birthDate","targetDate","daysSinceBirth","cycles","energyRating","overallPhase","interpretation","advice","criticalAlerts"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/forecast":{"post":{"operationId":"getForecast","tags":["Biorhythm"],"summary":"Get biorhythm forecast - Multi-day cycle predictions with best and worst days","description":"Generate a biorhythm forecast for a date range up to 90 days. Returns daily cycle values for physical, emotional, intellectual, and intuitive cycles, daily energy ratings, critical day identification, and a summary with best day, worst day, average energy, and period-level guidance. Ideal for wellness apps, productivity planners, scheduling tools, and calendar integrations that need forward-looking biorhythm data.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"startDate":{"type":"string","format":"date","example":"2026-04-01","description":"Start date of the forecast range in YYYY-MM-DD format. Defaults to today (UTC)."},"endDate":{"type":"string","format":"date","example":"2026-04-30","description":"End date of the forecast range in YYYY-MM-DD format. Defaults to startDate + 30 days. Maximum range: 90 days."}},"required":["birthDate"]}}}},"responses":{"200":{"description":"Biorhythm forecast with daily readings, summary, and best/worst day identification","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Birth date used for this calculation."},"startDate":{"type":"string","example":"2026-04-01","description":"First day of the forecast range."},"endDate":{"type":"string","example":"2026-04-30","description":"Last day of the forecast range."},"totalDays":{"type":"number","example":30,"description":"Number of days in the forecast range."},"summary":{"type":"object","properties":{"bestDay":{"type":"string","example":"2026-04-14","description":"Date with the highest average primary cycle values in the range. Best day for demanding activities."},"worstDay":{"type":"string","example":"2026-04-07","description":"Date with the lowest average primary cycle values in the range. Best scheduled as a rest day."},"criticalDayCount":{"type":"number","example":4,"description":"Total number of days where at least one primary cycle crosses zero in the range."},"averageEnergy":{"type":"number","example":6,"description":"Average energy rating (1-10) across the entire forecast period."},"periodAdvice":{"type":"string","example":"This period has a mix of energy levels. Plan demanding work around the best days and schedule lighter activity during the troughs.","description":"Overview guidance for the entire forecast period based on average energy and cycle patterns."}},"required":["bestDay","worstDay","criticalDayCount","averageEnergy","periodAdvice"]},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-01","description":"Date of this daily reading (YYYY-MM-DD)."},"daysSinceBirth":{"type":"number","example":13040,"description":"Days from birth date to this date."},"physical":{"type":"number","example":45,"description":"Physical cycle value (-100 to 100)."},"emotional":{"type":"number","example":-30,"description":"Emotional cycle value (-100 to 100)."},"intellectual":{"type":"number","example":72,"description":"Intellectual cycle value (-100 to 100)."},"intuitive":{"type":"number","example":18,"description":"Intuitive cycle value (-100 to 100)."},"energyRating":{"type":"number","example":6,"description":"Energy rating for this day (1-10)."},"isCritical":{"type":"boolean","example":false,"description":"True if any primary cycle crosses zero on this day."},"criticalCycles":{"type":"array","items":{"type":"string"},"example":[],"description":"Which primary cycles are critical on this day. Empty array if none."}},"required":["date","daysSinceBirth","physical","emotional","intellectual","intuitive","energyRating","isCritical","criticalCycles"]},"description":"Array of daily readings, one per day in the forecast range."}},"required":["birthDate","startDate","endDate","totalDays","summary","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/critical-days":{"post":{"operationId":"getCriticalDays","tags":["Biorhythm"],"summary":"Find critical days - Zero crossing detection for any date range","description":"Find all critical days (zero crossings) within a date range up to 180 days. Returns each critical day with cycle name, period, direction (ascending or descending), severity (single, double, or triple), and advisory text. Highlights rare double critical days where two primary cycles cross zero simultaneously and extremely rare triple critical days where all three primary cycles cross zero on the same date. Ideal for calendar integrations, push notification systems, alert engines, and wellness scheduling tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"startDate":{"type":"string","format":"date","example":"2026-04-01","description":"Start date of the search range in YYYY-MM-DD format. Defaults to today (UTC)."},"endDate":{"type":"string","format":"date","example":"2026-06-30","description":"End date of the search range in YYYY-MM-DD format. Defaults to startDate + 90 days. Maximum range: 180 days."}},"required":["birthDate"]}}}},"responses":{"200":{"description":"Critical days with zero crossing details, severity levels, and advisory text","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Birth date used for this calculation."},"startDate":{"type":"string","example":"2026-04-01","description":"Start of the search range."},"endDate":{"type":"string","example":"2026-06-30","description":"End of the search range."},"totalCriticalDays":{"type":"number","example":12,"description":"Total count of critical day events in the range. A double critical day counts as two events."},"criticalDays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-03","description":"Date of the zero crossing (YYYY-MM-DD)."},"cycle":{"type":"string","example":"physical","description":"Which primary cycle crosses zero on this date."},"period":{"type":"number","example":23,"description":"Cycle period in days."},"direction":{"type":"string","example":"ascending","description":"Whether the cycle is rising through zero (ascending) or falling through zero (descending)."},"severity":{"type":"string","example":"single","description":"How many primary cycles are critical on this date. single, double, or triple."},"advisory":{"type":"string","example":"Physical cycle crosses zero while descending. Transition from active to recovery phase.","description":"Advisory text explaining the significance of this critical day and recommended precautions."}},"required":["date","cycle","period","direction","severity","advisory"]},"description":"All critical day events in the range, sorted by date."},"doubleCriticalDays":{"type":"array","items":{"type":"string"},"example":["2026-05-12"],"description":"Dates where 2 or more primary cycles cross zero simultaneously. These are particularly significant days requiring extra caution."},"tripleCriticalDay":{"type":["string","null"],"example":null,"description":"Date where all 3 primary cycles cross zero simultaneously. Extremely rare event. Null if none found in range."}},"required":["birthDate","startDate","endDate","totalCriticalDays","criticalDays","doubleCriticalDays","tripleCriticalDay"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/compatibility":{"post":{"operationId":"calculateBioCompatibility","tags":["Biorhythm"],"summary":"Calculate compatibility - Biorhythm alignment between two people","description":"Calculate biorhythm compatibility between two people by overlaying their cycle profiles on a target date. Returns per-cycle alignment scores (0-100) for physical, emotional, and intellectual cycles, an overall compatibility score, relationship rating, strengths, challenges, practical advice, and a daily sync snapshot showing the absolute difference in each primary cycle. Perfect for dating apps, relationship platforms, team-building tools, and couples coaching applications.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date of person 1 in YYYY-MM-DD format."}},"required":["birthDate"]},"person2":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1992-03-22","description":"Birth date of person 2 in YYYY-MM-DD format."}},"required":["birthDate"]},"targetDate":{"type":"string","format":"date","example":"2026-04-10","description":"Date to evaluate compatibility on in YYYY-MM-DD format. Defaults to today (UTC). Compatibility varies by day since biorhythm cycles are continuous."}},"required":["person1","person2"]}}}},"responses":{"200":{"description":"Biorhythm compatibility analysis with per-cycle alignment, overall score, and relationship guidance","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Birth date of person 1."}},"required":["birthDate"]},"person2":{"type":"object","properties":{"birthDate":{"type":"string","example":"1992-03-22","description":"Birth date of person 2."}},"required":["birthDate"]},"targetDate":{"type":"string","example":"2026-04-10","description":"Date this compatibility was calculated for."},"overallScore":{"type":"number","example":72,"description":"Overall compatibility score from 0 (fully opposed) to 100 (perfectly synchronized)."},"rating":{"type":"string","example":"Well Aligned","description":"Compatibility rating label. One of: Highly Aligned, Well Aligned, Moderately Aligned, Misaligned, Opposed."},"cycles":{"type":"object","additionalProperties":{"type":"object","properties":{"person1Value":{"type":"number","example":74,"description":"Person 1 cycle value on the target date (-100 to 100)."},"person2Value":{"type":"number","example":55,"description":"Person 2 cycle value on the target date (-100 to 100)."},"difference":{"type":"number","example":19,"description":"Absolute difference between the two values (0-200). Lower values indicate better alignment."},"alignment":{"type":"number","example":90,"description":"Alignment score from 0 (perfectly opposed) to 100 (perfectly in sync)."},"phase":{"type":"string","example":"in_sync","description":"Alignment phase. One of: in_sync, complementary, neutral, opposing."},"description":{"type":"string","example":"Both partners share similar physical energy levels. Shared activities, exercise, and daily rhythms align naturally.","description":"Human-readable description of how this cycle alignment affects the relationship."}},"required":["person1Value","person2Value","difference","alignment","phase","description"]},"description":"Per-cycle compatibility analysis for physical, emotional, and intellectual cycles."},"strengths":{"type":"array","items":{"type":"string"},"example":["Good overall energy match with healthy variation","Complementary differences prevent stagnation","Strong alignment in at least two primary cycles"],"description":"Relationship strengths based on the compatibility profile."},"challenges":{"type":"array","items":{"type":"string"},"example":["One cycle may be out of sync, requiring awareness","Minor timing differences in energy peaks and valleys"],"description":"Potential relationship challenges to be aware of."},"advice":{"type":"string","example":"Your cycles are well matched today. Lean into the aligned areas and be patient with the one dimension that may differ. Small adjustments keep your connection smooth.","description":"Practical relationship guidance based on the combined cycle analysis."},"dailySync":{"type":"object","properties":{"physicalDiff":{"type":"number","example":19,"description":"Absolute difference in physical cycle values (0-200). Lower = more aligned."},"emotionalDiff":{"type":"number","example":45,"description":"Absolute difference in emotional cycle values (0-200). Lower = more aligned."},"intellectualDiff":{"type":"number","example":12,"description":"Absolute difference in intellectual cycle values (0-200). Lower = more aligned."}},"required":["physicalDiff","emotionalDiff","intellectualDiff"]}},"required":["person1","person2","targetDate","overallScore","rating","cycles","strengths","challenges","advice","dailySync"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/phases":{"post":{"operationId":"getPhases","tags":["Biorhythm"],"summary":"Get phase info - Lightweight cycle status for dashboards and widgets","description":"Get current phase information for all 10 biorhythm cycles without the full interpretation payload. Returns value, phase name, phase label, day position within cycle, cycle period, days until next critical crossing, and short-term trend for each cycle. Includes a compact summary string. Designed as a lightweight endpoint for dashboards, widgets, status bars, and quick-check interfaces that need biorhythm phase data without editorial text.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"targetDate":{"type":"string","format":"date","example":"2026-04-10","description":"Date to get phase information for in YYYY-MM-DD format. Defaults to today (UTC)."}},"required":["birthDate"]}}}},"responses":{"200":{"description":"Phase information for all 10 cycles with summary","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Birth date used for this calculation."},"targetDate":{"type":"string","example":"2026-04-10","description":"Date this phase info is for."},"daysSinceBirth":{"type":"number","example":13049,"description":"Total days alive from birth date to target date."},"phases":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number","example":74,"description":"Cycle value from -100 to 100."},"phase":{"type":"string","example":"high","description":"Current phase identifier."},"phaseLabel":{"type":"string","example":"High Energy","description":"Human-readable phase label."},"dayInCycle":{"type":"number","example":8,"description":"Current day position within the cycle."},"totalDays":{"type":"number","example":23,"description":"Cycle period in days. 0 for composite cycles (passion, mastery, wisdom)."},"daysUntilCritical":{"type":"number","example":9,"description":"Days until next zero crossing."},"trend":{"type":"string","example":"rising","description":"Short-term direction: rising, falling, peaking, or bottoming."}},"required":["value","phase","phaseLabel","dayInCycle","totalDays","daysUntilCritical","trend"]},"description":"Phase information for all 10 cycles keyed by cycle ID."},"summary":{"type":"string","example":"3 cycles rising, 2 at peak, 1 critical","description":"Quick overview string summarizing the current state of all cycles."}},"required":["birthDate","targetDate","daysSinceBirth","phases","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/biorhythm/daily":{"post":{"operationId":"getDailyBiorhythm","tags":["Biorhythm"],"summary":"Get daily biorhythm - Seeded reading for daily check-in features","description":"Get a daily biorhythm reading with seeded randomness for consistent \"biorhythm of the day\" features. Same seed and same date always produce the same reading, perfect for daily push notifications, morning briefings, and wellness app check-ins. Returns energy rating, overall phase, a spotlight on one featured cycle, quick-read values for all three primary cycles, a daily message, and actionable advice. The spotlight cycle is deterministically selected by the seed, creating variety across users while maintaining consistency for each individual.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same reading every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily biorhythm reading with spotlight cycle and actionable guidance","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-10","description":"Date this daily reading is for (YYYY-MM-DD, UTC)."},"seed":{"type":"string","example":"user123-2026-04-10","description":"Computed seed used for this reading. Same seed always produces the same reading."},"energyRating":{"type":"number","example":7,"description":"Overall energy score from 1 to 10."},"overallPhase":{"type":"string","example":"high_energy","description":"Summary phase. One of: high_energy, mixed, recovery, critical."},"spotlight":{"type":"object","properties":{"cycle":{"type":"string","example":"emotional","description":"Which primary cycle is featured as the daily spotlight."},"value":{"type":"number","example":72,"description":"Current value of the spotlight cycle (-100 to 100)."},"phase":{"type":"string","example":"high","description":"Current phase of the spotlight cycle."},"message":{"type":"string","example":"Your emotional cycle is elevated and positive. Mood is stable and upbeat, and you feel naturally connected to others. Creative ideas come more easily and social interactions feel rewarding.","description":"Personalized message about the spotlight cycle and what it means for today."}},"required":["cycle","value","phase","message"]},"quickRead":{"type":"object","properties":{"physical":{"type":"number","example":45,"description":"Physical cycle value (-100 to 100)."},"emotional":{"type":"number","example":72,"description":"Emotional cycle value (-100 to 100)."},"intellectual":{"type":"number","example":-30,"description":"Intellectual cycle value (-100 to 100)."}},"required":["physical","emotional","intellectual"]},"dailyMessage":{"type":"string","example":"Your biorhythm for 2026-01-28: Energy rating 8/10 (High). Emotional cycle is high energy at 72%.","description":"Concise daily biorhythm message combining energy rating and spotlight cycle."},"advice":{"type":"string","example":"Lean into collaborative projects and relationship building.","description":"Actionable 1-2 sentence guidance for the day."}},"required":["date","seed","energyRating","overallPhase","spotlight","quickRead","dailyMessage","advice"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/daily":{"post":{"operationId":"getDailyHexagram","tags":["I-Ching"],"summary":"Get daily I-Ching hexagram","description":"Receive a daily I-Ching hexagram for guidance and reflection. This endpoint uses seeded randomness to ensure the same seed gets the same hexagram on the same day - perfect for \"Hexagram of the Day\" features in oracle apps, meditation platforms, and daily wisdom tools. Returns the hexagram with judgment, image, and interpretations for love, career, decisions, and practical advice based on ancient Chinese wisdom from the Book of Changes.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily hexagram reading with full interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-28","description":"Date this daily hexagram is for (YYYY-MM-DD, UTC)."},"seed":{"type":"string","example":"user123-2026-01-28","description":"Computed seed used for this reading. Same seed always produces the same hexagram."},"hexagram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hexagram number in King Wen sequence (1-64)."},"symbol":{"type":"string","example":"䷀","description":"Unicode hexagram symbol for display."},"chinese":{"type":"string","example":"乾","description":"Original Chinese name."},"english":{"type":"string","example":"The Creative","description":"English translation of the hexagram name."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization with tone marks."},"upperTrigram":{"type":"string","example":"Heaven","description":"Upper trigram (lines 4-6)."},"lowerTrigram":{"type":"string","example":"Heaven","description":"Lower trigram (lines 1-3)."},"judgment":{"type":"string","example":"Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","example":"Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","example":"A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.","description":"General life situation interpretation."},"love":{"type":"string","example":"A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.","description":"Love and relationship guidance."},"career":{"type":"string","example":"Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.","description":"Career and professional interpretation."},"decision":{"type":"string","example":"The time is right for bold action. Trust your instincts and move forward with confidence.","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","example":"Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.","description":"Practical wisdom and actionable advice."}},"required":["general","love","career","decision","advice"],"description":"Modern interpretations across life areas based on ancient I-Ching wisdom."}},"required":["number","symbol","chinese","english","pinyin","upperTrigram","lowerTrigram","judgment","image","interpretation"]},"dailyMessage":{"type":"string","example":"Your hexagram for 2026-01-28: The Creative (乾). Be like the heavens: consistent, powerful, and untiring.","description":"Concise daily message summarizing the hexagram guidance"}},"required":["date","seed","hexagram","dailyMessage"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Failed to generate daily hexagram","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}}}}},"/iching/daily/cast":{"post":{"operationId":"castDailyReading","tags":["I-Ching"],"summary":"Cast daily I-Ching reading with changing lines","description":"Cast a complete daily I-Ching reading using the traditional three-coin method with seeded randomness. Unlike the simple daily hexagram, this provides the full casting experience with line values (6-9), changing line positions, and the resulting hexagram if transformation occurs. Same seed + same date = same casting result. Perfect for I-Ching divination apps requiring authentic oracle experience with daily consistency.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Complete daily casting with primary and resulting hexagrams","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-28","description":"Date this daily casting is for (YYYY-MM-DD, UTC)."},"seed":{"type":"string","example":"user123-2026-01-28","description":"Computed seed for reproducible castings."},"hexagram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hexagram number in King Wen sequence (1-64)."},"symbol":{"type":"string","example":"䷀","description":"Unicode hexagram symbol for display."},"chinese":{"type":"string","example":"乾","description":"Original Chinese name."},"english":{"type":"string","example":"The Creative","description":"English translation of the hexagram name."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization with tone marks."},"upperTrigram":{"type":"string","example":"Heaven","description":"Upper trigram (lines 4-6)."},"lowerTrigram":{"type":"string","example":"Heaven","description":"Lower trigram (lines 1-3)."},"judgment":{"type":"string","example":"Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","example":"Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","example":"A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.","description":"General life situation interpretation."},"love":{"type":"string","example":"A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.","description":"Love and relationship guidance."},"career":{"type":"string","example":"Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.","description":"Career and professional interpretation."},"decision":{"type":"string","example":"The time is right for bold action. Trust your instincts and move forward with confidence.","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","example":"Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.","description":"Practical wisdom and actionable advice."}},"required":["general","love","career","decision","advice"],"description":"Modern interpretations across life areas based on ancient I-Ching wisdom."}},"required":["number","symbol","chinese","english","pinyin","upperTrigram","lowerTrigram","judgment","image","interpretation"]},"lines":{"type":"array","items":{"type":"number"},"example":[7,8,9,7,6,8],"description":"Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing)."},"changingLinePositions":{"type":"array","items":{"type":"number"},"example":[3,5],"description":"Positions of changing lines (1-6, bottom to top). These lines transform yin to yang or vice versa."},"changingLines":{"type":"array","items":{"$ref":"#/components/schemas/ChangingLine"},"description":"The oracle statement and meaning of each line that came up CHANGING, and only those. The changing lines are what the cast is actually about, so this saves a second call to read them and stops a consuming agent from having to invent them."},"resultingHexagram":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"Hexagram number in King Wen sequence (1-64)."},"symbol":{"type":"string","example":"䷀","description":"Unicode hexagram symbol for display."},"chinese":{"type":"string","example":"乾","description":"Original Chinese name."},"english":{"type":"string","example":"The Creative","description":"English translation of the hexagram name."},"pinyin":{"type":"string","example":"Qián","description":"Pinyin romanization with tone marks."},"upperTrigram":{"type":"string","example":"Heaven","description":"Upper trigram (lines 4-6)."},"lowerTrigram":{"type":"string","example":"Heaven","description":"Lower trigram (lines 1-3)."},"judgment":{"type":"string","example":"Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","example":"Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","example":"A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.","description":"General life situation interpretation."},"love":{"type":"string","example":"A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.","description":"Love and relationship guidance."},"career":{"type":"string","example":"Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.","description":"Career and professional interpretation."},"decision":{"type":"string","example":"The time is right for bold action. Trust your instincts and move forward with confidence.","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","example":"Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.","description":"Practical wisdom and actionable advice."}},"required":["general","love","career","decision","advice"],"description":"Modern interpretations across life areas based on ancient I-Ching wisdom."}},"required":["number","symbol","chinese","english","pinyin","upperTrigram","lowerTrigram","judgment","image","interpretation"],"description":"Hexagram after transformation (if changing lines present)"}},"required":["date","seed","lines","changingLinePositions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/hexagrams":{"get":{"operationId":"listHexagrams","tags":["I-Ching"],"summary":"List all 64 hexagrams","description":"Browse all 64 I-Ching hexagrams from the Book of Changes with their Chinese names, English translations, and trigram compositions. The hexagrams are ordered by the traditional King Wen sequence used in I-Ching divination for 3,000 years. Each hexagram represents a unique life situation combining two trigrams (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake) into profound wisdom for decision-making and self-understanding.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":64,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-64, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-64, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"List of hexagrams with basic information.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":64,"description":"Total number of I-Ching hexagrams (always 64)."},"limit":{"type":"number","example":20,"description":"Page size used for this response."},"offset":{"type":"number","example":0,"description":"Number of hexagrams skipped. Use with limit for pagination."},"hexagrams":{"type":"array","items":{"$ref":"#/components/schemas/BasicHexagram"},"description":"Hexagrams for the current page. Use /hexagrams/{number} for full details."}},"required":["total","limit","offset","hexagrams"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/hexagrams/random":{"get":{"operationId":"getRandomHexagram","tags":["I-Ching"],"summary":"Get a random hexagram","description":"Receive a random I-Ching hexagram with full interpretation. Perfect for daily oracle features, meditation prompts, or exploring the Book of Changes. Returns complete hexagram data including judgment, image, interpretations for love/career/decisions, and all six changing line meanings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"A random hexagram with full details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hexagram"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No hexagrams available.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/hexagrams/lookup":{"get":{"operationId":"lookupHexagram","tags":["I-Ching"],"summary":"Lookup hexagram by line pattern","description":"Find an I-Ching hexagram by its binary line pattern. Provide 6 digits (0 or 1) representing broken (yin) and solid (yang) lines from bottom to top. Use this for custom divination interfaces where users input their own line configurations, or to find hexagrams matching specific trigram combinations. Example: \"111111\" returns Hexagram 1 (The Creative), \"000000\" returns Hexagram 2 (The Receptive).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","pattern":"^[01]{6}$","example":"111111","description":"Six-digit binary pattern (0=yin/broken, 1=yang/solid) from bottom to top."},"required":true,"description":"Six-digit binary pattern (0=yin/broken, 1=yang/solid) from bottom to top.","name":"lines","in":"query"}],"responses":{"200":{"description":"Matching hexagram.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hexagram"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No hexagram found for pattern.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/hexagrams/{number}":{"get":{"operationId":"getHexagram","tags":["I-Ching"],"summary":"Get hexagram by number","description":"Retrieve complete I-Ching hexagram details by King Wen sequence number (1-64). Returns the full hexagram with Chinese name, English translation, judgment text, image text, modern interpretations for general situations, love, career, and decision-making, plus all six changing line meanings. Use this to display detailed hexagram information after casting or for educational reference.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":64,"example":1,"description":"Hexagram number in King Wen sequence (1-64)."},"required":true,"description":"Hexagram number in King Wen sequence (1-64).","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Full hexagram details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hexagram"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Hexagram not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/cast":{"get":{"operationId":"castReading","tags":["I-Ching"],"summary":"Cast an I-Ching reading","description":"Generate an authentic I-Ching reading using the traditional three-coin casting method. Each of the six lines is determined by virtually tossing three coins, producing values 6-9 where 6 (old yin) and 9 (old yang) are changing lines. Returns the primary hexagram with full interpretation, the line values showing which lines are changing, and if any lines change, the resulting hexagram that the primary transforms into. Optionally provide a seed for reproducible castings. Perfect for divination apps, oracle features, and decision-making tools.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"user123-question1","description":"Optional seed for reproducible castings. Same seed = same casting every time. Pass any unique identifier (userId, session token, question hash). Omit for random casting."},"required":false,"description":"Optional seed for reproducible castings. Same seed = same casting every time. Pass any unique identifier (userId, session token, question hash). Omit for random casting.","name":"seed","in":"query"}],"responses":{"200":{"description":"Complete I-Ching reading with primary and resulting hexagrams.","content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123-question1","description":"The seed used for this casting (if provided)"},"hexagram":{"allOf":[{"$ref":"#/components/schemas/Hexagram"},{"description":"Primary hexagram from the casting"}]},"lines":{"type":"array","items":{"type":"number"},"example":[7,8,9,7,6,8],"description":"Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing)"},"changingLinePositions":{"type":"array","items":{"type":"number"},"example":[3,5],"description":"Positions of changing lines (1-6, bottom to top)"},"resultingHexagram":{"allOf":[{"$ref":"#/components/schemas/Hexagram"},{"description":"Hexagram the primary transforms into after changing lines (present only if there are changing lines)"}]}},"required":["lines","changingLinePositions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/trigrams":{"get":{"operationId":"listTrigrams","tags":["I-Ching"],"summary":"List all 8 trigrams","description":"Retrieve all 8 I-Ching trigrams (bagua) - the fundamental building blocks of hexagrams. Each trigram consists of three lines and represents a primal force of nature: Heaven (Qian), Earth (Kun), Thunder (Zhen), Wind (Xun), Water (Kan), Fire (Li), Mountain (Gen), and Lake (Dui). Understanding trigrams is essential for interpreting hexagram meanings, as each hexagram combines an upper and lower trigram.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"List of all 8 trigrams with basic information.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":8,"description":"Total number of I-Ching trigrams (always 8)."},"trigrams":{"type":"array","items":{"$ref":"#/components/schemas/BasicTrigram"},"description":"All 8 trigrams (bagua) with basic details."}},"required":["total","trigrams"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/iching/trigrams/{id}":{"get":{"operationId":"getTrigram","tags":["I-Ching"],"summary":"Get trigram by number or name","description":"Retrieve a specific I-Ching trigram by its number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake). Returns complete trigram information including Chinese name, pinyin, element associations, core attributes, and symbolic meaning. Use this to understand the component trigrams of any hexagram.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"Heaven","description":"Trigram number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake)."},"required":true,"description":"Trigram number (1-8) or English name (Heaven, Earth, Thunder, Wind, Water, Fire, Mountain, Lake).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Trigram details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trigram"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Trigram not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/zodiac/{sign}":{"get":{"operationId":"getCrystalsByZodiac","tags":["Crystals and Healing Stones"],"summary":"Crystals by Zodiac Sign","description":"Get healing crystals and gemstones associated with a specific zodiac sign. Returns summary data for each crystal. Use the /crystals/:id detail endpoint for full healing properties. Supports all 12 zodiac signs from Aries through Pisces. Perfect for personalized crystal recommendations based on astrological birth chart data.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"example":"pisces","description":"Zodiac sign name, case-insensitive (e.g., pisces, Pisces, PISCES all work). Valid: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces."},"required":true,"description":"Zodiac sign name, case-insensitive (e.g., pisces, Pisces, PISCES all work). Valid: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces.","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":30,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-30, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-30, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of crystals associated with the zodiac sign","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Pisces","description":"The zodiac sign that was queried."},"total":{"type":"number","example":9,"description":"Total number of crystals associated with this zodiac sign."},"limit":{"type":"number","example":20,"description":"Maximum crystals returned per page."},"offset":{"type":"number","example":0,"description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."}},"required":["name","id","imageUrl","colors"]},"description":"Crystal summaries for this zodiac sign. Call /crystals/:id for full healing properties."}},"required":["sign","total","limit","offset","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/chakra/{chakra}":{"get":{"operationId":"getCrystalsByChakra","tags":["Crystals and Healing Stones"],"summary":"Crystals by Chakra","description":"Get healing crystals and gemstones that resonate with a specific chakra energy center. Returns summary data for each crystal. Use the /crystals/:id detail endpoint for full healing properties. Supports all 7 primary chakras: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, and Crown. Essential for crystal grid building, chakra balancing, and energy healing applications.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Root","Sacral","Solar Plexus","Heart","Throat","Third Eye","Crown"],"example":"Heart","description":"Chakra name, case-insensitive (e.g., heart, Heart, HEART all work). Valid: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown."},"required":true,"description":"Chakra name, case-insensitive (e.g., heart, Heart, HEART all work). Valid: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.","name":"chakra","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":30,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-30, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-30, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of crystals for the specified chakra","content":{"application/json":{"schema":{"type":"object","properties":{"chakra":{"type":"string","example":"Heart","description":"The chakra energy center that was queried."},"total":{"type":"number","example":33,"description":"Total number of crystals associated with this chakra."},"limit":{"type":"number","example":20,"description":"Maximum crystals returned per page."},"offset":{"type":"number","example":0,"description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."}},"required":["name","id","imageUrl","colors"]},"description":"Crystal summaries for this chakra. Call /crystals/:id for full healing properties."}},"required":["chakra","total","limit","offset","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/element/{element}":{"get":{"operationId":"getCrystalsByElement","tags":["Crystals and Healing Stones"],"summary":"Crystals by Element","description":"Get healing crystals and gemstones associated with a specific natural element. Returns summary data for each crystal. Use the /crystals/:id detail endpoint for full healing properties. Supports five elements: Earth, Water, Fire, Air, and Storm. Essential for elemental crystal selection, nature-based healing, and element-themed crystal grid applications.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["Earth","Water","Fire","Air","Storm"],"example":"Water","description":"Element name, case-insensitive (e.g., water, Water, WATER all work). Valid: Earth, Water, Fire, Air, Storm."},"required":true,"description":"Element name, case-insensitive (e.g., water, Water, WATER all work). Valid: Earth, Water, Fire, Air, Storm.","name":"element","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":30,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-30, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-30, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of crystals for the specified element","content":{"application/json":{"schema":{"type":"object","properties":{"element":{"type":"string","example":"Water","description":"The element that was queried."},"total":{"type":"number","example":29,"description":"Total number of crystals associated with this element."},"limit":{"type":"number","example":20,"description":"Maximum crystals returned per page."},"offset":{"type":"number","example":0,"description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."}},"required":["name","id","imageUrl","colors"]},"description":"Crystal summaries for this element. Call /crystals/:id for full healing properties."}},"required":["element","total","limit","offset","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/birthstone/{month}":{"get":{"operationId":"getBirthstones","tags":["Crystals and Healing Stones"],"summary":"Birthstone Crystals by Month","description":"Get the traditional birthstone crystals for a given birth month. Returns summary data for each crystal. Use the /crystals/:id detail endpoint for full healing properties. Based on GIA-authoritative birthstone assignments. Perfect for birthday gift recommendations, personalized crystal suggestions, and birthstone jewelry applications.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Birth month as a number from 1 (January) to 12 (December)."},"required":true,"description":"Birth month as a number from 1 (January) to 12 (December).","name":"month","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Birthstone crystals for the specified month","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"number","example":2,"description":"The month number that was queried (1-12)."},"monthName":{"type":"string","example":"February","description":"Full name of the queried month."},"total":{"type":"number","example":1,"description":"Number of birthstone crystals for this month."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."}},"required":["name","id","imageUrl","colors"]},"description":"Birthstone crystals for this month. Call /crystals/:id for full healing properties."}},"required":["month","monthName","total","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/search":{"get":{"operationId":"searchCrystals","tags":["Crystals and Healing Stones"],"summary":"Search Crystals","description":"Search for healing crystals by keyword or name. Matches against crystal names, healing keywords, descriptions, and spiritual/emotional/physical meaning fields. Returns summary data for each crystal. Use the /crystals/:id detail endpoint for full healing properties. Useful for building crystal search bars, keyword-based recommendation features, and healing property lookups.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":50,"example":"love","description":"Search query (2-50 characters). Matches against crystal names, keywords, descriptions, and meaning fields. Case-insensitive partial matching."},"required":true,"description":"Search query (2-50 characters). Matches against crystal names, keywords, descriptions, and meaning fields. Case-insensitive partial matching.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-50, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-50, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Crystals matching the search query","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"love","description":"The search query that was used."},"total":{"type":"number","example":32,"description":"Total number of crystals matching the query."},"limit":{"type":"number","example":20,"description":"Maximum crystals returned per page."},"offset":{"type":"number","example":0,"description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."}},"required":["name","id","imageUrl","colors"]},"description":"Matching crystal summaries. Call /crystals/:id for full healing properties."}},"required":["query","total","limit","offset","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/pairings/{id}":{"get":{"operationId":"getCrystalPairings","tags":["Crystals and Healing Stones"],"summary":"Crystal Pairings","description":"Get crystals that pair well with a given crystal for enhanced healing combinations. Returns the source crystal along with its recommended companion stones and their properties. Essential for crystal grid building, healing combination recommendations, and crystal shop cross-sell features.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier to find pairings for, case-insensitive (e.g., \"amethyst\", \"Amethyst\", \"rose-quartz\" all resolve)."},"required":true,"description":"URL-safe crystal identifier to find pairings for, case-insensitive (e.g., \"amethyst\", \"Amethyst\", \"rose-quartz\" all resolve).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Crystal pairing recommendations","content":{"application/json":{"schema":{"type":"object","properties":{"crystal":{"type":"string","example":"amethyst","description":"The crystal identifier that pairings were requested for."},"name":{"type":"string","example":"Amethyst","description":"Display name of the source crystal."},"count":{"type":"number","example":5,"description":"Number of recommended crystal pairings."},"pairings":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Citrine","description":"Paired crystal display name."},"id":{"type":"string","example":"citrine","description":"URL-safe identifier for the paired crystal."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/citrine.jpg","description":"URL to paired crystal photograph."},"description":{"type":"string","example":"To manifest your dreams, you first need to know what they are. By activating both your imagination and your will, citrine helps you clearly envision what you want, and then gives you the persistence to see it through.","description":"Brief overview of the paired crystal."},"chakras":{"type":"array","items":{"type":"string"},"example":["Sacral","Solar Plexus","Crown"],"description":"Chakra associations for the paired crystal."},"keywords":{"type":["array","null"],"items":{"type":"string"},"example":["Happiness","Prosperity","Generosity","Creativity","Pleasure"],"description":"Healing property keywords for the paired crystal. Null when keyword data is unavailable."}},"required":["name","id","imageUrl","description","chakras","keywords"]},"description":"Crystals recommended for use alongside the source crystal for synergistic healing."}},"required":["crystal","name","count","pairings"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Crystal not found in database","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/daily":{"post":{"operationId":"getDailyCrystal","tags":["Crystals and Healing Stones"],"summary":"Daily Crystal","description":"Get the crystal of the day as a discovery teaser. Returns a deterministic crystal based on the current date (or a provided seed date), ensuring all users see the same crystal for any given day. Use the /crystals/:id detail endpoint for complete spiritual, emotional, and physical healing properties. Perfect for daily guidance features, push notifications, wellness app widgets, and crystal journal integrations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same crystal every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily crystal teaser with summary information","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-03-05","description":"The date used for crystal selection (UTC)."},"seed":{"type":"string","example":"user123-2026-03-05","description":"Computed seed used for this reading. Same seed always produces the same crystal."},"name":{"type":"string","example":"Rose Quartz","description":"Display name of the crystal selected for this date."},"id":{"type":"string","example":"rose-quartz","description":"URL-safe identifier. Call /crystals/:id for full healing properties."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/rose-quartz.jpg","description":"URL to crystal photograph. Use for daily crystal card display and visual features."},"description":{"type":"string","example":"Rose quartz is the classic stone of love. It helps dissolve old hurts and open the heart to trust in love and have faith in the benevolence of the Universe.","description":"Overview of the crystal covering primary healing purpose and benefits."},"chakras":{"type":"array","items":{"type":"string"},"example":["Heart"],"description":"Chakra energy centers this crystal resonates with for energy healing practice."},"zodiacSigns":{"type":["array","null"],"items":{"type":"string"},"example":["Taurus","Libra"],"description":"Zodiac signs this crystal is traditionally associated with. Null when zodiac data is unavailable."},"affirmation":{"type":"string","example":"I am aligned with the energy of unconditional love.","description":"Positive affirmation aligned with the selected crystal. Use for daily affirmation features and meditation guidance."}},"required":["date","seed","name","id","imageUrl","description","chakras","zodiacSigns","affirmation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/random":{"get":{"operationId":"getRandomCrystal","tags":["Crystals and Healing Stones"],"summary":"Random Crystal","description":"Get a randomly selected healing crystal as a discovery teaser. Returns a different crystal on each request (non-deterministic). Use the /crystals/:id detail endpoint for complete spiritual, emotional, and physical healing properties. Perfect for crystal discovery features, surprise crystal picks, crystal roulette games, and exploration widgets. For a deterministic daily crystal that is the same for all users on a given date, use the /daily endpoint instead.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"A randomly selected crystal with summary information","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Citrine","description":"Display name of the randomly selected crystal."},"id":{"type":"string","example":"citrine","description":"URL-safe identifier. Call /crystals/:id for full healing properties."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/citrine.jpg","description":"URL to crystal photograph for visual display."},"description":{"type":"string","example":"To manifest your dreams, you first need to know what they are. By activating both your imagination and your will, citrine helps you clearly envision what you want, and then gives you the persistence to see it through.","description":"Overview of the crystal covering primary healing purpose and benefits."},"chakras":{"type":"array","items":{"type":"string"},"example":["Sacral","Solar Plexus","Crown"],"description":"Chakra energy centers this crystal resonates with."},"zodiacSigns":{"type":["array","null"],"items":{"type":"string"},"example":["Aries","Gemini","Leo","Libra"],"description":"Zodiac signs this crystal is traditionally associated with. Null when zodiac data is unavailable."},"affirmation":{"type":"string","example":"I am aligned with the energy of happiness.","description":"Positive affirmation aligned with the selected crystal energy."}},"required":["name","id","imageUrl","description","chakras","zodiacSigns","affirmation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/colors":{"get":{"operationId":"listCrystalColors","tags":["Crystals and Healing Stones"],"summary":"List Crystal Colors","description":"List all unique crystal colors available in the database. Use these values with the color filter on GET /crystals to find crystals by color. Essential reference endpoint for building color-based crystal browsing, visual crystal pickers, and filtering UI.","security":[{"apiKey":[]}],"responses":{"200":{"description":"All unique crystal colors sorted alphabetically","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":92,"description":"Total number of unique color values in the database."},"colors":{"type":"array","items":{"type":"string"},"example":["apple green","azure blue","beige","black","blue-green"],"description":"Alphabetically sorted list of all unique crystal colors. Pass any value to the color filter on GET /crystals."}},"required":["count","colors"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/planets":{"get":{"operationId":"listCrystalPlanets","tags":["Crystals and Healing Stones"],"summary":"List Crystal Planets","description":"List all unique planetary associations available in the database. Use these values with the planet filter on GET /crystals to find crystals by ruling planet. Essential reference endpoint for astrology app builders who want to recommend crystals based on planetary placements in a birth chart.","security":[{"apiKey":[]}],"responses":{"200":{"description":"All unique planetary associations sorted alphabetically","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":13,"description":"Total number of unique planetary values in the database."},"planets":{"type":"array","items":{"type":"string"},"example":["Earth","Jupiter","Mars","Mercury","Moon"],"description":"Alphabetically sorted list of all unique planetary associations. Pass any value to the planet filter on GET /crystals."}},"required":["count","planets"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals":{"get":{"operationId":"listCrystals","tags":["Crystals and Healing Stones"],"summary":"List All Crystals","description":"Retrieve healing crystals and gemstones with pagination. Supports optional filtering by chakra, zodiac sign, element, color, or planet. Returns minimal summary fields per crystal. Use the detail endpoint for full healing properties. Perfect for building crystal explorer apps, healing stone guides, and personalized crystal recommendation engines.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["Root","Sacral","Solar Plexus","Heart","Throat","Third Eye","Crown"],"example":"Heart","description":"Filter by chakra association, case-insensitive. Valid values: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown."},"required":false,"description":"Filter by chakra association, case-insensitive. Valid values: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.","name":"chakra","in":"query"},{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"example":"pisces","description":"Filter by zodiac sign, case-insensitive. Valid values: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces."},"required":false,"description":"Filter by zodiac sign, case-insensitive. Valid values: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces.","name":"zodiac","in":"query"},{"schema":{"type":"string","enum":["Earth","Water","Fire","Air","Storm"],"example":"Water","description":"Filter by elemental association, case-insensitive. Valid values: Earth, Water, Fire, Air, Storm."},"required":false,"description":"Filter by elemental association, case-insensitive. Valid values: Earth, Water, Fire, Air, Storm.","name":"element","in":"query"},{"schema":{"type":"string","example":"pink","description":"Filter by crystal color (partial match, case-insensitive). E.g., \"pink\", \"green\", \"blue\", \"purple\". Use GET /colors for valid values."},"required":false,"description":"Filter by crystal color (partial match, case-insensitive). E.g., \"pink\", \"green\", \"blue\", \"purple\". Use GET /colors for valid values.","name":"color","in":"query"},{"schema":{"type":"string","example":"Venus","description":"Filter by planetary association (partial match, case-insensitive). E.g., \"Venus\", \"Moon\", \"Jupiter\". Use GET /planets for valid values."},"required":false,"description":"Filter by planetary association (partial match, case-insensitive). E.g., \"Venus\", \"Moon\", \"Jupiter\". Use GET /planets for valid values.","name":"planet","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-100, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of crystals with summary information","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":91,"description":"Total number of crystals matching the filter criteria."},"limit":{"type":"number","example":20,"description":"Maximum crystals returned per page."},"offset":{"type":"number","example":0,"description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Crystal display name."},"id":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to crystal photograph for visual identification."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable."},"chakras":{"type":"array","items":{"type":"string"},"example":["Third Eye","Crown"],"description":"Chakra energy centers this crystal resonates with. One of: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown."}},"required":["name","id","imageUrl","colors","chakras"]},"description":"Crystal summaries for the current page."}},"required":["total","limit","offset","crystals"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/crystals/{id}":{"get":{"operationId":"getCrystal","tags":["Crystals and Healing Stones"],"summary":"Get Crystal Healing Properties","description":"Get complete healing properties and metaphysical data for a specific crystal or gemstone. Returns spiritual, emotional, and physical healing interpretations along with chakra associations, zodiac connections, elemental properties, and crystal pairing recommendations. Authoritative interpretations covering all major healing crystals.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"amethyst","description":"URL-safe crystal identifier, case-insensitive (e.g., \"amethyst\", \"Amethyst\", \"rose-quartz\" all resolve). Must match an entry in the database."},"required":true,"description":"URL-safe crystal identifier, case-insensitive (e.g., \"amethyst\", \"Amethyst\", \"rose-quartz\" all resolve). Must match an entry in the database.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Complete crystal healing properties with all associations","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Amethyst","description":"Display name of the crystal or healing stone."},"id":{"type":"string","example":"amethyst","description":"URL-safe identifier for the crystal."},"imageUrl":{"type":["string","null"],"example":"https://roxyapi.com/img/crystals/amethyst.jpg","description":"URL to a high-quality crystal photograph. Use for visual crystal guides, product listings, and crystal identification features."},"description":{"type":"string","example":"Amethyst is a powerful purple quartz prized for protection, intuition, and spiritual growth. It is used for breaking bad habits, deepening meditation, and connecting with higher consciousness.","description":"Overview of the crystal covering its primary healing purpose, spiritual significance, and key benefits."},"meaning":{"type":"object","properties":{"spiritual":{"type":["string","null"],"example":"Amethyst is thought to provide a protective shield against negative energies, transmuting them into loving, positive vibrations. It is also traditionally associated with clarity of thought, intuition, and inspiration.","description":"Spiritual and metaphysical healing properties including energy work, meditation benefits, and higher consciousness connections. Null when spiritual interpretation is unavailable."},"emotional":{"type":"string","example":"Its calming energy supports emotional balance, encourages spiritual awareness, and promotes mindfulness. It encourages mental focus, memory, motivation, and dream recall, while assisting in maintaining inner calm and spiritual wisdom.","description":"Emotional healing properties including stress relief, relationship support, and emotional balance benefits."},"physical":{"type":["string","null"],"example":"Amethyst is traditionally believed to support overall vitality and holistic well-being. Crystal enthusiasts associate its energy with enhancing hormone balance, tuning the endocrine system, and strengthening the immune system.","description":"Physical healing associations traditionally attributed to this crystal in crystal healing practice. Null when physical healing data is unavailable."}},"required":["spiritual","emotional","physical"],"description":"Detailed healing interpretations across three areas: spiritual and metaphysical, emotional and psychological, and physical body associations."},"chakras":{"type":"array","items":{"type":"string"},"example":["Third Eye","Crown"],"description":"Chakra energy centers this crystal resonates with. One of: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown."},"zodiacSigns":{"type":["array","null"],"items":{"type":"string"},"example":["Virgo","Sagittarius","Capricorn","Aquarius","Pisces"],"description":"Zodiac signs this crystal is traditionally associated with. Null when zodiac data is unavailable. Useful for personalized crystal recommendations based on birth chart."},"planet":{"type":["string","null"],"example":"Jupiter","description":"Ruling planet or celestial body associated with this crystal in astrological tradition. Null when planetary association is unavailable."},"elements":{"type":["array","null"],"items":{"type":"string"},"example":["Air","Water"],"description":"Elemental associations (Earth, Water, Fire, Air, Storm) connecting the crystal to natural forces and energy types. Null when elemental data is unavailable."},"colors":{"type":["array","null"],"items":{"type":"string"},"example":["violet","purple"],"description":"Primary colors of this crystal variety. Null when color data is unavailable. Useful for color-based crystal selection and filtering."},"hardness":{"type":"number","example":7,"description":"Mohs hardness scale rating (1-10). Indicates durability for jewelry use. Quartz family is 7, Diamond is 10, Selenite is 2."},"numericalVibration":{"type":"number","example":3,"description":"Numerological vibration number linking this crystal to numerology meanings. Connects crystal healing with numerology practice."},"keywords":{"type":["array","null"],"items":{"type":"string"},"example":["Nobility","Spiritual Awareness","Psychic Abilities","Inner Peace","Meditation"],"description":"Keywords capturing the core healing properties and spiritual themes of this crystal. The count varies by stone, from a single keyword up to twenty. Null when keyword data is unavailable."},"birthMonth":{"type":["number","null"],"example":2,"description":"Birth month (1-12) if this crystal is a traditional birthstone. Null if not a birthstone. January is 1, December is 12."},"affirmation":{"type":"string","example":"I am filled with nobility.","description":"Positive affirmation aligned with this crystal energy. Use for meditation, journaling, or daily affirmation features."},"pairsWith":{"type":"array","items":{"type":"string"},"example":["citrine","rose-quartz","clear-quartz","smoky-quartz","black-tourmaline"],"description":"Crystal identifiers that pair well with this stone for enhanced healing combinations. Use for crystal grid and pairing recommendations."}},"required":["name","id","imageUrl","description","meaning","chakras","zodiacSigns","planet","elements","colors","hardness","numericalVibration","keywords","birthMonth","affirmation","pairsWith"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Crystal not found in database","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/dreams/symbols":{"get":{"operationId":"searchDreamSymbols","tags":["Dreams"],"summary":"List and search dream symbols","description":"Browse and search our complete dream interpretation dictionary containing 2,000+ dream symbols with psychological meanings. Find dream meanings for animals (snake dreams, spider dreams, dog dreams), common scenarios (falling dreams, flying dreams, being chased, drowning), people (dreams about mother, father, baby, ex), objects (car, house, water, fire), emotions (fear, anxiety, love), body parts (teeth falling out, hair, eyes), colors, numbers, and abstract concepts. Filter by starting letter for A-Z navigation or search by keyword to find what your dreams mean.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"example":"water","description":"Search query to match against symbol names and meanings. Case-insensitive."},"required":false,"description":"Search query to match against symbol names and meanings. Case-insensitive.","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1,"example":"a","description":"Filter symbols by starting letter (a-z). Case-insensitive."},"required":false,"description":"Filter symbols by starting letter (a-z). Case-insensitive.","name":"letter","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-50, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-50, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of dream symbols with basic information.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":2526,"description":"Total number of dream symbols matching your search or filter criteria."},"limit":{"type":"number","example":50,"description":"Page size used for this response."},"offset":{"type":"number","example":0,"description":"Number of symbols skipped. Use with limit for pagination."},"symbols":{"type":"array","items":{"$ref":"#/components/schemas/BasicDreamSymbol"},"description":"Dream symbols for the current page. Use /symbols/{id} to get full interpretation."}},"required":["total","limit","offset","symbols"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/dreams/symbols/random":{"get":{"operationId":"getRandomSymbols","tags":["Dreams"],"summary":"Get random dream symbols","description":"Discover random dream symbols and their interpretations for daily dream insights and exploration. Each request returns different symbols from the 2,000+ dream meaning database - perfect for dream of the day features, dream journaling prompts, meditation on subconscious themes, or exploring what different dreams mean. Get one or multiple random dream interpretations with full psychological meanings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":10,"default":1,"example":1,"description":"Number of random symbols to return (1-10). Default: 1."},"required":false,"description":"Number of random symbols to return (1-10). Default: 1.","name":"count","in":"query"}],"responses":{"200":{"description":"Random dream symbol(s) with full interpretations.","content":{"application/json":{"schema":{"type":"object","properties":{"symbols":{"type":"array","items":{"$ref":"#/components/schemas/DreamSymbol"}}},"required":["symbols"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/dreams/symbols/letters":{"get":{"operationId":"getSymbolLetterCounts","tags":["Dreams"],"summary":"Get symbol counts by letter","description":"Get the count of dream symbols available for each letter A-Z. Build alphabetical dream dictionary navigation to help users browse dream interpretations by letter - from abandonment dreams to zodiac dreams. See how many dream meanings exist for each starting letter.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Symbol counts organized by starting letter.","content":{"application/json":{"schema":{"type":"object","properties":{"letters":{"type":"object","additionalProperties":{"type":"number","example":138,"description":"Number of dream symbols whose name starts with this letter. A letter with no symbols is absent from the map."},"example":{"a":138,"b":282,"c":324,"d":173},"description":"Map of starting letter to symbol count. Use to build A-Z dream dictionary navigation showing how many dream meanings exist per letter."},"total":{"type":"number","example":2526,"description":"Total number of dream symbols in the complete dream interpretation database."}},"required":["letters","total"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/dreams/symbols/{id}":{"get":{"operationId":"getDreamSymbol","tags":["Dreams"],"summary":"Get dream symbol details","description":"Get the complete dream interpretation for a specific symbol. Understand what your dream means with detailed psychological analysis covering subconscious symbolism, emotional significance, and connections to your waking life. Covers all major dream themes: snake dreams (hidden fears, transformation), falling dreams (loss of control, anxiety), water dreams (emotions, cleansing), death dreams (endings, transformation), teeth falling out (self-image, communication anxiety), being chased (avoidance, confronting fears), flying dreams (freedom, ambition), and thousands more dream meanings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"snake","description":"Unique symbol identifier in kebab-case (e.g., \"snake\", \"being-chased\", \"teeth-falling-out\")."},"required":true,"description":"Unique symbol identifier in kebab-case (e.g., \"snake\", \"being-chased\", \"teeth-falling-out\").","name":"id","in":"path"}],"responses":{"200":{"description":"Full dream symbol with interpretation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamSymbol"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Symbol not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/dreams/daily":{"post":{"operationId":"getDailyDreamSymbol","tags":["Dreams"],"summary":"Get daily dream symbol","description":"Receive a single dream symbol for daily reflection and subconscious exploration. Uses seeded randomness so the same seed gets the same symbol on the same day, perfect for \"Dream Symbol of the Day\" features. Provide a seed (userId, email hash, session token) for reproducible consistency, or omit for date-based daily symbols. Returns the symbol with full psychological interpretation. Great for dream journal apps, wellness platforms, morning ritual apps, and meditation tools.","security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same symbol every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily dream symbol with interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-28","description":"Date of the daily dream symbol in YYYY-MM-DD format (UTC). Determines which symbol is selected for seeded readings."},"seed":{"type":"string","example":"user123-2026-01-28","description":"Seed used for this daily reading. Same seed on the same date always produces the identical symbol."},"symbol":{"type":"object","properties":{"id":{"type":"string","example":"flying","description":"Unique symbol identifier in kebab-case. Use this to fetch full details via /symbols/{id}."},"name":{"type":"string","example":"Flying","description":"Display name of the dream symbol."},"letter":{"type":"string","example":"f","description":"Starting letter (a-z) for alphabetical navigation."},"meaning":{"type":"string","example":"Flying dreams can be the most exhilarating, liberating and instantly gratifying dreams you can ever have. These dreams are classified as lucid, suggesting that the dreamer is aware that they are dreaming.","description":"Full psychological dream interpretation explaining the subconscious symbolism, emotional significance, and waking-life connections."}},"required":["id","name","letter","meaning"]},"dailyMessage":{"type":"string","example":"Your dream symbol for 2026-01-28: Flying. Flying dreams can be the most exhilarating, liberating and instantly gratifying dreams you can ever have...","description":"Concise daily message summarizing the dream symbol and its key themes for quick reflection."}},"required":["date","seed","symbol","dailyMessage"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/angel-numbers/numbers":{"get":{"operationId":"listAngelNumbers","tags":["Angel Numbers"],"summary":"List All Angel Numbers","description":"Retrieve the complete database of angel numbers with summary information. Returns 75+ angel numbers covering root digits (0-9), master numbers (11, 22, 33), double digits (44-99), triple repeating (111-999), quad repeating (1111-9999), the mirror families (X0X like 101-909, X1X, four-digit mirrors like 1212-2121), palindromes (1221, 1331), compound sequences (911, 1122), and sequential numbers (123, 1234). Supports optional type filtering. Perfect for building angel number explorer apps, reference guides, and spiritual databases.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-50, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-50, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"},{"schema":{"type":"string","enum":["repeating","sequential","mirror","master","root","compound"],"example":"repeating","description":"Filter results by angel number pattern type. \"repeating\" returns numbers like 111, 444, 7777. \"sequential\" returns patterns like 1234. \"mirror\" returns palindrome or alternating patterns like 1212, 717. \"master\" returns 11, 22, 33. \"root\" returns single digits 0-9. \"compound\" returns mixed sequences with no pure pattern like 911, 1122."},"required":false,"description":"Filter results by angel number pattern type. \"repeating\" returns numbers like 111, 444, 7777. \"sequential\" returns patterns like 1234. \"mirror\" returns palindrome or alternating patterns like 1212, 717. \"master\" returns 11, 22, 33. \"root\" returns single digits 0-9. \"compound\" returns mixed sequences with no pure pattern like 911, 1122.","name":"type","in":"query"}],"responses":{"200":{"description":"List of angel numbers with summary information","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":78,"description":"Total number of angel numbers matching the applied filters. The full catalog size when unfiltered, fewer when filtered by type."},"limit":{"type":"number","example":20,"description":"Maximum items returned per page."},"offset":{"type":"number","example":0,"description":"Number of items skipped from the start of the result set."},"numbers":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","example":"111","description":"Angel number sequence as a string. Common patterns include triple repeating (111-999), quad repeating (1111-9999), master numbers (11, 22, 33), mirror patterns (1212), and sequential numbers (1234)."},"title":{"type":"string","example":"New Beginnings, Manifestation, and Alignment With Your Highest Purpose","description":"Short descriptive title capturing the core theme and spiritual significance of this angel number."},"coreMessage":{"type":"string","example":"Your focus is shaping what comes next. Give your attention to what you want rather than what you fear, because a new chapter is beginning.","description":"One to two sentence summary of the divine message. Ideal for push notifications, daily guidance widgets, and quick reference lookups."},"type":{"type":"string","example":"repeating","description":"Pattern classification of the angel number. \"repeating\" means all digits are the same (111, 4444). \"sequential\" means consecutive digits (1234). \"mirror\" means palindrome or alternating pattern (1212, 1221). \"master\" means numerology master number (11, 22, 33). \"root\" means single digit (0-9). \"compound\" means a mixed sequence with no pure pattern (911, 1122)."},"digitRoot":{"type":"number","example":3,"description":"Numerology digit root calculated by summing all digits and reducing to a single digit. Links each angel number to foundational numerology meaning. Master numbers 11, 22, 33 are preserved without further reduction."},"keywords":{"type":"array","items":{"type":"string"},"example":["new beginnings","manifestation","initiative","alignment","fresh start","leadership"],"description":"Five to eight keywords capturing the spiritual themes and energy of this angel number. Useful for search, filtering, and content generation."},"energy":{"type":"string","example":"positive","description":"Overall energy classification. \"positive\" indicates encouraging, uplifting energy. \"neutral\" indicates transitional energy (neither purely positive nor cautionary). \"cautionary\" indicates a gentle warning to rebalance or pay attention."}},"required":["number","title","coreMessage","type","digitRoot","keywords","energy"]},"description":"Array of angel number summaries for the current page."}},"required":["total","limit","offset","numbers"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/angel-numbers/numbers/{number}":{"get":{"operationId":"getAngelNumber","tags":["Angel Numbers"],"summary":"Get Angel Number Meaning","description":"Get the complete, authoritative meaning and interpretation for a specific angel number. Returns detailed spiritual, love, career, money, and twin flame interpretations, plus a biblical perspective and a shadow reading, along with keywords, affirmation, and actionable steps. Covers 75+ angel numbers including 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, 1212, 1234, and more. Authoritative interpretations covering all major angel number patterns.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"444","description":"Angel number sequence to look up (e.g., \"111\", \"444\", \"1212\", \"1234\"). Must match an entry in the database."},"required":true,"description":"Angel number sequence to look up (e.g., \"111\", \"444\", \"1212\", \"1234\"). Must match an entry in the database.","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Complete angel number meaning with all interpretations","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","example":"111","description":"Angel number sequence as a string. Common patterns include triple repeating (111-999), quad repeating (1111-9999), master numbers (11, 22, 33), mirror patterns (1212), and sequential numbers (1234)."},"title":{"type":"string","example":"New Beginnings, Manifestation, and Alignment With Your Highest Purpose","description":"Short descriptive title capturing the core theme and spiritual significance of this angel number."},"coreMessage":{"type":"string","example":"Your focus is shaping what comes next. Give your attention to what you want rather than what you fear, because a new chapter is beginning.","description":"One to two sentence summary of the divine message. Ideal for push notifications, daily guidance widgets, and quick reference lookups."},"type":{"type":"string","example":"repeating","description":"Pattern classification of the angel number. \"repeating\" means all digits are the same (111, 4444). \"sequential\" means consecutive digits (1234). \"mirror\" means palindrome or alternating pattern (1212, 1221). \"master\" means numerology master number (11, 22, 33). \"root\" means single digit (0-9). \"compound\" means a mixed sequence with no pure pattern (911, 1122)."},"digitRoot":{"type":"number","example":3,"description":"Numerology digit root calculated by summing all digits and reducing to a single digit. Links each angel number to foundational numerology meaning. Master numbers 11, 22, 33 are preserved without further reduction."},"keywords":{"type":"array","items":{"type":"string"},"example":["new beginnings","manifestation","initiative","alignment","fresh start","leadership"],"description":"Five to eight keywords capturing the spiritual themes and energy of this angel number. Useful for search, filtering, and content generation."},"energy":{"type":"string","example":"positive","description":"Overall energy classification. \"positive\" indicates encouraging, uplifting energy. \"neutral\" indicates transitional energy (neither purely positive nor cautionary). \"cautionary\" indicates a gentle warning to rebalance or pay attention."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","example":"Angel number 111 is one of the strongest manifestation signals in the angelic system. When it appears, the energy around you is ripe for new beginnings, and what you hold in your attention tends to take form more readily than usual.","description":"Two to three paragraph spiritual interpretation covering divine guidance, higher purpose, and the metaphysical significance of this angel number sequence."},"love":{"type":"string","example":"In love, 111 marks fresh starts and new possibility. For those who are single, it suggests that a meaningful connection may be forming, but it asks you first to align your own thoughts with the kind of love you want to receive.","description":"Love and relationship interpretation covering singles, couples, and those healing from past relationships. Includes romantic guidance and partnership advice."},"career":{"type":"string","example":"Professionally, 111 points to new opportunities taking shape. This is a favorable moment to start the venture, apply for the role, or launch the project you have been weighing, because your initiative carries extra momentum now.","description":"Career and vocation guidance: professional opportunities, calling, and practical work advice aligned with this angel number energy. Money and finances are returned separately in the money field."},"money":{"type":"string","example":"In money matters, 111 favors fresh starts. It is a supportive moment to open a new income stream, reset a budget, or change a financial habit, because the patterns you set now tend to take hold.","description":"Money, finances, and material abundance guidance, kept distinct from career and vocation. Covers income, spending, debt, and prosperity mindset for this angel number."},"twinFlame":{"type":"string","example":"For twin flames, 111 is a significant marker of either an approaching meeting or a clear step forward on the journey. If you have not yet met, 111 suggests that a meeting is drawing nearer.","description":"Twin flame connection interpretation covering union, separation, and spiritual growth within the twin flame journey."}},"required":["spiritual","love","career","money","twinFlame"]},"biblical":{"type":"string","example":"In the Bible the number 1 speaks of unity and primacy, the truth that God is one (Deuteronomy 6:4), and of beginnings. Angel numbers as personal codes are not a biblical concept, and Scripture does not single out 111.","description":"Biblical and religious perspective on the sequence, framed honestly. States plainly when a number is not a scriptural concept rather than inventing scripture."},"shadow":{"type":"string","example":"The shadow side of 111 is mistaking thought for action. The same focus that manifests can curdle into magical thinking, the belief that wanting something hard enough replaces the work of building it.","description":"Shadow or cautionary reading: the misuse, over-reliance, or imbalance this sequence can signal. Complements the energy classification."},"affirmation":{"type":"string","example":"My focus shapes my reality, so I give my attention to what I want to create.","description":"Positive affirmation aligned with this angel number. Can be used for daily affirmation features, meditation guidance, or spiritual journal prompts."},"actionSteps":{"type":"array","items":{"type":"string"},"example":["Notice where your thoughts have been pointing, since they are taking form","Set one clear, positive intention for what you want to begin","Take a concrete first step on something new you have been postponing","Watch for fresh opportunities and act on the ones that align"],"description":"Three to five specific, actionable steps to take when you see this angel number. Practical spiritual guidance for daily life."}},"required":["number","title","coreMessage","type","digitRoot","keywords","energy","meaning","biblical","shadow","affirmation","actionSteps"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Angel number not found in database","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/angel-numbers/lookup":{"get":{"operationId":"analyzeNumberSequence","tags":["Angel Numbers"],"summary":"Analyze Any Number Sequence","description":"Smart angel number analysis that works for ANY number sequence, not just known angel numbers. Automatically classifies the pattern type (repeating, sequential, mirror, master, root, compound), calculates the numerology digit root, checks the database for a known meaning, and provides the foundational digit root interpretation (with full spiritual, love, career, money, and twin flame guidance) as a fallback. An optional context parameter adds a note tailored to where the number was seen. Perfect for synchronicity tracking apps where users enter arbitrary number sequences they encounter.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,8}$","example":"1234","description":"Number sequence to analyze (1-8 digits). Can be any number the user has encountered: clock times (1111), addresses (717), receipts (888), license plates (4444), or any repeating pattern."},"required":true,"description":"Number sequence to analyze (1-8 digits). Can be any number the user has encountered: clock times (1111), addresses (717), receipts (888), license plates (4444), or any repeating pattern.","name":"number","in":"query"},{"schema":{"type":"string","enum":["clock","receipt","license-plate","phone","address","price"],"example":"clock","description":"Where the number was seen. When supplied, the response adds a contextNote tailoring the reading to the sighting: clock (a glanced time), receipt (a purchase), license-plate (in transit), phone (a call or notification), address (a home or place), price (a total or amount)."},"required":false,"description":"Where the number was seen. When supplied, the response adds a contextNote tailoring the reading to the sighting: clock (a glanced time), receipt (a purchase), license-plate (in transit), phone (a call or notification), address (a home or place), price (a total or amount).","name":"context","in":"query"}],"responses":{"200":{"description":"Complete analysis of the number sequence with pattern classification and meaning","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","example":"1234","description":"The number sequence that was analyzed."},"type":{"type":"string","example":"sequential","description":"Pattern classification detected for this number. \"repeating\" means all same digits. \"sequential\" means consecutive ascending or descending. \"mirror\" means palindrome or alternating pattern. \"master\" means numerology master number. \"root\" means single digit. \"compound\" means a multi-digit sequence with no pure pattern (e.g. 911, 1122)."},"digitRoot":{"type":"number","example":1,"description":"Numerology digit root from summing and reducing all digits. Links to foundational single-digit meaning. Master numbers 11, 22, 33 are preserved."},"digits":{"type":"number","example":4,"description":"Total number of digits in the sequence."},"uniqueDigits":{"type":"number","example":4,"description":"Count of unique digits. A repeating number like 111 has 1 unique digit; 1234 has 4."},"isPalindrome":{"type":"boolean","example":false,"description":"Whether the number reads the same forwards and backwards (e.g., 1221, 1001)."},"isRepeating":{"type":"boolean","example":false,"description":"Whether all digits are identical (e.g., 111, 4444, 777)."},"knownMeaning":{"type":["object","null"],"properties":{"title":{"type":"string","example":"Sequential Progress and Life Simplification","description":"Title of the matched angel number meaning."},"coreMessage":{"type":"string","example":"One step at a time. Simplify your life. Progress is happening in perfect order.","description":"Core message summary."},"energy":{"type":"string","example":"positive","description":"Energy classification (positive, neutral, cautionary)."},"keywords":{"type":"array","items":{"type":"string"},"example":["progress","simplification","step by step","natural order","patience"],"description":"Keywords for this angel number."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","example":"Angel number 1234 is a sequential number that carries a message of simplification and steady progress. Just as the numbers naturally progress from 1 to 4, your life is unfolding in a logical, step-by-step manner.","description":"Spiritual interpretation covering divine guidance, higher purpose, and metaphysical significance."},"love":{"type":"string","example":"In love, 1234 encourages you to let relationships develop naturally and organically. Do not rush commitment or force milestones. Each stage of the relationship has its purpose.","description":"Love and relationship interpretation for singles, couples, and those healing from past relationships."},"career":{"type":"string","example":"Professionally, 1234 encourages a methodical, step-by-step approach to career advancement. Break large goals into smaller, manageable steps and complete them one at a time.","description":"Career and vocation guidance. Money and finances are returned separately in the money field."},"money":{"type":"string","example":"In money matters, 1234 is the most orderly of sequences: build your finances one step at a time. It favors simplifying, putting things in order, and progressing methodically, a budget, then debts, then savings, then growth, rather than reaching for everything at once.","description":"Money, finances, and material abundance guidance, distinct from career."},"twinFlame":{"type":"string","example":"For twin flames, 1234 indicates that your journey is progressing in natural, divine order. Each phase of separation, growth, and reunion has its purpose. Do not try to skip ahead or force the timeline.","description":"Twin flame connection interpretation covering union, separation, and spiritual growth."}},"required":["spiritual","love","career","money","twinFlame"],"description":"Detailed interpretations across life areas."},"biblical":{"type":"string","example":"The ascending run 1234 has no standing as a number in biblical numerology, though its individual digits carry meaning, one as unity and beginnings, two as witness, three as divine completeness, four as creation and earthly order.","description":"Biblical and religious perspective, framed honestly."},"shadow":{"type":"string","example":"The shadow side of 1234 is the urge to skip steps. The momentum of forward progress can tempt you to rush ahead, leave foundations half-built, or chase the finish before the groundwork is sound.","description":"Shadow or cautionary reading for this number."},"affirmation":{"type":"string","example":"I simplify my path and trust the natural progression of my journey.","description":"Positive affirmation for this number."},"actionSteps":{"type":"array","items":{"type":"string"},"example":["Break large goals into small, sequential steps","Simplify areas of your life that have become overly complicated","Trust the natural order and timing of your progress"],"description":"Actionable steps when you see this number."}},"required":["title","coreMessage","energy","keywords","meaning","biblical","shadow","affirmation","actionSteps"],"description":"Full angel number meaning if this number exists in the curated database (75+ known sequences). Null if the number is not in the database, in which case use the analysis fields (type, digitRoot) and the digitRootMeaning fallback for interpretation."},"digitRootMeaning":{"type":["object","null"],"properties":{"number":{"type":"string","example":"1","description":"Root digit number (0-9) or master number (11, 22, 33)."},"title":{"type":"string","example":"New Beginnings, Leadership, and Independence","description":"Title of the root digit meaning in numerology."},"coreMessage":{"type":"string","example":"You are a powerful creator. Step into leadership and trust your ability to initiate.","description":"Core message of the foundational root digit."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","example":"The number 1 carries the energy of creation, independence, and new beginnings. It represents the primal force that initiates all action.","description":"Spiritual interpretation of the root digit, covering divine guidance, higher purpose, and metaphysical significance."},"love":{"type":"string","example":"In love, 1 emphasizes independence and new beginnings. For singles, it signals readiness for a new romantic chapter.","description":"Love and relationship interpretation of the root digit, for singles, couples, and those healing from past relationships."},"career":{"type":"string","example":"Professionally, 1 is the number of pioneers and leaders. It encourages you to take initiative, start new projects, and trust your innovative ideas.","description":"Career and vocation guidance for the root digit. Money and finances are returned separately in the money field."},"money":{"type":"string","example":"In money matters, 1 favors initiative and independence: starting an income stream, backing your own idea, or taking the lead on a financial decision rather than waiting on others.","description":"Money, finances, and material abundance guidance for the root digit, kept distinct from career."},"twinFlame":{"type":"string","example":"For twin flames, 1 represents the individual journey each soul must take. Before union can occur, both flames must become whole and independent within themselves.","description":"Twin flame interpretation of the root digit, covering union, separation, and spiritual growth."}},"required":["spiritual","love","career","money","twinFlame"],"description":"Full life-area interpretation of the underlying root digit. For an unknown sequence this is the substantive reading to display, so a synchronicity app never dead-ends on an arbitrary number."},"keywords":{"type":"array","items":{"type":"string"},"example":["new beginnings","leadership","independence","creation","initiative"],"description":"Keywords for the root digit."},"affirmation":{"type":"string","example":"I am a powerful creator, and I trust my ability to begin anew.","description":"Affirmation for the root digit."}},"required":["number","title","coreMessage","meaning","keywords","affirmation"],"description":"The foundational meaning of this number based on its digit root. Every number reduces to a root digit (0-9) or master number (11, 22, 33), which provides the base interpretation even for unknown sequences."},"contextNote":{"type":"string","example":"Catching 1234 on a clock is the most common way this sequence reaches you. Treat the moment you glanced up as a timestamp on whatever you were just thinking or feeling, and read the meaning below against that exact thought.","description":"Present only when the context query parameter is supplied. A short reading layered on top of the meaning that accounts for WHERE the number was seen (clock, receipt, license plate, phone, address, price), since the place of a sighting shifts its emphasis."}},"required":["number","type","digitRoot","digits","uniqueDigits","isPalindrome","isRepeating","knownMeaning","digitRootMeaning"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/angel-numbers/daily":{"post":{"operationId":"getDailyAngelNumber","tags":["Angel Numbers"],"summary":"Daily Angel Number","description":"Get the angel number of the day with full meaning and interpretation. Returns a deterministic angel number based on the current date (or a provided seed date), ensuring all users see the same number for any given day. Includes complete spiritual, love, career, money, and twin flame interpretations plus a biblical perspective and a shadow reading. Perfect for daily guidance features, push notifications, content generation, and angel number widget integrations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seed":{"type":"string","example":"user123","description":"Optional seed for reproducible readings. Same seed + same date = same angel number every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings."},"date":{"type":"string","format":"date","example":"2026-03-06","description":"Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones."}}}}}},"responses":{"200":{"description":"Daily angel number with complete interpretation","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-03-05","description":"The date used for angel number selection (UTC)."},"seed":{"type":"string","example":"user123-2026-03-05","description":"Computed seed used for this reading. Same seed always produces the same angel number."},"number":{"type":"string","example":"444","description":"Angel number sequence selected for today. Three or more digit repeating, sequential, or mirror pattern (e.g., 111, 444, 1212)."},"title":{"type":"string","example":"Angelic Protection, Solid Foundations, and the Signal to Keep Going","description":"Short descriptive title capturing the core theme and spiritual significance of the daily angel number."},"coreMessage":{"type":"string","example":"You are protected and supported. Keep building on the foundations you have laid, because steady effort is moving you toward solid ground.","description":"One to two sentence summary of the divine message for today. Ideal for push notifications, daily guidance widgets, and quick reference."},"type":{"type":"string","example":"repeating","description":"Pattern classification of the daily angel number. \"repeating\" means all digits are the same (111, 4444). \"sequential\" means consecutive digits (1234). \"mirror\" means palindrome or alternating pattern (1212, 1221)."},"digitRoot":{"type":"number","example":3,"description":"Numerology digit root calculated by summing all digits and reducing to a single digit. Links the daily angel number to its foundational numerology meaning."},"energy":{"type":"string","example":"positive","description":"Overall energy classification. \"positive\" indicates encouraging, uplifting energy. \"neutral\" indicates transitional energy. \"cautionary\" indicates a gentle warning to rebalance or pay attention."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","example":"Among the angel numbers, 444 is the one most closely associated with the presence of angels themselves. It is a sign of being supported and watched over, particularly during a stretch that has tested your sense of security.","description":"Two to three paragraph spiritual interpretation covering divine guidance, higher purpose, and the metaphysical significance of the angel number selected for this date."},"love":{"type":"string","example":"In love, 444 points to foundations rather than fireworks. It favors trust, honesty, loyalty, and consistency, the quiet structural elements that let a relationship last.","description":"Love and relationship interpretation covering singles, couples, and those healing from past relationships. Includes romantic guidance and partnership advice."},"career":{"type":"string","example":"Professionally, 444 reads as permission to move forward from a base you have already built. Progress here comes from consistency and attention to detail rather than dramatic leaps.","description":"Career and vocation guidance: professional opportunities, calling, and practical work advice. Money and finances are returned separately in the money field."},"money":{"type":"string","example":"In money matters, 444 speaks to stability that is built rather than wished for. It signals that financial security is within reach, but reached through patience, discipline, and sound decisions rather than a sudden windfall.","description":"Money, finances, and material abundance guidance, kept distinct from career and vocation."},"twinFlame":{"type":"string","example":"For twin flames, 444 indicates support around the connection, even through a phase of separation. It suggests that both people are being guided toward the stability a lasting union requires, which makes the real work individual.","description":"Twin flame connection interpretation covering union, separation, and spiritual growth within the twin flame journey."}},"required":["spiritual","love","career","money","twinFlame"],"description":"Detailed interpretations across life areas for the daily angel number."},"biblical":{"type":"string","example":"In the Bible the number 4 is tied to creation and earthly order: the fourth day, when the sun, moon, and stars were set in place, and figures such as the four corners of the earth and the four winds. Angel numbers as personal codes are not a biblical concept, and Scripture does not single out 444.","description":"Biblical and religious perspective on the daily sequence, framed honestly."},"shadow":{"type":"string","example":"The shadow side of 444 is structure turned rigid. The same drive that builds stability can harden into stubbornness, resistance to change, or a refusal to let chance and spontaneity in.","description":"Shadow or cautionary reading for the daily sequence. Complements the energy classification."},"keywords":{"type":"array","items":{"type":"string"},"example":["protection","foundation","stability","discipline","reassurance","angelic support","perseverance"],"description":"Five to eight keywords capturing the spiritual themes and energy of the daily angel number. Useful for search, filtering, and content generation."},"affirmation":{"type":"string","example":"I am supported and protected, and the foundations I am building will hold.","description":"Positive affirmation aligned with the daily angel number. Use for daily affirmation features, meditation guidance, or spiritual journal prompts."},"actionSteps":{"type":"array","items":{"type":"string"},"example":["Trust that you are supported, and keep building rather than restarting","Strengthen one practical foundation this week, whether finances, health, or home","Address an unstable situation directly instead of working around it"],"description":"Three to five specific, actionable steps to take today based on the angel number guidance. Practical spiritual advice for daily life."}},"required":["date","seed","number","title","coreMessage","type","digitRoot","energy","meaning","biblical","shadow","keywords","affirmation","actionSteps"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/location/search":{"get":{"operationId":"searchCities","tags":["Location and Timezone"],"security":[{"apiKey":[]}],"summary":"Search cities worldwide - Geocoding autocomplete with coordinates and timezone","description":"Turn a place name into coordinates, an IANA timezone and a DST-aware UTC offset, across 235,000+ cities and towns in 240+ countries. Coverage reaches rural towns of a few hundred people and every administrative seat, so a birthplace outside a major metro resolves as reliably as a capital. Matching is case-insensitive, accent-insensitive and partial, so ber matches Berlin, Bern and Bergen, native scripts are transliterated, and historic names resolve to the current place, so bombay returns Mumbai and peking returns Beijing. Results are ordered by match quality first and population second, so an exactly named small town is never buried under a larger city that merely shares its opening letters. Built for birth chart location pickers, horoscope apps, event scheduling, and any feature that needs place-to-coordinates resolution.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Place to search for, written the way a person would. Accepts a bare city (berlin), a city plus country (berlin germany), a comma-qualified place (richfield, utah), a fully qualified place (richfield, utah, united states), or a historic name (bombay, peking, constantinople). Commas are optional, and a qualifier the dataset spells differently, such as USA for United States, still resolves. Matched against city name, alternate names, state or province, and country. Add the state or country whenever the name is common, since that is what separates the six Springfields, and Richfield, Utah from Richfield, Minnesota.","example":"berlin"},"required":true,"description":"Place to search for, written the way a person would. Accepts a bare city (berlin), a city plus country (berlin germany), a comma-qualified place (richfield, utah), a fully qualified place (richfield, utah, united states), or a historic name (bombay, peking, constantinople). Commas are optional, and a qualifier the dataset spells differently, such as USA for United States, still resolves. Matched against city name, alternate names, state or province, and country. Add the state or country whenever the name is common, since that is what separates the six Springfields, and Richfield, Utah from Richfield, Minnesota.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Maximum items to return per page. Range: 1-50, default 10."},"required":false,"description":"Maximum items to return per page. Range: 1-50, default 10.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Matching places, best match first, with coordinates, IANA timezone and UTC offset","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":3,"description":"Number of places matching the query across all pages, not the number returned in this response. Greater than 1 means the name is ambiguous, so show province and country and let the user confirm before using the result for a chart."},"limit":{"type":"number","example":10,"description":"Page size used for this response."},"offset":{"type":"number","example":0,"description":"Number of places skipped. Use with limit to page through results."},"cities":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string","description":"City name as commonly used. Matches the local or internationally recognized name for the location.","example":"Berlin"},"province":{"type":"string","description":"State, province, canton, or administrative region. Show it whenever more than one result comes back: it is what separates Richfield, Utah from Richfield, Minnesota, and the six US Springfields from each other. Empty for the small number of places with no administrative division recorded.","example":"Berlin"},"country":{"type":"string","description":"Full country name in English.","example":"Germany"},"iso2":{"type":"string","description":"ISO 3166-1 alpha-2 country code. Use for filtering cities by country or building country-specific location pickers.","example":"DE"},"latitude":{"type":"number","description":"Geographic latitude in decimal degrees (-90 to 90). Pass directly to birth chart, natal chart, horoscope, synastry, transit, kundli, and panchang API endpoints as the latitude parameter.","example":52.52},"longitude":{"type":"number","description":"Geographic longitude in decimal degrees (-180 to 180). Pass directly to astrology, horoscope, and panchang API endpoints alongside latitude.","example":13.405},"timezone":{"type":"string","description":"IANA timezone identifier following the tz database standard (e.g. Europe/Berlin, America/New_York, Asia/Tokyo). Always present. Pass THIS, not the numeric offset, into any chart or panchang request for a past date: the calculation endpoints resolve it to the offset that was actually in force on that date, including historical daylight saving. Also works directly with JavaScript Date, Luxon, day.js, or any date library.","example":"Europe/Berlin"},"utcOffset":{"type":"number","description":"UTC offset in decimal hours for TODAY at this place, already adjusted for daylight saving. Convenient for displaying local time now. For a birth date or any past date use the `timezone` field instead, since the offset in force then may differ. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal.","example":1},"population":{"type":"number","description":"Population estimate for the place. Breaks ties between results of equal match quality, so among several places matching equally well the largest leads. It never outranks a better match, which is why a small town still wins when its name is typed exactly. May be 0 for a hamlet or administrative seat that carries no published figure.","example":3644826}},"required":["city","province","country","iso2","latitude","longitude","timezone","utcOffset","population"],"description":"Geographic location with coordinates, timezone, and UTC offset. Every field is designed for direct use as input parameters in astrology, horoscope, and location-dependent API calculations."},"description":"Matching places for the current page, best match first. Ordered by match quality, then population within equal quality: an exact name beats a qualified name such as richfield, utah, which beats a name merely starting with the query, which beats an incidental match on state or country. Take the first entry when total is 1, otherwise disambiguate on province and country."}},"required":["total","limit","offset","cities"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/location/countries":{"get":{"operationId":"listCountries","tags":["Location and Timezone"],"security":[{"apiKey":[]}],"summary":"List all countries - ISO codes and city coverage","description":"Returns every country with ISO 3166-1 alpha-2 and alpha-3 codes, plus the number of searchable cities per country. Use this endpoint to build country dropdown menus, regional filters, or to check city coverage before querying. Sorted alphabetically by country name. Covers Europe, Americas, Asia, Middle East, Africa, and Oceania.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":250,"default":50,"example":50,"description":"Maximum items to return per page. Range: 1-250, default 50."},"required":false,"description":"Maximum items to return per page. Range: 1-250, default 50.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Alphabetically sorted list of all countries with ISO codes and city counts","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":246,"description":"Total number of countries with at least one place in the dataset."},"limit":{"type":"number","example":50,"description":"Page size used for this response."},"offset":{"type":"number","example":0,"description":"Number of countries skipped. Use with limit for pagination."},"countries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Full country name in English. Use for display in location pickers and dropdown menus.","example":"Germany"},"iso2":{"type":"string","description":"ISO 3166-1 alpha-2 country code. Use as the identifier when fetching cities for a specific country via the /countries/{iso2} endpoint.","example":"DE"},"iso3":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Three-letter standard used in international data exchange.","example":"DEU"},"cityCount":{"type":"number","description":"Number of searchable places in this country, including small towns and administrative seats. Useful for showing coverage in a UI or sizing a dependent city dropdown.","example":11894}},"required":["name","iso2","iso3","cityCount"],"description":"Country with ISO 3166 codes and city coverage count. Use iso2 to query cities within a specific country."},"description":"Countries for the current page, sorted alphabetically by name."}},"required":["total","limit","offset","countries"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/location/countries/{iso2}":{"get":{"operationId":"getCitiesByCountry","tags":["Location and Timezone"],"security":[{"apiKey":[]}],"summary":"Get cities in a country - Geocoding directory sorted by population","description":"Returns all cities for a specific country, identified by ISO 3166-1 alpha-2 code (e.g. DE for Germany, FR for France, GB for United Kingdom, US for United States). Each city includes geographic coordinates, IANA timezone, and DST-aware UTC offset for direct use in astrology birth chart, horoscope, transit, and panchang calculations. Cities sorted by population with the largest metropolitan areas first.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code, case-insensitive. Common codes: DE (Germany), FR (France), GB (United Kingdom), US (United States), ES (Spain), IT (Italy), NL (Netherlands), IN (India), BR (Brazil), JP (Japan).","example":"DE"},"required":true,"description":"ISO 3166-1 alpha-2 country code, case-insensitive. Common codes: DE (Germany), FR (France), GB (United Kingdom), US (United States), ES (Spain), IT (Italy), NL (Netherlands), IN (India), BR (Brazil), JP (Japan).","name":"iso2","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-100, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Cities in the specified country, sorted by population (largest first)","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":11894,"description":"Total number of places available for this country across all pages."},"limit":{"type":"number","example":50,"description":"Page size used for this response."},"offset":{"type":"number","example":0,"description":"Number of cities skipped. Use with limit for pagination."},"cities":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string","description":"City name as commonly used. Matches the local or internationally recognized name for the location.","example":"Berlin"},"province":{"type":"string","description":"State, province, canton, or administrative region. Show it whenever more than one result comes back: it is what separates Richfield, Utah from Richfield, Minnesota, and the six US Springfields from each other. Empty for the small number of places with no administrative division recorded.","example":"Berlin"},"country":{"type":"string","description":"Full country name in English.","example":"Germany"},"iso2":{"type":"string","description":"ISO 3166-1 alpha-2 country code. Use for filtering cities by country or building country-specific location pickers.","example":"DE"},"latitude":{"type":"number","description":"Geographic latitude in decimal degrees (-90 to 90). Pass directly to birth chart, natal chart, horoscope, synastry, transit, kundli, and panchang API endpoints as the latitude parameter.","example":52.52},"longitude":{"type":"number","description":"Geographic longitude in decimal degrees (-180 to 180). Pass directly to astrology, horoscope, and panchang API endpoints alongside latitude.","example":13.405},"timezone":{"type":"string","description":"IANA timezone identifier following the tz database standard (e.g. Europe/Berlin, America/New_York, Asia/Tokyo). Always present. Pass THIS, not the numeric offset, into any chart or panchang request for a past date: the calculation endpoints resolve it to the offset that was actually in force on that date, including historical daylight saving. Also works directly with JavaScript Date, Luxon, day.js, or any date library.","example":"Europe/Berlin"},"utcOffset":{"type":"number","description":"UTC offset in decimal hours for TODAY at this place, already adjusted for daylight saving. Convenient for displaying local time now. For a birth date or any past date use the `timezone` field instead, since the offset in force then may differ. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal.","example":1},"population":{"type":"number","description":"Population estimate for the place. Breaks ties between results of equal match quality, so among several places matching equally well the largest leads. It never outranks a better match, which is why a small town still wins when its name is typed exactly. May be 0 for a hamlet or administrative seat that carries no published figure.","example":3644826}},"required":["city","province","country","iso2","latitude","longitude","timezone","utcOffset","population"],"description":"Geographic location with coordinates, timezone, and UTC offset. Every field is designed for direct use as input parameters in astrology, horoscope, and location-dependent API calculations."},"description":"Cities for the current page, sorted by population (largest first)."}},"required":["total","limit","offset","cities"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/usage":{"get":{"operationId":"getUsageStats","tags":["Usage"],"summary":"Get API usage statistics","description":"Returns current usage and plan limits for your subscription.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Usage statistics retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","description":"Name of the subscription plan the API key belongs to. One flat plan covers every domain and the Remote MCP servers, so this is a quota tier, never a per product entitlement.","example":"Pro"},"usedThisMonth":{"type":"number","description":"Billable requests counted against the current calendar month. Read from the same counter the rate limiter enforces on, so it never reports a rosier number than the limit that will 429 you. Cached responses still count.","example":1523},"requestsPerMonth":{"type":"number","description":"Monthly request allowance for the plan. One request, API or MCP, equals one unit: there is no credit weighting and no per domain fee.","example":10000},"remainingThisMonth":{"type":"number","description":"Requests left before the monthly allowance is exhausted, floored at zero. Equal to requestsPerMonth minus usedThisMonth.","example":8477},"email":{"type":"string","format":"email","description":"Billing email the subscription is registered under.","example":"dev@example.com"},"status":{"type":"string","description":"Subscription lifecycle state. Values: active, cancelled (no longer renewing but usable until endDate), suspended (payment failed, usable until endDate), expired (past endDate), pending (checkout started, payment not captured).","example":"active"},"endDate":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the current billing period ends. A renewal extends this date in place. API access survives a cancelled or suspended status until this moment passes.","example":"2026-09-01T00:00:00.000Z"}},"required":["plan","usedThisMonth","requestsPerMonth","remainingThisMonth","email","status","endDate"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/languages":{"get":{"operationId":"listLanguages","tags":["Languages"],"summary":"List supported response languages","description":"Returns the language codes accepted by the `lang` query parameter on every i18n-aware endpoint. Use this to populate language pickers, validate user input before calling chart or reading endpoints, or auto-detect available locales in agent integrations. Codes follow ISO 639-1. Endpoints without a translation for the requested language fall back to English silently.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Supported languages","content":{"application/json":{"schema":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"example":"en","description":"ISO 639-1 language code. Pass this value as the `lang` query parameter."},"name":{"type":"string","example":"English","description":"Language name in English."},"nativeName":{"type":"string","example":"English","description":"Language name written in the language itself."}},"required":["code","name","nativeName"]},"description":"All language codes accepted by the `lang` query parameter."}},"required":["languages"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}},"webhooks":{}}