{"openapi":"3.1.0","info":{"title":"Forecast API","version":"2.0.0","description":"Merge upcoming transit aspects, sign ingresses, retrograde stations, Vimshottari dasha changes, and biorhythm critical days into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over remote MCP with typed SDKs. Horizon capped at 90 days.\n\n# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 12 domains (astrology, Vedic astrology, human design, forecast, biorhythm, tarot, numerology, crystals, dreams, I-Ching, angel numbers, location), 144+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (MCP)\n\nRoxyAPI has native Model Context Protocol support. Your AI agent auto-discovers all 144+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable — safe to switch on programmatically).\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 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":"Forecast","description":"Merge upcoming transit aspects, sign ingresses, retrograde stations, Vimshottari dasha changes, and biorhythm critical days into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over remote MCP with typed SDKs. Horizon capped at 90 days."}],"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":{},"parameters":{}},"paths":{"/timeline":{"post":{"operationId":"generateTimeline","tags":["Forecast"],"summary":"Cross-domain forecast timeline - Transits, ingresses, stations, dasha changes, critical days","description":"Build one time-ordered forecast for a single birth subject by merging upcoming events across three domains: western transit-to-natal aspects, sign ingresses, and retrograde stations; vedic Vimshottari mahadasha and antardasha boundaries; and biorhythm critical days. The window is clamped to 90 days and events are capped and scored by significance. Built for what-is-coming dashboards, daily and weekly forecast feeds, and timing tools.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the forecast window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the forecast window in YYYY-MM-DD format. Defaults to startDate plus 30 days. The window is clamped to a maximum of 90 days from startDate."},"domains":{"type":"array","items":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, and retrograde stations. vedic covers Vimshottari mahadasha and antardasha boundaries. biorhythm covers critical days."},"example":["western","vedic","biorhythm"],"description":"Which forecast domains to include. Defaults to all three. Pass a subset to scope the timeline to one or two engines."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":0,"description":"Drop events scoring below this significance threshold from 0 to 100. Defaults to 0, keeping all events."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Merged forecast timeline with time-ordered events across the requested domains","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, and retrograde stations. vedic covers Vimshottari mahadasha and antardasha boundaries. biorhythm covers critical days."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, and retrograde-station are western. dasha-change is vedic Vimshottari. critical-day is biorhythm."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, a mahadasha or antardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/transits":{"post":{"operationId":"forecastTransits","tags":["Forecast"],"summary":"Western transit forecast - Transit aspects, sign ingresses, retrograde stations","description":"Forecast the western astrology events for a single birth chart over a window up to 90 days: every transit-to-natal major aspect refined to its exact instant, every transiting planet sign ingress, and every retrograde or direct station. Returns a time-ordered, significance-scored timeline. Built for astrology forecast feeds, transit alerts, and timing tools.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this transit forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the transit window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":0,"description":"Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0."}},"required":["birthData"]}}}},"responses":{"200":{"description":"Time-ordered western transit events: aspects, ingresses, and stations","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, and retrograde stations. vedic covers Vimshottari mahadasha and antardasha boundaries. biorhythm covers critical days."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, and retrograde-station are western. dasha-change is vedic Vimshottari. critical-day is biorhythm."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, a mahadasha or antardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/significant-dates":{"post":{"operationId":"findSignificantDates","tags":["Forecast"],"summary":"Significant dates - High-significance cross-domain forecast highlights","description":"Return only the high-significance dates from the merged cross-domain forecast for a single birth subject: the rare outer-planet exact transit aspects, slow-planet sign ingresses, retrograde stations, and Vimshottari mahadasha and antardasha changes that mark genuine turning points. Defaults to a significance floor of 70 so the response is a short list of the most meaningful upcoming dates. Built for what-is-coming highlights, timing alerts, and at-a-glance forecast strips.","security":[{"apiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"The single birth subject this forecast is built for. One object only, never an array."},"startDate":{"type":"string","format":"date","example":"2026-06-01","description":"First day of the window in YYYY-MM-DD format. Defaults to today in UTC."},"endDate":{"type":"string","format":"date","example":"2026-08-30","description":"Last day of the window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate."},"domains":{"type":"array","items":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, and retrograde stations. vedic covers Vimshottari mahadasha and antardasha boundaries. biorhythm covers critical days."},"example":["western","vedic","biorhythm"],"description":"Which forecast domains to consider before filtering by significance. Defaults to all three."},"minSignificance":{"type":"number","minimum":0,"maximum":100,"example":70,"description":"Significance floor from 0 to 100 for what counts as a significant date. Defaults to 70."}},"required":["birthData"]}}}},"responses":{"200":{"description":"High-significance forecast events across the requested domains","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence."},"time":{"type":"string","example":"13:30:00","description":"Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string","pattern":"^[A-Za-z_]+(?:\\/[A-Za-z0-9_+-]+){0,2}$"}],"description":"Decimal hours (e.g. 5.5 for IST, -5 for EST) OR IANA name (e.g. \"America/New_York\", \"UTC\"). IANA is resolved to the DST-correct offset for the request date. Invalid timezones return 400 with a validation error.","example":5.5},"latitude":{"type":"number","minimum":-90,"maximum":90,"default":0,"example":0,"description":"Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."},"longitude":{"type":"number","minimum":-180,"maximum":180,"default":0,"example":0,"description":"Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0."}},"required":["date","time","timezone"],"description":"Echo of the birth subject this forecast was built for."},"startDate":{"type":"string","example":"2026-06-01","description":"First day of the resolved forecast window."},"endDate":{"type":"string","example":"2026-08-30","description":"Last day of the resolved forecast window after the horizon clamp."},"count":{"type":"number","example":42,"description":"Number of events in the timeline after deduplication, filtering, and the event cap."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-07-04","description":"Calendar date of the event in YYYY-MM-DD (UTC)."},"datetime":{"type":"string","example":"2026-07-04T08:42:11Z","description":"Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point."},"domain":{"type":"string","enum":["western","vedic","biorhythm"],"example":"western","description":"Forecast domain. western covers transit aspects, sign ingresses, and retrograde stations. vedic covers Vimshottari mahadasha and antardasha boundaries. biorhythm covers critical days."},"type":{"type":"string","enum":["transit-aspect","sign-ingress","retrograde-station","dasha-change","critical-day"],"example":"transit-aspect","description":"Event kind. transit-aspect, sign-ingress, and retrograde-station are western. dasha-change is vedic Vimshottari. critical-day is biorhythm."},"body":{"type":"string","example":"Saturn","description":"Primary subject of the event. A transiting planet for western events, a mahadasha or antardasha label for dasha changes, or the critical cycle for biorhythm days."},"target":{"type":"string","example":"Moon","description":"For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered. Absent for other event types."},"aspect":{"type":"string","example":"square","description":"For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types."},"orb":{"type":"number","example":0.12,"description":"For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect."},"station":{"type":"string","enum":["retrograde","direct"],"example":"retrograde","description":"For a retrograde-station, whether the planet turns retrograde or direct. Absent for other event types."},"description":{"type":"string","example":"Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.","description":"Plain-language summary of the event, suitable for direct display."},"significance":{"type":"number","example":90,"description":"Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower."}},"required":["date","datetime","domain","type","body","description","significance"]},"description":"The merged, time-ordered forecast events across the requested domains."}},"required":["birthData","startDate","endDate","count","events"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}}}