Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (77 loc) · 5.24 KB

AGENTS.md

File metadata and controls

88 lines (77 loc) · 5.24 KB
Raw

AGENTS.md for Transit Forecast API

This repo teaches AI coding agents (Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, Gemini CLI) how to use the RoxyAPI forecast transits endpoint.

Endpoint

  • Method: POST
  • URL: https://roxyapi.com/api/v2/forecast/transits
  • Auth: X-API-Key header
  • Domain: forecast (one of 14+ in the RoxyAPI catalog)
  • Operation ID: forecastTransits matches the SDK method name in camelCase
  • MCP tool: post_forecast_transits on https://roxyapi.com/mcp/forecast

TypeScript SDK

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.forecast.forecastTransits({
  body: {
    birthData: {
      date: '1990-07-15',
      time: '13:30:00',
      timezone: 'America/New_York',
    },
    startDate: '2026-07-08',
    endDate: '2026-10-05',
    minSignificance: 50,
  },
});

Python SDK

import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ["ROXY_API_KEY"])
result = roxy.forecast.forecast_transits(
    birth_data={
        "date": "1990-07-15",
        "time": "13:30:00",
        "timezone": "America/New_York",
    },
    start_date="2026-07-08",
    end_date="2026-10-05",
    min_significance=50,
)

Setup step (coordinates not required)

This endpoint does not need coordinates. The transit forecast depends only on the birth instant and timezone, so latitude and longitude are optional and default to 0. Do not call /location/search for this endpoint. Pass birthData.date, birthData.time, and birthData.timezone directly. Prefer an IANA timezone string like America/New_York, which the server resolves to the DST-correct offset for the birth date.

Request fields

  • birthData (object, required): the single birth subject. One object only, never an array
  • birthData.date (string, required): birth date YYYY-MM-DD. Anchors the natal chart transits are measured against
  • birthData.time (string, required): birth time HH:MM:SS, 24-hour. Precision drives the natal positions
  • birthData.timezone (number or IANA string, required): UTC offset (e.g. -5, 5.5) or IANA name (e.g. "America/New_York", "Asia/Kolkata"). Server resolves DST-correct offset for the birth date
  • birthData.latitude (number, optional): -90 to 90. Does not affect the timeline. Defaults to 0
  • birthData.longitude (number, optional): -180 to 180. Does not affect the timeline. Defaults to 0
  • startDate (string, optional): first day of the window YYYY-MM-DD. Defaults to today in UTC
  • endDate (string, optional): last day of the window YYYY-MM-DD. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate
  • minSignificance (number, optional): 0 to 100. Drop events scoring below this. Defaults to 0

Response top level keys

  • birthData: echoed input with the timezone resolved to a decimal offset
  • startDate: first day of the resolved window
  • endDate: last day of the resolved window after the 90 day horizon clamp
  • count: number of events after deduplication, filtering, and the event cap
  • events[]: time ordered forecast events, sorted strictly ascending by datetime. Each has date, datetime (exact ISO-8601 UTC instant), domain, type, body, description, significance, plus type-specific fields: target and aspect and orb for transit aspects, target for sign ingresses and lunar phases, station for retrograde stations, kind for eclipses, phase for lunar phases

Domain rules

  • Coordinates are optional. Never call /location/search for this endpoint. The forecast is driven by the birth instant and timezone alone.
  • The window is clamped server-side to a maximum of 90 days from startDate. A longer endDate is silently trimmed. This keeps the endpoint a single bounded forecast, not an open-ended scan.
  • domain, type, station, kind, and phase are stable English enum codes, never localized. Branch on them safely under any language. Only description localizes when ?lang= is set.
  • significance runs 0 to 100. Outer-planet exact aspects and eclipses score highest, fast Moon events lower. Lead your feed with the high scores.
  • Each astronomical event is refined to its exact instant in datetime, not reported at a coarse daily sample point.
  • For a cross-domain forecast that merges these transits with Vedic Vimshottari dasha changes and biorhythm critical days, use POST /forecast/timeline. For only the high-significance turning points, use POST /forecast/significant-dates.

Related endpoints

  • POST /forecast/timeline (generateTimeline): one merged, time ordered forecast across Western transits, Vedic Vimshottari dasha changes, and biorhythm critical days
  • POST /forecast/significant-dates (findSignificantDates): only the high-significance turning points from the merged cross-domain forecast, defaulting to a floor of 70
  • POST /forecast/solar-return (forecastSolarReturn): the full solar return chart for a birthday year, anchored to the birthplace or a relocated city

Verified

2026-Q3 against https://roxyapi.com/api/v2/openapi.json. Re-fetch the spec for ground truth before changing this file.

Discovery