{"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. 10 domains (astrology, tarot, numerology, crystals, dreams, I-Ching, angel numbers, Vedic astrology, location, biorhythm), 130+ endpoints, one API key, instant activation. Native MCP support for AI 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 (MCP)\n\nRoxyAPI has native Model Context Protocol support. Your AI agent auto-discovers all 130+ 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 `suggestion`, `hint`, or `availableEndpoints` 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 to $699/month.\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":"Production-ready Western astrology API + remote MCP for AI agents and developers. Hosted MCP server, no local setup, connect Claude Code, Cursor, VS Code, Windsurf in seconds. Natal birth charts, publisher-grade daily/weekly/monthly horoscopes with unique content per sign (house-based transit system, active transits, Moon sign, Moon phase, energy rating), 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. 23+ endpoints optimized for horoscope platforms, astrology dating apps, AI chatbots, wellness products, and zodiac content engines. Schedule future horoscopes with date parameter for editorial workflows. No astronomy expertise needed."},{"name":"Vedic Astrology","description":"Production-grade Vedic (Jyotish) and KP astrology API + remote MCP for AI agents and developers. Hosted MCP server, no local setup, connect Claude Code, Cursor, VS Code, Windsurf in seconds. Calculations verified against NASA JPL Horizons with sub-arcminute accuracy. Birth charts with 15 divisional charts (D1-D60), Ashtakoot Gun Milan compatibility, Vimshottari Dasha predictions, dosha detection with remedies, 300+ planetary yogas, complete Panchang, and KP horary with 249-level sub-lord analysis. 40+ endpoints optimized for matrimonial apps, horoscope platforms, spiritual wellness services, and AI-powered astrology chatbots."},{"name":"Numerology","description":"Production-ready Pythagorean numerology API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Calculate life path, expression, soul urge, personality, and maturity numbers. Pinnacle and Challenge life phase timing with meanings. Hidden Passion, Subconscious Self, and Cornerstone/Capstone name analysis. Birth day 1-31 profiles, lucky associations (colors, gemstones, planets), personal year and month forecasts, relationship compatibility, karmic debt and lessons. 16 endpoints with detailed interpretations optimized for numerology apps, editorial platforms, AI chatbots, wellness platforms, and spiritual services."},{"name":"Tarot","description":"Production-ready tarot card reading API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Complete 78-card Rider-Waite-Smith deck with domain-specific interpretations for love, career, health, and spiritual growth. Celtic Cross, three-card, love, career, yes/no oracle, daily card, and custom spreads. Seeded reproducibility for personalized daily readings. Card images included. 10+ endpoints optimized for tarot apps, AI tarot chatbots, fortune-telling platforms, and spiritual wellness products."},{"name":"Biorhythm","description":"The most complete biorhythm API + remote MCP for AI agents and developers. Hosted MCP server, no local setup, connect Claude Code, Cursor, VS Code in seconds. 10 cycle types: 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 day identification, two-person compatibility scoring, phase tracking for dashboards, and seeded daily readings for push notifications. 6 endpoints, 8 languages, sub-millisecond response times, editorial-grade interpretations. Ship a biorhythm feature in hours, not weeks."},{"name":"I-Ching","description":"I-Ching oracle API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Access 3,000 years of Chinese wisdom 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 daily hexagrams, and explore the Book of Changes programmatically. 9+ endpoints optimized for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products."},{"name":"Crystals and Healing Stones","description":"Production-ready crystal healing API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Look up 80 healing crystals and gemstones with spiritual, emotional, and physical healing 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 ratings, numerological vibrations, planetary associations, and crystal pairing recommendations. Built for wellness apps, crystal shop platforms, chakra balancing tools, astrology integrations, and AI-powered spiritual advisors."},{"name":"Dreams","description":"Dream interpretation API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. 2,000+ dream symbols with psychological meanings covering animals, objects, emotions, people, scenarios, and abstract concepts. Decode falling dreams, flying dreams, 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. Part of RoxyAPI multi-domain spiritual intelligence."},{"name":"Angel Numbers","description":"Production-ready angel numbers API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Look up meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 40+ angel number sequences. Includes love, career, spiritual, and twin flame interpretations per number. Smart lookup analyzes any number sequence with pattern detection, digit root calculation, and classification. Daily angel number endpoint, filter by type (repeating, sequential, mirror, master). Built for synchronicity apps, spiritual journals, daily guidance features, AI chatbots, and wellness platforms."},{"name":"Location and Timezone","description":"City search and geocoding API + hosted MCP for AI agents and astrology apps. Connect Claude Code, Cursor, VS Code in seconds, no local setup. 7,000+ cities across 227 countries. Returns latitude, longitude, IANA timezone, and DST-aware UTC offset. The location layer for birth chart forms, horoscope apps, event planners, and any feature that needs place-to-coordinates resolution."},{"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."}],"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)."},"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."},"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."},"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 10 planetary positions 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."},"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."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.)."},"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."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and interpretation."},"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)."},"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)."},"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."},"summary":{"type":"object","properties":{"dominantElement":{"type":"string","example":"Water","description":"Most represented element in the chart (Fire, Earth, Air, Water)."},"dominantModality":{"type":"string","example":"Cardinal","description":"Most represented modality in the chart (Cardinal, Fixed, Mutable)."},"retrogradePlanets":{"type":"array","items":{"type":"string"},"example":["Mercury","Saturn"],"description":"Planets in retrograde motion at the time of birth."},"elementDistribution":{"type":"object","additionalProperties":{"type":"number"},"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":{"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","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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},"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"},"longitude":{"type":"number"},"sign":{"type":"string"},"degree":{"type":"number"}},"required":["number","longitude","sign","degree"]}}},"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."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.)."},"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: harmonious, challenging, or neutral."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Trine","description":"Aspect display name."},"description":{"type":"object","properties":{"short":{"type":"string","description":"Brief aspect description."},"long":{"type":"string","description":"Detailed aspect description with astrological context."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"Aspect nature classification."}},"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."},"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":{"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"14:30:00","description":"Time in HH:MM:SS format (24-hour)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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 planets to calculate aspects for (defaults to all 10)"},"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"]},"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)."},"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."},"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 10 planets 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."},"natalPlanet":{"type":"string","example":"Mars","description":"Natal planet being aspected."},"type":{"type":"string","example":"CONJUNCTION","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.)."},"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 — 100 is exact."},"nature":{"type":"string","example":"challenging","description":"Aspect nature: harmonious (trine, sextile), challenging (square, opposition), or neutral (conjunction)."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","description":"Narrative interpretation of what this transit aspect means and how it manifests."},"timing":{"type":"string","description":"How long this transit influence lasts based on the transiting planet speed."},"impact":{"type":"string","description":"Strength and nature of the transit impact on your natal chart."},"guidance":{"type":"string","description":"Practical advice for working with or navigating this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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},"natalChart":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"14:30:00"},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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"}}},"BirthChartResponse":{"type":"object","properties":{"aries":{"type":"object","properties":{"rashi":{"type":"string","description":"Zodiac sign name in lowercase."},"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°20 each."},"key":{"type":"number","example":2,"description":"Nakshatra index (1-27) in the zodiac sequence starting from Ashwini."}},"required":["name","pada","key"]},"isRetrograde":{"type":"boolean","example":false,"description":"True if planet is in retrograde motion (appears to move backward). Retrograde planets have altered significations."}},"required":["graha","longitude","nakshatra","isRetrograde"]},"description":"Planets placed in this zodiac sign."}},"required":["rashi","signs"]},"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 arcminutes 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 arcminutes. 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."}},"required":["name","pada","key"],"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."}},"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","meta"],"example":{"aries":{"rashi":"aries","signs":[]},"meta":{"Sun":{"graha":"Sun","rashi":"Leo","longitude":132.45,"nakshatra":{"name":"Magha","pada":2,"key":9},"isRetrograde":false},"Moon":{"graha":"Moon","rashi":"Cancer","longitude":98.32,"nakshatra":{"name":"Punarvasu","pada":4,"key":6},"isRetrograde":false}}}},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"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 arcminutes 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 arcminutes. 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."}},"required":["name","pada","key"],"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."}},"required":["graha","rashi","longitude","nakshatra","isRetrograde"]},"description":"Planet positions in the Navamsa (D9) chart keyed by planet name. Contains all 9 Navagraha plus Lagna."}},"required":["meta"],"additionalProperties":{"nullable":true},"description":"Navamsa (D9) divisional chart showing planetary positions across 12 rashi houses plus a meta lookup. Same structure as the birth chart response."},"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","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"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."},"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 arcminutes 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 arcminutes. 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."}},"required":["name","pada","key"],"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."}},"required":["graha","rashi","longitude","nakshatra","isRetrograde"]},"description":"Planet positions in the divisional chart keyed by planet name. Contains all 9 Navagraha plus Lagna."}},"required":["meta"],"additionalProperties":{"nullable":true},"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","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5},"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":{"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","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."}},"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."},"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 arcminutes each."},"pada":{"type":"number","example":2,"description":"Nakshatra pada (quarter, 1-4). Each nakshatra divides into 4 padas of 3 degrees 20 arcminutes. 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. Combustion orbs vary by planet: 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. Sun, Rahu, Ketu, and Lagna are never combust. Based on Surya Siddhanta combustion orbs."},"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."}},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"ManglikResponse":{"type":"object","properties":{"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"KalsarpaResponse":{"type":"object","properties":{"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"SadhesatiResponse":{"type":"object","properties":{"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":"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"KPAyanamsaResponse":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-26","description":"Date for which ayanamsa was calculated"},"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","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","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. \"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 type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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"]}}},"required":["ayanamsa","houseSystem","cusps"]},"KPCuspsRequest":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","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. \"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","description":"KP Newcomb ayanamsa value in degrees. Precession correction applied to convert tropical to sidereal positions."},"ayanamsaType":{"type":"string","description":"Ayanamsa system used (KP Newcomb)."},"houseSystem":{"type":"string","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","description":"Sidereal longitude of Ascendant (Lagna) in degrees."},"sign":{"type":"string","description":"Zodiac sign of the Ascendant."},"nakshatra":{"type":"string","description":"Nakshatra (star) of the Ascendant."},"nakshatraLord":{"type":"string","description":"Lord of the Ascendant nakshatra."},"pada":{"type":"number","description":"Nakshatra pada (1-4) of the Ascendant."},"starLord":{"type":"string","description":"KP star lord of the Ascendant position."},"subLord":{"type":"string","description":"KP sub lord of the Ascendant. crucial for KP predictions. The Ascendant sub lord determines overall life promise."},"subSubLord":{"type":"string","description":"KP sub-sub lord (SSL) of the Ascendant. Third level of the Vimshottari subdivision hierarchy, used for fine-tuning predictions."},"kpNumber":{"type":"number","description":"KP number (1-249) for the Ascendant degree."}},"required":["longitude","sign","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","description":"House number (1-12)."},"longitude":{"type":"number","description":"Placidus cusp longitude in sidereal degrees."},"sign":{"type":"string","description":"Zodiac sign at the cusp."},"signLord":{"type":"string","description":"Lord of the zodiac sign at the cusp (house owner)."},"nakshatra":{"type":"string","description":"Nakshatra at the cusp degree."},"nakshatraLord":{"type":"string","description":"Lord of the nakshatra at the cusp."},"pada":{"type":"number","description":"Nakshatra pada (1-4) at the cusp."},"starLord":{"type":"string","description":"KP star lord of the cusp."},"subLord":{"type":"string","description":"KP sub lord of the cusp. the deciding factor for house-level predictions in KP astrology."},"subSubLord":{"type":"string","description":"KP sub-sub lord (SSL) of the cusp. Third level of Vimshottari subdivision for fine-grained cusp analysis."},"kpNumber":{"type":"number","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","description":"Planet name (Sun through Saturn, 7 visible planets)."},"longitude":{"type":"number","description":"Sidereal longitude in degrees (KP ayanamsa corrected)."},"sign":{"type":"string","description":"Zodiac sign the planet occupies."},"house":{"type":"number","description":"House number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","description":"Nakshatra the planet occupies."},"nakshatraLord":{"type":"string","description":"Nakshatra lord (same as star lord)."},"pada":{"type":"number","description":"Nakshatra pada (1-4)."},"starLord":{"type":"string","description":"KP star lord, determines primary house signification."},"subLord":{"type":"string","description":"KP sub lord, the decisive factor. Planet gives results of the houses signified by its sub lord."},"subSubLord":{"type":"string","description":"KP sub-sub lord (SSL) of the planet. Third level of Vimshottari subdivision for precise timing analysis."},"kpNumber":{"type":"number","description":"KP number (1-249)."},"retrograde":{"type":"boolean","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","description":"Sidereal longitude of Rahu (North Node)."},"sign":{"type":"string","description":"Zodiac sign Rahu occupies."},"house":{"type":"number","description":"Occupied house number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","description":"Nakshatra of Rahu."},"starLord":{"type":"string","description":"KP star lord of Rahu."},"subLord":{"type":"string","description":"KP sub lord of Rahu."},"subSubLord":{"type":"string","description":"KP sub-sub lord (SSL) of Rahu."}},"required":["longitude","sign","house","nakshatra","starLord","subLord","subSubLord"],"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","description":"Sidereal longitude of Ketu (South Node). Always 180 degrees from Rahu."},"sign":{"type":"string","description":"Zodiac sign Ketu occupies."},"house":{"type":"number","description":"Occupied house number (1-12) based on Placidus cusps."},"nakshatra":{"type":"string","description":"Nakshatra of Ketu."},"starLord":{"type":"string","description":"KP star lord of Ketu."},"subLord":{"type":"string","description":"KP sub lord of Ketu."},"subSubLord":{"type":"string","description":"KP sub-sub lord (SSL) of Ketu."}},"required":["longitude","sign","house","nakshatra","starLord","subLord","subSubLord"],"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)."}},"required":["meta","ascendant","cusps","planets","nodes","significators"]},"KPChartRequest":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-04","description":"Birth date in YYYY-MM-DD format"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","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. \"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 type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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},"longitude":{"type":"number","example":77.209},"timezone":{"type":"number","example":5.5}},"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."}},"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":"number"},"example":[11,6],"description":"Level 1 (strongest signification). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes L1 houses from agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"number"},"example":[11],"description":"Level 2. The house this planet physically occupies in the chart. For Rahu and Ketu, also includes houses occupied by agent planets (conjoined, aspecting, sign lord)."},"L3":{"type":"array","items":{"type":"number"},"example":[3,8],"description":"Level 3. Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes L3 houses from agent planets."},"L4":{"type":"array","items":{"type":"number"},"example":[5,6],"description":"Level 4 (weakest signification). Houses this planet rules by zodiac sign ownership. For Sun through Saturn, can be up to 2 houses. For Rahu and Ketu, includes houses owned by agent planets (conjoined, aspecting, sign lord)."}},"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":"number"},"example":[11,6],"description":"Level 1 (strongest signification). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes L1 houses from agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"number"},"example":[11],"description":"Level 2. The house this planet physically occupies in the chart. For Rahu and Ketu, also includes houses occupied by agent planets (conjoined, aspecting, sign lord)."},"L3":{"type":"array","items":{"type":"number"},"example":[3,8],"description":"Level 3. Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes L3 houses from agent planets."},"L4":{"type":"array","items":{"type":"number"},"example":[5,6],"description":"Level 4 (weakest signification). Houses this planet rules by zodiac sign ownership. For Sun through Saturn, can be up to 2 houses. For Rahu and Ketu, includes houses owned by agent planets (conjoined, aspecting, sign lord)."}},"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":"number"},"example":[11,6],"description":"Level 1 (strongest signification). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes L1 houses from agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"number"},"example":[11],"description":"Level 2. The house this planet physically occupies in the chart. For Rahu and Ketu, also includes houses occupied by agent planets (conjoined, aspecting, sign lord)."},"L3":{"type":"array","items":{"type":"number"},"example":[3,8],"description":"Level 3. Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes L3 houses from agent planets."},"L4":{"type":"array","items":{"type":"number"},"example":[5,6],"description":"Level 4 (weakest signification). Houses this planet rules by zodiac sign ownership. For Sun through Saturn, can be up to 2 houses. For Rahu and Ketu, includes houses owned by agent planets (conjoined, aspecting, sign lord)."}},"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":"number"},"example":[11,6],"description":"Level 1 (strongest signification). Houses influenced because this planet sits in the nakshatra (star) of a planet occupying those houses. For Rahu and Ketu, also includes L1 houses from agent planets (conjoined, aspecting, sign lord)."},"L2":{"type":"array","items":{"type":"number"},"example":[11],"description":"Level 2. The house this planet physically occupies in the chart. For Rahu and Ketu, also includes houses occupied by agent planets (conjoined, aspecting, sign lord)."},"L3":{"type":"array","items":{"type":"number"},"example":[3,8],"description":"Level 3. Houses influenced because this planet sits in the nakshatra of the sign lord (owner) of those houses. For Rahu and Ketu, also includes L3 houses from agent planets."},"L4":{"type":"array","items":{"type":"number"},"example":[5,6],"description":"Level 4 (weakest signification). Houses this planet rules by zodiac sign ownership. For Sun through Saturn, can be up to 2 houses. For Rahu and Ketu, includes houses owned by agent planets (conjoined, aspecting, sign lord)."}},"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"}},"required":["startDatetime","endDatetime","intervalMinutes","location","totalIntervals","intervals"]},"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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-01-01","description":"Start date for sublord change search (YYYY-MM-DD format)"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":0,"description":"Decimal hours from UTC OR IANA name (e.g. \"Asia/Kolkata\"). 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"],"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. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-01-01","description":"Start date for sign ingress search (YYYY-MM-DD format)"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":0,"description":"Decimal hours from UTC OR IANA name (e.g. \"Asia/Kolkata\"). 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"],"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. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?Z?$","example":"2025-01-15T00:00:00Z","description":"Start datetime in ISO 8601 format. Always interpreted as local time when a non-zero timezone is provided (Z suffix is ignored). With timezone 0, Z suffix is treated as UTC."},"endDatetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?Z?$","example":"2025-01-15T23:59:00Z","description":"End datetime in ISO 8601 format. Maximum 7 days from start. Always interpreted as local time when a non-zero timezone is provided (Z suffix is ignored)."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":0,"description":"Decimal hours from UTC OR IANA name (e.g. \"Asia/Kolkata\"). 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"],"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. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. Defaults to \"mean\"."}},"required":["startDatetime","endDatetime","intervalMinutes","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":{"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"AshtakavargaResponse":{"type":"object","properties":{"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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]},"ShadbalaResponse":{"type":"object","properties":{"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 and retrogression. Retrograde planets score higher. Sun uses Ayana Chesta Bala (declination arc), Moon uses elongation from Sun. Other planets use Sheeghrochcha (mean anomaly) from Surya Siddhanta elements. 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 aspects received by other planets. Benefic aspects (Jupiter, Venus) add strength, malefic aspects (Sun, Mars, Saturn) reduce it. Can be negative when malefic aspects dominate. Uses Sputa Drishti with Vishesha (special) aspects for Mars, Jupiter, and Saturn.","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":["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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","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"},"description":"Key themes when the card is drawn upright. Used for quick tarot reference and reading summaries."},"reversed":{"type":"array","items":{"type":"string"},"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":["beginnings","innocence","spontaneity"],"reversed":["recklessness","fearlessness"]}},"upright":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"},"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","description":"Full narrative interpretation of the card in this orientation. Covers symbolism, life lessons, and guidance for the querent."},"love":{"type":"string","description":"Love and relationship interpretation for this orientation. Covers romantic partnerships, dating, emotional connections, and matters of the heart."},"career":{"type":"string","description":"Career and professional interpretation for this orientation. Covers workplace dynamics, job transitions, ambition, and vocational purpose."},"finances":{"type":"string","description":"Financial interpretation for this orientation. Covers money management, investments, material prosperity, and abundance mindset."},"health":{"type":"string","description":"Health and wellbeing interpretation for this orientation. Covers physical vitality, mental health, energy levels, and self-care guidance."},"spirituality":{"type":"string","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"},"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","description":"Full narrative interpretation of the card in this orientation. Covers symbolism, life lessons, and guidance for the querent."},"love":{"type":"string","description":"Love and relationship interpretation for this orientation. Covers romantic partnerships, dating, emotional connections, and matters of the heart."},"career":{"type":"string","description":"Career and professional interpretation for this orientation. Covers workplace dynamics, job transitions, ambition, and vocational purpose."},"finances":{"type":"string","description":"Financial interpretation for this orientation. Covers money management, investments, material prosperity, and abundance mindset."},"health":{"type":"string","description":"Health and wellbeing interpretation for this orientation. Covers physical vitality, mental health, energy levels, and self-care guidance."},"spirituality":{"type":"string","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","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups, queen-of-swords)."},"name":{"type":"string","description":"Display name of the tarot card as it appears in the Rider-Waite-Smith tradition."},"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","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","description":"Position index of this card in the draw sequence (1-based). Useful for mapping cards to spread positions."},"reversed":{"type":"boolean","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation, providing detailed divination guidance."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","position","reversed","keywords","meaning","imageUrl"]},"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":"The Creative works sublime success, furthering through perseverance.","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance and outcome."},"image":{"type":"string","example":"The movement of heaven is full of power. Thus the superior man makes himself strong and untiring.","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"]},"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":"Hidden dragon. Do not act.","description":"Changing line interpretation text. Applies only when this specific line is a changing line (old yin or old yang) in a casting."}},"required":["position","text"]},"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":"Trigram number (1-8) in the traditional I-Ching ordering."},"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":{"/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."},"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","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 7231).","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."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"Cardinal","description":"Quality/modality: Cardinal (initiating), Fixed (sustaining), or Mutable (adapting)."},"rulingPlanet":{"type":"string","example":"Mars","description":"Traditional ruling planet that governs this sign."},"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","description":"Brief 1-2 sentence personality overview."},"long":{"type":"string","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"},"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","description":"Greatest gifts and natural talents of this sign."},"challenges":{"type":"string","description":"Greatest challenges and growth areas for this sign."},"weapon":{"type":"string","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 7231).","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 10 astrological planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) 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 planet profiles with detailed interpretations, keywords, temperature, and dignities (rulership/detriment/exultation/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 10 planet 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 & 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 nodes and Chiron."},"description":{"type":"string","description":"Brief overview of the planet and its astrological significance."}},"required":["id","name","symbol","tagline","description"]},"description":"All 10 astrological planets 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 7231).","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/exultation/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 & 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","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 nodes and Chiron."},"detriment":{"type":"string","example":"Aquarius","description":"Sign of detriment. Opposite the rulership sign, where the planet struggles. Absent for nodes and Chiron."},"exultation":{"type":"string","example":"Aries","description":"Sign of exaltation. Where the planet is honored and amplified. Absent for nodes and Chiron."},"fall":{"type":"string","example":"Libra","description":"Sign of fall. Opposite the exaltation sign, where the planet is weakened. Absent for nodes and Chiron."},"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","description":"Brief 1-2 sentence overview of the planet."},"long":{"type":"string","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 7231).","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 10 planetary positions (Sun through Pluto), 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 7231).","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 10 planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) 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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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)."},"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","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","description":"Interpretation of this planet in its current zodiac sign."},"planetMeaning":{"type":"string","description":"General meaning of this planet in astrology."},"signExpression":{"type":"string","description":"How this planet expresses through the current sign."},"keywords":{"type":"array","items":{"type":"string"},"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 10 planetary positions 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 7231).","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","default":"12:00:00","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":{"anyOf":[{"type":"number","nullable":true,"minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"},{"nullable":true}],"default":0,"example":0,"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC)."},"required":false,"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\"). 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 7231).","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 7231).","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."},"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","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 7231).","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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},"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."},"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."},"moonSign":{"type":"string","example":"Pisces","description":"Moon sign of this person. Emotional nature and inner needs."}},"required":["ascendant","sunSign","moonSign"],"description":"Person 1 chart highlights: Ascendant, Sun sign, and Moon sign."},"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."},"degree":{"type":"number","example":22.18,"description":"Degree within the Ascendant sign (0-29.999)."}},"required":["sign","degree"],"description":"Ascendant position for person 2."},"sunSign":{"type":"string","example":"Pisces","description":"Sun sign of this person."},"moonSign":{"type":"string","example":"Scorpio","description":"Moon sign of this person."}},"required":["ascendant","sunSign","moonSign"],"description":"Person 2 chart highlights: Ascendant, Sun sign, and Moon sign."},"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."},"planet2":{"type":"string","example":"Mars","description":"Planet from person 2 chart."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.)."},"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","description":"Brief aspect description."},"long":{"type":"string","description":"Detailed aspect description."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"Aspect nature classification."},"relationshipContext":{"type":"string","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":{"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","description":"Overall relationship analysis narrative based on aspect patterns."},"strengths":{"type":"array","items":{"type":"string"},"description":"Areas where the relationship naturally thrives based on harmonious aspects."},"challenges":{"type":"array","items":{"type":"string"},"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 7231).","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","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","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","example":40.7128,"description":"Birth location latitude in decimal degrees. 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","example":-74.006,"description":"Birth location longitude in decimal degrees. Affects local time and horizon calculations for house cusps."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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 7231).","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 7231).","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 planets now). Optionally compare transits to natal chart to find transit-to-natal aspects. Returns all 10 planet positions 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 7231).","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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}},"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","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","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"]},"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"]},"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."}},"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."},"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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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":"Current transiting planetary positions in the tropical zodiac. All 10 planets from Sun through Pluto."},"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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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":"Natal (birth chart) planetary positions used as the baseline for transit aspect comparison."},"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"],"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"],"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."},"transitInterpretation":{"type":"object","properties":{"summary":{"type":"string","description":"Narrative interpretation of this transit aspect and its life impact."},"timing":{"type":"string","description":"When this transit is most active and how long its influence lasts."},"impact":{"type":"string","description":"Strength and nature of this transit effect — constructive, challenging, or neutral."},"guidance":{"type":"string","description":"Practical advice for working with this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"]}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"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","nullable":true,"properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron"],"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"],"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."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"],"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"},"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","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 7231).","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","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","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","example":40.7128,"description":"Latitude of the solar return location in decimal degrees. Use current residence or travel location at time of birthday — solar return charts are location-sensitive."},"longitude":{"type":"number","example":-74.006,"description":"Longitude of the solar return location in decimal degrees. Affects house cusps and Ascendant of the return chart."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","description":"Observer latitude used for Placidus house cusp and Ascendant calculation in the solar return chart."},"longitude":{"type":"number","description":"Observer longitude used for local sidereal time and Midheaven calculation in the solar return chart."},"timezone":{"type":"number","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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 10 planetary positions (Sun through Pluto) in the tropical zodiac with house placements."},"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"],"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"],"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."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."}},"required":["birthDetails","planets","houses","houseSystem","aspects"],"description":"Full natal-style chart erected for the solar return moment. Contains all 10 planetary positions, 12 house cusps, aspects, Ascendant, and Midheaven in the tropical zodiac."},"natalSunPosition":{"type":"object","properties":{"longitude":{"type":"number","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","description":"Narrative overview of the solar return year themes and energy."},"purpose":{"type":"string","description":"Explanation of how to use solar return charts for annual forecasting, identifying yearly themes, and timing predictions."},"keyThemes":{"type":"array","items":{"type":"string"},"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 7231).","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","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","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","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","example":40.7128,"description":"Latitude of the lunar return location in decimal degrees. Affects the Ascendant and house cusps of the return chart."},"longitude":{"type":"number","example":-74.006,"description":"Longitude of the lunar return location in decimal degrees. Determines local sidereal time for house calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","description":"Observer latitude used for house cusp calculation in the lunar return chart."},"longitude":{"type":"number","description":"Observer longitude used for local sidereal time and Midheaven in the return chart."},"timezone":{"type":"number","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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 10 planetary positions (Sun through Pluto) in the tropical zodiac with house placements."},"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"],"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"],"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."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."}},"required":["birthDetails","planets","houses","houseSystem","aspects"],"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","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","description":"Narrative overview of the monthly emotional themes and lunar cycle focus areas."},"purpose":{"type":"string","description":"Explanation of how to use lunar return charts for monthly emotional forecasting and self-care planning."},"keyThemes":{"type":"array","items":{"type":"string"},"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 7231).","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. 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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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}},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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}},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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","description":"Narrative interpretation of this composite planet placement."},"relationshipMeaning":{"type":"string","description":"What this planet represents in the context of the relationship."},"keywords":{"type":"array","items":{"type":"string"},"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 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"],"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"],"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."}},"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","description":"Overall relationship interpretation based on composite chart analysis."},"strengths":{"type":"array","items":{"type":"string"},"description":"Areas where the relationship naturally thrives."},"challenges":{"type":"array","items":{"type":"string"},"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 7231).","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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}},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\", \"Asia/Kolkata\"). 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}},"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":"gemini","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","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":"gemini","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","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":"gemini","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","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":"pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","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","nullable":true,"example":"water","description":"Dominant element shared by both charts, or null if dominant elements differ."},"description":{"type":"string","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","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"},"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"},"description":"Potential friction points based on challenging inter-chart aspects. Each includes specific guidance for navigating the tension."},"summary":{"type":"string","description":"Narrative overview of the relationship compatibility, highlighting the dominant themes."},"interpretation":{"type":"string","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","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 7231).","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. Supports date parameter for editorial scheduling. 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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-03","description":"Forecast date in YYYY-MM-DD format. Defaults to today. Supports future and past dates for editorial scheduling."},"required":false,"description":"Forecast date in YYYY-MM-DD format. Defaults to today. Supports future and past dates for editorial scheduling.","name":"date","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","description":"General daily overview based on Moon house activation and planetary transits. Unique per sign based on whole-sign house positions."},"love":{"type":"string","description":"Love and relationship forecast. Based on Venus house position relative to this sign, providing unique guidance per sign."},"career":{"type":"string","description":"Career and professional outlook. Based on Mars house position relative to this sign, with Saturn and Jupiter influences."},"health":{"type":"string","description":"Health, energy, and wellness guidance for the day."},"finance":{"type":"string","description":"Financial outlook and money-related guidance."},"advice":{"type":"string","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 7231).","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 7-day 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. 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"}],"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","description":"Weekly overview highlighting the dominant planetary transits through the sign."},"love":{"type":"string","description":"Weekly love and relationship forecast."},"career":{"type":"string","description":"Weekly career and professional outlook."},"health":{"type":"string","description":"Weekly health, energy, and wellness guidance."},"finance":{"type":"string","description":"Weekly financial outlook."},"advice":{"type":"string","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 7231).","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. 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"}],"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","description":"Monthly overview covering the major planetary transits and their impact on the sign."},"love":{"type":"string","description":"Monthly love and relationship forecast."},"career":{"type":"string","description":"Monthly career and professional outlook."},"health":{"type":"string","description":"Monthly health and wellness guidance."},"finance":{"type":"string","description":"Monthly financial outlook and guidance."},"weekByWeek":{"type":"array","items":{"type":"object","properties":{"week":{"type":"number","example":1,"description":"Week number within the month (1-4)."},"focus":{"type":"string","description":"Primary focus area for this week, derived from planetary house activations for this sign."},"advice":{"type":"string","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","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","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 7231).","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","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","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","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","example":40.7128,"description":"Latitude of the return location in decimal degrees. Affects house cusps and Ascendant of the return chart."},"longitude":{"type":"number","example":-74.006,"description":"Longitude of the return location in decimal degrees."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","description":"Observer latitude used for house cusp calculation in the return chart."},"longitude":{"type":"number","description":"Observer longitude used for Midheaven and local sidereal time."},"timezone":{"type":"number","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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"],"example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto)."},"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 Moon and Pluto."},"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 10 planetary positions (Sun through Pluto) in the tropical zodiac with house placements."},"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"],"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"],"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."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."}},"required":["birthDetails","planets","houses","houseSystem","aspects"],"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","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","description":"Narrative overview of this planetary return cycle and its significance for personal development."},"keyThemes":{"type":"array","items":{"type":"string"},"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 7231).","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"}],"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 orbs), 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 7231).","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":[]}],"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 7231).","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":[]}],"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 7231).","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 7231).","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 7231).","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. 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":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly ephemeris (1900-2100)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for ephemeris."},"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","month"]}}}},"responses":{"200":{"description":"Monthly ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the ephemeris."},"month":{"type":"number","example":2,"description":"Month of the ephemeris."},"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)."},"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."},"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 7231).","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 - Dasha Calculator API","description":"Calculate current Vimshottari Dasha periods (Mahadasha, Antardasha, Pratyantardasha) with remaining time. Accurate dasha calculator API for life phase prediction and planetary period analysis. Returns dasha timeline with start/end dates for each period. Essential for understanding current planetary influences, dasha transitions, and timing events in Vedic astrology. 120-year dasha system based on moon nakshatra at birth.","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-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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"required":["date","time","latitude","longitude"]}}}},"responses":{"200":{"description":"Currently active Mahadasha, Antardasha, and Pratyantardasha with start/end dates, remaining balance, Moon nakshatra, and Vedic interpretations for each period.","content":{"application/json":{"schema":{"type":"object","properties":{"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."},"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)."},"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."}},"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)."},"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."},"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)."},"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."},"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."},"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)."}},"required":["moonNakshatra","nakshatraName","nakshatraLord","mahadasha","antardasha","pratyantardasha","remainingInMahadasha","remainingInAntardasha","remainingInPratyantardasha"]}}}},"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 7231).","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"}],"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"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":{"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."},"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)."},"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."}},"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","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 7231).","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"}],"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","example":"10:12:00","description":"Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every ~2 hours. 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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"Asia/Kolkata\", \"America/New_York\"). 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 (IST).","example":5.5}},"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":{"mahadashaLord":{"type":"string","enum":["Ketu","Venus","Sun","Moon","Mars","Rahu","Jupiter","Saturn","Mercury"],"example":"Jupiter","description":"Ruling planet of the requested Mahadasha period."},"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)."},"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."}},"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)."},"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."},"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."},"description":"All 9 Antardasha sub-periods within this Mahadasha, proportional to each planet Vimshottari years. Sorted chronologically."}},"required":["mahadashaLord","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 7231).","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","description":"Date in YYYY-MM-DD format. Panchang elements (Tithi, Nakshatra, Yoga, Karana) are calculated for this date.","example":"2025-12-17"},"time":{"type":"string","description":"Time in HH:MM:SS format (24-hour). Determines the exact Moon and Sun positions for tithi and nakshatra calculation.","example":"12:00:00"},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-02-03","description":"Date in YYYY-MM-DD format."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone offset from UTC in decimal hours. Used for sunrise/sunset/moonrise/moonset search accuracy and output time formatting. Essential for correct results outside IST. 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","description":"Observer latitude used for sunrise/sunset calculation."},"longitude":{"type":"number","description":"Observer longitude used for sunrise/sunset calculation."},"timezone":{"type":"number","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":"Hindu weekday name. Vara begins at local sunrise, not midnight."},"lord":{"type":"string","example":"Mars","description":"Ruling planet of the day (Vara lord). Influences day-level auspiciousness."}},"required":["name","lord"],"description":"Vara (weekday) information based on Hindu sunrise calendar."},"sunrise":{"type":"string","example":"2026-02-03T01:38:00.000Z","description":"Local sunrise time in UTC. Marks the start of the Hindu day."},"sunset":{"type":"string","example":"2026-02-03T12:30:00.000Z","description":"Local sunset time in UTC. Marks the transition to night muhurtas."},"moonrise":{"type":"string","nullable":true,"example":"2026-02-03T10:15:00.000Z","description":"Moonrise time in the requested timezone. Can be null if Moon does not rise on this date."},"moonset":{"type":"string","nullable":true,"example":"2026-02-03T22:45:00.000Z","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","description":"Start time of the current hora in UTC."},"end":{"type":"string","description":"End time of the current hora in UTC."}},"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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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","nullable":true,"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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","nullable":true,"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00.000Z","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.000Z","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","nullable":true,"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00.000Z","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.000Z","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","nullable":true,"properties":{"start":{"type":"string","example":"2026-02-03T09:00:00.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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":false,"description":"Whether Panchaka is currently active. Panchaka occurs when Moon transits through the last 5 nakshatras (Dhanishta to Revati)."},"type":{"type":"string","nullable":true,"example":null,"description":"Panchaka type when active: Mrityu (death-related), Agni (fire-related), Raja (government-related), Chora (theft-related), or Roga (disease-related). Null when Panchaka is not active."},"startsAt":{"type":"string","nullable":true,"example":null,"description":"When the current Panchaka period started (Moon entered Dhanishta nakshatra). Null when not active. In requested timezone."},"endsAt":{"type":"string","nullable":true,"example":null,"description":"When the current Panchaka period ends (Moon exits Revati nakshatra). Null when not active. In requested timezone."}},"required":["active","type","startsAt","endsAt"],"description":"Panchaka, inauspicious period when Moon transits nakshatras 23-27. Five types based on the specific nakshatra. Includes timing when active. Avoid major activities during Panchaka."},"bhadra":{"type":"object","properties":{"active":{"type":"boolean","example":false,"description":"Whether Bhadra (Vishti Karana) is currently active. Bhadra is considered inauspicious for starting new ventures."},"startsAt":{"type":"string","nullable":true,"example":null,"description":"When the current Bhadra (Vishti) period started. Null when not active. In requested timezone."},"endsAt":{"type":"string","nullable":true,"example":null,"description":"When the current Bhadra (Vishti) period ends. Null when not active. In requested timezone."}},"required":["active","startsAt","endsAt"],"description":"Bhadra, occurs during Vishti Karana period. One of the 7 movable karanas, Vishti (also called Bhadra) is avoided for all auspicious activities. Includes timing when active."},"transitions":{"type":"object","properties":{"tithi":{"type":"object","properties":{"endsAt":{"type":"string","example":"2026-02-03T14:53:00.000Z","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.000Z","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.000Z","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.000Z","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.000Z","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-02-03","description":"Date in YYYY-MM-DD format."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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"},"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.000Z","description":"Period start time in ISO 8601 format. Timezone-adjusted based on input timezone offset."},"end":{"type":"string","example":"2026-02-03T02:30:00.000Z","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.000Z","description":"Period start time in ISO 8601 format. Timezone-adjusted based on input timezone offset."},"end":{"type":"string","example":"2026-02-03T02:30:00.000Z","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-02-03","description":"Date in YYYY-MM-DD format."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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.000Z","description":"Start time of the hora period in ISO 8601 format."},"end":{"type":"string","example":"2026-02-03T02:05:00.000Z","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.000Z","description":"Start time of the hora period in ISO 8601 format."},"end":{"type":"string","example":"2026-02-03T02:05:00.000Z","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 7231).","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":[]}],"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 7231).","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":[]}],"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 7231).","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":[]}],"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 7231).","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 - 300+ Vedic Yoga Combinations","description":"Returns list of all 300+ planetary yogas (astrological combinations) with basic information (id and name only). Use this to discover available yogas, then call GET /yogas/:id for detailed information. Perfect for building yoga browser interfaces, search functionality, and progressive data loading 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"}],"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 /yogas/:id."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Traditional Sanskrit name of the planetary yoga combination."}},"required":["id","name"]},"description":"Array of all planetary yogas with basic identifiers. Use GET /yogas/:id for formation rules, effects, and quality classification."},"total":{"type":"number","example":300,"description":"Total count of planetary yogas in the database. 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 7231).","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 - Detailed Yoga Information API","description":"Returns complete details for a specific yoga including formation conditions, results/effects, and quality (Positive/Negative/Both). Use GET /yogas first to get the list of IDs. Provides in-depth information about each planetary combination. Perfect for yoga detail pages, educational content, and astrological interpretation in horoscope apps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","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":{"type":"object","properties":{"id":{"type":"string","example":"gajakesari","description":"Unique yoga identifier in lowercase kebab-case. Use this to fetch yoga details via GET /yogas/:id."},"name":{"type":"string","example":"Gajakesari Yoga","description":"Traditional Sanskrit name of the planetary yoga combination as referenced in classical Vedic astrology texts."},"description":{"type":"string","example":"Jupiter in kendra from Moon","description":"Brief formation rule describing which planets must be in which houses or signs for this yoga to form in a birth chart."},"result":{"type":"string","example":"Gajakesari Yoga is one of the most powerful yogas. You will be eloquent, wealthy...","description":"Detailed prediction of the effects and life outcomes when this yoga is present in a horoscope. Covers personality traits, career, wealth, relationships, and spiritual tendencies."},"quality":{"type":"string","enum":["Positive","Negative","Both"],"example":"Positive","description":"Overall nature of the yoga. Positive yogas (Raj Yoga, Gajakesari) bestow benefits. Negative yogas (Kemadruma, Kaal Sarp) indicate challenges. Both means the yoga has mixed effects depending on chart context."}},"required":["id","name","description","result","quality"]}}}},"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 7231).","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 real-time KP-Newcomb ayanamsa value calculated using Newcomb precession theory - no preset tables. Returns precise ayanamsa for any date based on IAU modern precession standards. Essential for accurate KP chart calculations and research. Formula: A = 16.90709×(Year/10000) - 0.757371×(Year/1000)² - 6.92416, B = (Month-1 + Date/30)×1.1574074/1000. KP Newcomb ayanamsa API, dynamic ayanamsa calculator, Krishnamurti ayanamsa today, current KP ayanamsa","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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° per month due to Earth's precession."},"required":false,"description":"Date for ayanamsa calculation in YYYY-MM-DD format. Defaults to today if not provided. Ayanamsa changes by ~0.01° per month due to Earth's precession.","name":"date","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 7231).","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 7231).","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":[]}],"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 7231).","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":[]}],"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 7231).","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":[]}],"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":5.5,"description":"Timezone: decimal hours from UTC OR IANA name (e.g. \"Asia/Kolkata\"). IANA resolved to the DST-correct offset based on birthDate or datetime. Defaults to 5.5 (IST).","example":5.5},"datetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?Z?$","example":"2025-01-15T10:30:00Z","description":"ISO 8601 datetime for ruling planets. Defaults to current time. Always interpreted as local time when a non-zero timezone is provided (Z suffix is ignored)."},"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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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 type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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 7231).","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":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startDatetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?Z?$","example":"2026-02-03T00:00:00Z","description":"Start of the interval range in ISO 8601 format. Always interpreted as local time when a non-zero timezone is provided (Z suffix is ignored)."},"endDatetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?Z?$","example":"2026-02-03T01:00:00Z","description":"End of the interval range in ISO 8601 format. Always interpreted as local time when a non-zero timezone is provided (Z suffix is ignored)."},"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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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"],"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. Defaults to \"kp-newcomb\"."},"nodeType":{"type":"string","enum":["mean","true"],"default":"mean","example":"mean","description":"Lunar node type for Rahu and Ketu positions. \"mean\" uses the smooth mean node (traditional Vedic astrology default). \"true\" uses the osculating node with perturbation corrections, oscillating up to 1.5 degrees from mean with a 173-day period. Impacts KP sub-lord assignments in narrow boundary cases. 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 7231).","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 7231).","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 7231).","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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":"UTC datetime used for aspect calculation (ISO 8601)."},"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 7231).","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). 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":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly analysis (1900-2100)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","month"]}}}},"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."},"month":{"type":"number","example":2,"description":"Month of the aspect analysis."},"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."},"planet2":{"type":"string","example":"Venus","description":"Second planet forming the aspect."},"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","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 7231).","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. 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":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for monthly analysis (1900-2100)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","month"]}}}},"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."},"month":{"type":"number","example":2,"description":"Month of the lunar aspect analysis."},"events":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Jupiter","description":"Planet that the Moon forms an aspect with."},"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","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 7231).","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. Returns transiting planets with their natal house positions, aspects to natal planets, and highlights key transits from slow-moving planets (Jupiter, Saturn, Rahu, Ketu). Essential for timing predictions, event forecasting, and understanding current planetary influences. Transit analysis API, gochar calculator, vedic transit predictions.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","default":"12:00:00","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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":{"birthDatetime":{"type":"string","description":"Birth datetime used for the natal chart (UTC ISO 8601)."},"transitDatetime":{"type":"string","description":"Transit datetime being analyzed (UTC ISO 8601)."},"natalPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun through Ketu plus Lagna)."},"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":"House number (1-12) in the natal chart based on Placidus cusps."}},"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 this planet is currently transiting through. Key for Gochar predictions."},"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":"Aspect type: conjunction, opposition, trine, square, or sextile."},"orb":{"type":"number","example":2.45,"description":"Angular distance from exact aspect in degrees. Smaller orb = stronger influence."}},"required":["natalPlanet","aspectType","orb"]},"description":"Aspects formed between this transiting planet and natal planets."}},"required":["name","longitude","sign","natalHouse","aspectsToNatal"]},"description":"Current planetary positions overlaid on the natal chart with house placements and aspects."},"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 natal 10th house","description":"Human-readable transit summary."},"natalHouse":{"type":"number","example":10,"description":"Natal house being transited by this slow planet."},"aspects":{"type":"array","items":{"type":"string"},"example":["square Moon"],"description":"Notable aspects to natal planets from this slow-moving transiting planet."}},"required":["planet","description","natalHouse","aspects"]},"description":"Highlighted transits from slow-moving planets (Jupiter, Saturn, Rahu, Ketu), most impactful for Gochar analysis."}},"required":["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 7231).","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. Essential for transit prediction, monthly horoscope generation, and muhurta planning. Monthly planetary transit API, gochar calendar, rashi parivartan dates.","security":[{"apiKey":[]}],"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)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for transit analysis."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","month"]}}}},"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."},"month":{"type":"number","example":2,"description":"Month of the monthly transit analysis."},"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."},"sign":{"type":"string","example":"Capricorn","description":"Zodiac sign (rashi) the planet occupies at the start of the month."},"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."},"fromSign":{"type":"string","example":"Gemini","description":"Zodiac sign the planet is leaving (previous rashi)."},"toSign":{"type":"string","example":"Cancer","description":"Zodiac sign the planet is entering (new rashi transit)."},"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","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^\\d{2}:\\d{2}:\\d{2}$","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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","description":"UTC datetime used for declination calculation (ISO 8601)."},"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 7231).","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. Essential for advanced transit analysis and hidden aspect discovery. Monthly declination parallels API, planetary parallel ephemeris, contraparallel event calendar.","security":[{"apiKey":[]}],"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)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Month number (1-12) for parallel analysis."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"default":0,"description":"Timezone offset from UTC in hours. Output times are converted to this timezone. Defaults to 0 (UTC).","example":5.5}},"required":["year","month"]}}}},"responses":{"200":{"description":"Monthly parallel events","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the parallel analysis."},"month":{"type":"number","example":2,"description":"Month of the parallel analysis."},"events":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"First planet in the parallel or 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 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 7231).","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","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"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."},"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","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 7231).","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 7231).","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","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 7231).","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 7231).","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","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 7231).","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 7231).","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 7231).","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":[]}],"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 7231).","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 7231).","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,"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 7231).","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,"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 7231).","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,"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 7231).","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,"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 7231).","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 7231).","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,"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 7231).","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,"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":{"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 7231).","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,"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","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-04","description":"Target date in YYYY-MM-DD format (defaults to today)"}},"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 7231).","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 7231).","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 7231).","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,"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,"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 7231).","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,"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","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","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","description":"True if the reduction passed through a karmic debt number (13, 14, 16, 19)."},"karmicDebtNumber":{"type":"number","description":"The karmic debt number encountered during reduction, if any."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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","description":"Expression (Destiny) number derived from full birth name using Pythagorean numerology."},"calculation":{"type":"string","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","description":"Whether karmic debt was encountered during calculation."},"karmicDebtNumber":{"type":"number","description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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","description":"Soul Urge (Heart Desire) number from vowels in birth name."},"calculation":{"type":"string","description":"Vowel extraction and reduction calculation."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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","description":"Personality number from consonants in birth name."},"calculation":{"type":"string","description":"Consonant extraction and reduction calculation."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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","description":"Birth Day number (1-31). A special talent number based on the day of the month you were born."},"calculation":{"type":"string","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","description":"True if the birth day is a karmic debt number (13, 14, 16, 19)."},"karmicDebtNumber":{"type":"number","description":"The karmic debt number if the birth day carries one (13, 14, 16, or 19)."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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","description":"Maturity number (Life Path + Expression). Becomes active around age 35-40."},"calculation":{"type":"string","description":"Shows Life Path + Expression reduction."},"type":{"type":"string","enum":["single","master"],"description":"Single digit or master number."},"hasKarmicDebt":{"type":"boolean","description":"Whether karmic debt was encountered."},"karmicDebtNumber":{"type":"number","description":"Karmic debt number if present."},"meaning":{"type":"object","properties":{"title":{"type":"string","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"},"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","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"},"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"},"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","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","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","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"},"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","description":"The missing number representing this karmic lesson."},"lesson":{"type":"string","description":"Karmic lesson title identifying the core quality or virtue this soul needs to develop in the current lifetime."},"description":{"type":"string","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","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"},"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","description":"True if any core number reduces through a karmic debt number (13, 14, 16, 19)."},"debtNumbers":{"type":"array","items":{"type":"number"},"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","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","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","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","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","description":"Personal Year number (1-9). Each year in the 9-year cycle has distinct themes and energies."},"cycle":{"type":"string","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","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","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"},"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"},"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","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","description":"Personal Month number (1-9)."},"theme":{"type":"string","description":"Central theme for this Personal Month."},"focus":{"type":"string","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","description":"Pinnacle position (1-4). Four major life phases."},"number":{"type":"number","description":"Pinnacle number (1-9, 11, 22, 33). Defines the theme of this life phase."},"startAge":{"type":"number","description":"Age when this Pinnacle phase begins."},"endAge":{"type":"number","nullable":true,"description":"Age when this phase ends. Null for the 4th Pinnacle (lasts rest of life)."},"meaning":{"type":"object","properties":{"title":{"type":"string","description":"Pinnacle phase title."},"description":{"type":"string","description":"What this Pinnacle phase brings to your life."},"opportunities":{"type":"array","items":{"type":"string"},"description":"Key opportunities during this phase."},"challenges":{"type":"array","items":{"type":"string"},"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","description":"Challenge position (1-4). Four life obstacle periods."},"number":{"type":"number","description":"Challenge number (0-8). Defines the obstacle of this period."},"startAge":{"type":"number","description":"Age when this Challenge period begins."},"endAge":{"type":"number","nullable":true,"description":"Age when this period ends. Null for the 4th Challenge."},"meaning":{"type":"object","properties":{"title":{"type":"string","description":"Challenge title."},"description":{"type":"string","description":"What this Challenge demands you overcome."},"lesson":{"type":"string","description":"Core lesson to learn during this period."},"howToOvercome":{"type":"string","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","description":"Hidden Passion number (1-9). The most frequently occurring number in the birth name."},"count":{"type":"number","description":"How many times this number appears in the name."},"allPassions":{"type":"array","items":{"type":"number"},"description":"All numbers tied for highest frequency (usually one, sometimes multiple)."},"title":{"type":"string","description":"Archetype title for this Hidden Passion."},"description":{"type":"string","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","description":"Subconscious Self number (1-9). Count of unique numbers present in the name."},"uniqueNumbers":{"type":"array","items":{"type":"number"},"description":"Which numbers (1-9) are present in the birth name."},"title":{"type":"string","description":"Archetype title for this Subconscious Self level."},"description":{"type":"string","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","description":"First letter of the first name."},"number":{"type":"number","description":"Pythagorean number value of the Cornerstone letter."},"meaning":{"type":"string","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","description":"Last letter of the first name."},"number":{"type":"number","description":"Pythagorean number value of the Capstone letter."},"meaning":{"type":"string","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","description":"First vowel in the full name (A, E, I, O, or U)."},"meaning":{"type":"string","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","description":"Calendar day of birth (1-31)."},"reducesTo":{"type":"number","description":"Single digit or master number this day reduces to."},"title":{"type":"string","description":"Unique archetype title for this specific birth day."},"keywords":{"type":"array","items":{"type":"string"},"description":"Personality traits specific to this birth day."},"description":{"type":"string","description":"Detailed personality profile unique to this calendar day, not just the reduced digit."},"strengths":{"type":"array","items":{"type":"string"},"description":"Strengths specific to this birth day."},"challenges":{"type":"array","items":{"type":"string"},"description":"Challenges specific to this birth day."},"career":{"type":"string","description":"Career guidance for this specific birth day."},"relationships":{"type":"string","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","description":"Whether the Maturity number is currently active (typically activates around age 35-40)."},"currentAge":{"type":"number","description":"Current age calculated from the birth year."},"activationRange":{"type":"string","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"},"description":"Lucky colors associated with the Life Path number."},"gemstones":{"type":"array","items":{"type":"string"},"description":"Lucky gemstones aligned to the ruling planet."},"day":{"type":"string","description":"Lucky day of the week."},"element":{"type":"string","description":"Classical element (Fire, Water, Earth, Air)."},"rulingPlanet":{"type":"string","description":"Ruling planet for this Life Path number."},"compatibleNumbers":{"type":"array","items":{"type":"number"},"description":"Most compatible Life Path numbers."},"incompatibleNumbers":{"type":"array","items":{"type":"number"},"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 7231).","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":"Invalid number (must be 1-9, 11, 22, or 33)","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"]}}}},"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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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"},"description":"Qualities that are amplified and accessible today. Lean into these for maximum alignment with the daily energy."},"challenges":{"type":"array","items":{"type":"string"},"description":"Shadow patterns to watch for today. Awareness of these helps navigate the day with intention and balance."},"career":{"type":"string","description":"Professional guidance tuned to the daily energy. Suggests optimal work strategies, meeting approaches, and productivity focus areas."},"relationships":{"type":"string","description":"Relationship dynamics influenced by the daily number. Covers communication style, social energy, and partnership awareness for the day."},"spirituality":{"type":"string","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 7231).","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","nullable":true,"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","nullable":true,"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","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","description":"Maximum items returned per page."},"offset":{"type":"number","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 7231).","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 7231).","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","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","description":"Date of the daily tarot reading in YYYY-MM-DD format (UTC). Determines which card is drawn for seeded readings."},"seed":{"type":"string","description":"Seed used for this daily reading. Same seed on the same date always produces the identical card for reproducible daily divination."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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)."},"position":{"type":"number","description":"Position index of the card in the draw sequence (1-based)."},"reversed":{"type":"boolean","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation, providing daily guidance and reflection."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","position","reversed","keywords","meaning","imageUrl"]},"dailyMessage":{"type":"string","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 7231).","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":"optional-seed","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","description":"The querent question that was asked, if one was provided."},"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","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","imageUrl"]},"interpretation":{"type":"string","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 7231).","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":"optional-seed","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","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","description":"The querent question, if one was provided."},"seed":{"type":"string","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","description":"Position number in the spread layout (1-based)."},"name":{"type":"string","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","meaning","imageUrl"]}},"required":["position","name","interpretation","card"]},"description":"Array of spread positions, each containing a drawn card with position-specific tarot interpretation."},"summary":{"type":"string","description":"AI-generated narrative connecting all cards in the spread into a 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 7231).","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?"},"seed":{"type":"string","example":"optional-seed"}}}}}},"responses":{"200":{"description":"Celtic Cross spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","description":"The querent question, if one was provided."},"seed":{"type":"string","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","description":"Position number in the spread layout (1-based)."},"name":{"type":"string","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","meaning","imageUrl"]}},"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","description":"AI-generated narrative connecting all cards in the spread into a 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 7231).","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?"},"seed":{"type":"string","example":"optional-seed"}}}}}},"responses":{"200":{"description":"Love spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","description":"The querent question, if one was provided."},"seed":{"type":"string","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","description":"Position number in the spread layout (1-based)."},"name":{"type":"string","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","meaning","imageUrl"]}},"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","description":"AI-generated narrative connecting all cards in the spread into a 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 7231).","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?"},"seed":{"type":"string","example":"optional-seed"}}}}}},"responses":{"200":{"description":"Career spread reading","content":{"application/json":{"schema":{"type":"object","properties":{"spread":{"type":"string","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","description":"The querent question, if one was provided."},"seed":{"type":"string","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","description":"Position number in the spread layout (1-based)."},"name":{"type":"string","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","meaning","imageUrl"]}},"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","description":"AI-generated narrative connecting all cards in the spread into a 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 7231).","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":"Optional question","description":"Optional querent question to focus the custom tarot reading. Provides context for position-specific interpretations."},"seed":{"type":"string","example":"optional-seed","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","description":"Name of the tarot spread used (e.g. Three-Card, Celtic Cross, Career, Love)."},"question":{"type":"string","description":"The querent question, if one was provided."},"seed":{"type":"string","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","description":"Position number in the spread layout (1-based)."},"name":{"type":"string","description":"Position name describing what this card reveals (e.g. Past, Present, Future, Challenge)."},"interpretation":{"type":"string","description":"Position-specific interpretation of the drawn card, explaining how this card meaning applies to this particular spread position."},"card":{"type":"object","properties":{"id":{"type":"string","description":"Unique card identifier in kebab-case (e.g. the-fool, ace-of-cups)."},"name":{"type":"string","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","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"},"description":"Key themes and concepts associated with this card in its current orientation (upright or reversed)."},"meaning":{"type":"string","description":"Full interpretation of this card in its current orientation."},"imageUrl":{"type":"string","description":"URL to the tarot card artwork image."}},"required":["id","name","arcana","reversed","keywords","meaning","imageUrl"]}},"required":["position","name","interpretation","card"]},"description":"Array of custom spread positions matching your defined layout, each with a drawn card and position-specific interpretation."},"summary":{"type":"string","description":"AI-generated narrative connecting all cards in the spread into a 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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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","description":"Editorial 3-5 sentence reading combining all cycle states into a coherent daily assessment."},"advice":{"type":"string","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","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-01","description":"Start date of the forecast range in YYYY-MM-DD format. Defaults to today (UTC)."},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-01","description":"Start date of the search range in YYYY-MM-DD format. Defaults to today (UTC)."},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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","nullable":true,"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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-15","description":"Birth date of person 1 in YYYY-MM-DD format."}},"required":["birthDate"]},"person2":{"type":"object","properties":{"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1992-03-22","description":"Birth date of person 2 in YYYY-MM-DD format."}},"required":["birthDate"]},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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"},"description":"Relationship strengths based on the compatibility profile."},"challenges":{"type":"array","items":{"type":"string"},"description":"Potential relationship challenges to be aware of."},"advice":{"type":"string","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"1990-07-15","description":"Birth date of the person in YYYY-MM-DD format."},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","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","description":"Concise daily biorhythm message combining energy rating and spotlight cycle."},"advice":{"type":"string","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","description":"General life situation interpretation."},"love":{"type":"string","description":"Love and relationship guidance."},"career":{"type":"string","description":"Career and professional interpretation."},"decision":{"type":"string","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","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 (乾). Supreme success through perseverance.","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","description":"Date this daily casting is for (YYYY-MM-DD, UTC)."},"seed":{"type":"string","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","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","description":"General life situation interpretation."},"love":{"type":"string","description":"Love and relationship guidance."},"career":{"type":"string","description":"Career and professional interpretation."},"decision":{"type":"string","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","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."},"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","description":"The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance."},"image":{"type":"string","description":"The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action."},"interpretation":{"type":"object","properties":{"general":{"type":"string","description":"General life situation interpretation."},"love":{"type":"string","description":"Love and relationship guidance."},"career":{"type":"string","description":"Career and professional interpretation."},"decision":{"type":"string","description":"Decision-making guidance for whether to act, wait, or change course."},"advice":{"type":"string","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 7231).","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":20,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-20, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-20, default 20.","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"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 7231).","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 7231).","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 7231).","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 7231).","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 7231).","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 7231).","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 7231).","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","nullable":true,"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","description":"Total number of crystals associated with this zodiac sign."},"limit":{"type":"number","description":"Maximum crystals returned per page."},"offset":{"type":"number","description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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","nullable":true,"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","description":"Total number of crystals associated with this chakra."},"limit":{"type":"number","description":"Maximum crystals returned per page."},"offset":{"type":"number","description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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","nullable":true,"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","description":"Total number of crystals associated with this element."},"limit":{"type":"number","description":"Maximum crystals returned per page."},"offset":{"type":"number","description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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","description":"The month number that was queried (1-12)."},"monthName":{"type":"string","example":"February","description":"Full name of the queried month."},"total":{"type":"number","description":"Number of birthstone crystals for this month."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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","nullable":true,"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","description":"The search query that was used."},"total":{"type":"number","description":"Total number of crystals matching the query."},"limit":{"type":"number","description":"Maximum crystals returned per page."},"offset":{"type":"number","description":"Number of crystals skipped."},"crystals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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 (e.g., \"amethyst\", \"rose-quartz\")."},"required":true,"description":"URL-safe crystal identifier to find pairings for (e.g., \"amethyst\", \"rose-quartz\").","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":3,"description":"Number of recommended crystal pairings."},"pairings":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Paired crystal display name."},"id":{"type":"string","description":"URL-safe identifier for the paired crystal."},"imageUrl":{"type":"string","nullable":true,"description":"URL to paired crystal photograph."},"description":{"type":"string","description":"Brief overview of the paired crystal."},"chakras":{"type":"array","items":{"type":"string"},"description":"Chakra associations for the paired crystal."},"keywords":{"type":"array","nullable":true,"items":{"type":"string"},"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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","nullable":true,"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","description":"Overview of the crystal covering primary healing purpose and benefits."},"chakras":{"type":"array","items":{"type":"string"},"description":"Chakra energy centers this crystal resonates with for energy healing practice."},"zodiacSigns":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Zodiac signs this crystal is traditionally associated with. Null when zodiac data is unavailable."},"affirmation":{"type":"string","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 7231).","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","nullable":true,"description":"URL to crystal photograph for visual display."},"description":{"type":"string","description":"Overview of the crystal covering primary healing purpose and benefits."},"chakras":{"type":"array","items":{"type":"string"},"description":"Chakra energy centers this crystal resonates with."},"zodiacSigns":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Zodiac signs this crystal is traditionally associated with. Null when zodiac data is unavailable."},"affirmation":{"type":"string","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 7231).","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":35,"description":"Total number of unique color values in the database."},"colors":{"type":"array","items":{"type":"string"},"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 7231).","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":12,"description":"Total number of unique planetary values in the database."},"planets":{"type":"array","items":{"type":"string"},"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 7231).","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","nullable":true,"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":80,"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","description":"Crystal display name."},"id":{"type":"string","description":"URL-safe crystal identifier for detail lookup."},"imageUrl":{"type":"string","nullable":true,"description":"URL to crystal photograph for visual identification."},"colors":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Primary colors of this crystal variety. Null when color data is unavailable."},"chakras":{"type":"array","items":{"type":"string"},"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 7231).","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 (e.g., \"amethyst\", \"rose-quartz\", \"black-tourmaline\"). Must match an entry in the database."},"required":true,"description":"URL-safe crystal identifier (e.g., \"amethyst\", \"rose-quartz\", \"black-tourmaline\"). 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","nullable":true,"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","description":"Overview of the crystal covering its primary healing purpose, spiritual significance, and key benefits."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","nullable":true,"description":"Spiritual and metaphysical healing properties including energy work, meditation benefits, and higher consciousness connections. Null when spiritual interpretation is unavailable."},"emotional":{"type":"string","description":"Emotional healing properties including stress relief, relationship support, and emotional balance benefits."},"physical":{"type":"string","nullable":true,"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"},"description":"Chakra energy centers this crystal resonates with. One of: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown."},"zodiacSigns":{"type":"array","nullable":true,"items":{"type":"string"},"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","nullable":true,"example":"Jupiter","description":"Ruling planet or celestial body associated with this crystal in astrological tradition. Null when planetary association is unavailable."},"elements":{"type":"array","nullable":true,"items":{"type":"string"},"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","nullable":true,"items":{"type":"string"},"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","nullable":true,"items":{"type":"string"},"description":"Five to nine keywords capturing the core healing properties and spiritual themes of this crystal. Null when keyword data is unavailable."},"birthMonth":{"type":"number","nullable":true,"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","description":"Positive affirmation aligned with this crystal energy. Use for meditation, journaling, or daily affirmation features."},"pairsWith":{"type":"array","items":{"type":"string"},"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 7231).","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","nullable":true,"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 7231).","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 7231).","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":{"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 7231).","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 7231).","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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","description":"Date of the daily dream symbol in YYYY-MM-DD format (UTC). Determines which symbol is selected for seeded readings."},"seed":{"type":"string","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","description":"Unique symbol identifier in kebab-case. Use this to fetch full details via /symbols/{id}."},"name":{"type":"string","description":"Display name of the dream symbol."},"letter":{"type":"string","description":"Starting letter (a-z) for alphabetical navigation."},"meaning":{"type":"string","description":"Full psychological dream interpretation explaining the subconscious symbolism, emotional significance, and waking-life connections."}},"required":["id","name","letter","meaning"]},"dailyMessage":{"type":"string","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 7231).","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 all 43 angel numbers covering root digits (0-9), master numbers (11, 22, 33), double digits (44-99), triple repeating (111-999), quad repeating (1111-9999), mirror patterns (1212), and sequential numbers (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","nullable":true,"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"],"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 patterns like 1212. \"master\" returns 11, 22, 33. \"root\" returns single digits 0-9."},"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 patterns like 1212. \"master\" returns 11, 22, 33. \"root\" returns single digits 0-9.","name":"type","in":"query"}],"responses":{"200":{"description":"List of angel numbers with summary information","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","description":"Total number of angel numbers matching the applied filters. 43 for the full set, fewer when filtered by type."},"limit":{"type":"number","description":"Maximum items returned per page."},"offset":{"type":"number","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","description":"Short descriptive title capturing the core theme and spiritual significance of this angel number."},"coreMessage":{"type":"string","example":"Your thoughts are creating your reality. Think positively. 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)."},"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","alignment","angel number","synchronicity"],"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 7231).","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, and twin flame interpretations along with keywords, affirmation, and actionable steps. Covers 43 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","description":"Short descriptive title capturing the core theme and spiritual significance of this angel number."},"coreMessage":{"type":"string","example":"Your thoughts are creating your reality. Think positively. 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)."},"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","alignment","angel number","synchronicity"],"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","description":"Two to three paragraph spiritual interpretation covering divine guidance, higher purpose, and the metaphysical significance of this angel number sequence."},"love":{"type":"string","description":"Love and relationship interpretation covering singles, couples, and those healing from past relationships. Includes romantic guidance and partnership advice."},"career":{"type":"string","description":"Career and financial guidance including professional opportunities, money mindset, and practical advice for work life aligned with this angel number energy."},"twinFlame":{"type":"string","description":"Twin flame connection interpretation covering union, separation, and spiritual growth within the twin flame journey."}},"required":["spiritual","love","career","twinFlame"]},"affirmation":{"type":"string","example":"My thoughts are powerful. I choose to focus on what I desire.","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":["Monitor your thoughts carefully","Set clear positive intentions","Take inspired action on new opportunities"],"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","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 7231).","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), calculates the numerology digit root, checks the database for a known meaning, and provides the foundational digit root interpretation as a fallback. 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"}],"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."},"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","nullable":true,"properties":{"title":{"type":"string","description":"Title of the matched angel number meaning."},"coreMessage":{"type":"string","description":"Core message summary."},"energy":{"type":"string","description":"Energy classification (positive, neutral, cautionary)."},"keywords":{"type":"array","items":{"type":"string"},"description":"Keywords for this angel number."},"meaning":{"type":"object","properties":{"spiritual":{"type":"string","description":"Spiritual interpretation covering divine guidance, higher purpose, and metaphysical significance."},"love":{"type":"string","description":"Love and relationship interpretation for singles, couples, and those healing from past relationships."},"career":{"type":"string","description":"Career and financial guidance including professional opportunities and money mindset."},"twinFlame":{"type":"string","description":"Twin flame connection interpretation covering union, separation, and spiritual growth."}},"required":["spiritual","love","career","twinFlame"],"description":"Detailed interpretations across four life areas: spiritual, love, career, and twin flame."},"affirmation":{"type":"string","description":"Positive affirmation for this number."},"actionSteps":{"type":"array","items":{"type":"string"},"description":"Actionable steps when you see this number."}},"required":["title","coreMessage","energy","keywords","meaning","affirmation","actionSteps"],"description":"Full angel number meaning if this number exists in the database (43 known numbers). Null if the number is not in the database, in which case use the analysis fields (type, digitRoot) for interpretation."},"digitRootMeaning":{"type":"object","nullable":true,"properties":{"number":{"type":"string","example":"3","description":"Root digit number (0-9) or master number (11, 22, 33)."},"title":{"type":"string","description":"Title of the root digit meaning in numerology."},"coreMessage":{"type":"string","description":"Core message of the foundational root digit."}},"required":["number","title","coreMessage"],"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."}},"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 7231).","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, and twin flame interpretations. 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","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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","description":"Short descriptive title capturing the core theme and spiritual significance of the daily angel number."},"coreMessage":{"type":"string","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","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","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","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","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","description":"Love and relationship interpretation covering singles, couples, and those healing from past relationships. Includes romantic guidance and partnership advice."},"career":{"type":"string","description":"Career and financial guidance including professional opportunities, money mindset, and practical advice for work life."},"twinFlame":{"type":"string","description":"Twin flame connection interpretation covering union, separation, and spiritual growth within the twin flame journey."}},"required":["spiritual","love","career","twinFlame"],"description":"Detailed interpretations across four life areas for the daily angel number."},"keywords":{"type":"array","items":{"type":"string"},"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","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"},"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","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 7231).","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":"City autocomplete and geocoding search across 7,000+ locations in 227 countries. Returns geographic coordinates (latitude, longitude), IANA timezone, and DST-aware UTC offset for each match. Built for birth chart location pickers, horoscope apps, event scheduling, and any feature requiring place-to-coordinates resolution. Partial name matching with intelligent ranking: exact prefix matches first, then sorted by population for relevance. Covers all major cities in Europe, Americas, Asia, Africa, and Oceania.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"City name to search for. Matches against city name, province/state, or combined \"city country\" queries. Case-insensitive with partial matching (e.g. \"ber\" matches Berlin, Bern, Bergen).","example":"berlin"},"required":true,"description":"City name to search for. Matches against city name, province/state, or combined \"city country\" queries. Case-insensitive with partial matching (e.g. \"ber\" matches Berlin, Bern, Bergen).","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","nullable":true,"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 cities sorted by relevance (prefix match first) then population","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":3,"description":"Total number of cities matching the search query."},"limit":{"type":"number","example":10,"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. Helps disambiguate cities with the same name across regions (e.g. Springfield IL vs Springfield MO).","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). Use with JavaScript Date, Luxon, day.js, or any date library for accurate local time conversion.","example":"Europe/Berlin"},"utcOffset":{"type":"number","description":"Current UTC offset in decimal hours, automatically adjusted for daylight saving time. Pass directly as the timezone parameter in astrology API endpoints. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal.","example":1},"population":{"type":"number","description":"City population estimate from geographic databases. Larger cities rank higher in search results, ensuring major metropolitan areas appear first in autocomplete suggestions.","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":"City results for the current page, sorted by relevance (prefix match first) then population."}},"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 7231).","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 227 countries - ISO codes and city coverage","description":"Returns all 227 countries 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":50,"default":50,"example":50,"description":"Maximum items to return per page. Range: 1-50, default 50."},"required":false,"description":"Maximum items to return per page. Range: 1-50, default 50.","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"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 227 countries with ISO codes and city counts","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":227,"description":"Total number of countries available."},"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 cities available for this country. Useful for showing coverage in UI or deciding whether to offer city search for a given country.","example":82}},"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 7231).","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":200,"default":50,"example":50,"description":"Maximum items to return per page. Range: 1-200, default 50."},"required":false,"description":"Maximum items to return per page. Range: 1-200, default 50.","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"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":82,"description":"Total number of cities available for this country."},"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. Helps disambiguate cities with the same name across regions (e.g. Springfield IL vs Springfield MO).","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). Use with JavaScript Date, Luxon, day.js, or any date library for accurate local time conversion.","example":"Europe/Berlin"},"utcOffset":{"type":"number","description":"Current UTC offset in decimal hours, automatically adjusted for daylight saving time. Pass directly as the timezone parameter in astrology API endpoints. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal.","example":1},"population":{"type":"number","description":"City population estimate from geographic databases. Larger cities rank higher in search results, ensuring major metropolitan areas appear first in autocomplete suggestions.","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 7231).","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","example":"Pro"},"usedThisMonth":{"type":"number","example":1523},"requestsPerMonth":{"type":"number","example":10000},"remainingThisMonth":{"type":"number","example":8477},"email":{"type":"string","format":"email"},"status":{"type":"string","example":"active"},"endDate":{"type":"string","format":"date-time"}},"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 7231).","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"]}}}}}}}}}