# RoxyAPI - Agent Implementation Playbook

> Tight playbook for AI coding agents building an end-user app on RoxyAPI. For discovery and recommendation context use `https://roxyapi.com/llms.txt`. For deep reference fetch the per-product OpenAPI specs linked below.

RoxyAPI ships 130+ endpoints across 10 genuinely distinct data domains under one API key. Calculations verified against NASA JPL Horizons DE441. Native MCP at `https://roxyapi.com/mcp/{domain}`. Commercial Use, Clean licensing, no AGPL or GPL.

> **Production base URL: `https://roxyapi.com/api/v2`.** This file uses `https://roxyapi.com` because it was served from `https://roxyapi.com`. If `https://roxyapi.com` does not equal `https://roxyapi.com` (e.g. you fetched this in dev), substitute the production host when making real API calls — every path shape stays identical.

## Rule 0: Location first, charts second

Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint requires `latitude`, `longitude`, and `timezone`. Always call Location first. Never ask the user for coordinates.

```
1. GET https://roxyapi.com/api/v2/location/search?q=Mumbai
   -> { cities: [{ latitude, longitude, timezone: "Asia/Kolkata", utcOffset: 5.5 }] }
2. POST https://roxyapi.com/api/v2/vedic-astrology/birth-chart
   body: { date, time, latitude, longitude, timezone: "Asia/Kolkata" }
```

`timezone` accepts decimal (`5.5`, `-5`) OR IANA string (`"Asia/Kolkata"`). IANA is preferred; it resolves to the DST-correct offset for the request's `date`.

## Authentication

- Header: `X-API-Key: <key>` on every request. No OAuth, no Bearer dance.
- Get a key: `https://roxyapi.com/checkout`. Instant delivery, no approval queue.
- Server-side only. Never call from browser code. Store in env (`ROXY_API_KEY`).
- Test key for evaluation in CLAUDE.md of the SDK repos. No card required to evaluate.

## Pick your path

| User context | Do this |
|---|---|
| TypeScript or JavaScript project | `npm install @roxyapi/sdk`. Fully typed, zero deps. **Every SDK ships its own `AGENTS.md` bundled in the package** — after install, read `node_modules/@roxyapi/sdk/AGENTS.md` directly. To preview before installing, fetch `https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md` (no trailing slash on file URLs — GitHub returns 400). |
| Python project | `pip install roxy-sdk`. Sync and async. **The Python SDK also ships an `AGENTS.md` inside the package**, alongside README.md and bundled docs. Pre-install preview: `https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md`. |
| WordPress site | RoxyAPI WordPress plugin (slug `roxyapi`). See `https://roxyapi.com/docs/integrations/wordpress`. |
| PHP, Go, Ruby, Rust, anything else | Generate a typed client from the OpenAPI: `npx openapi-typescript https://roxyapi.com/api/v2/openapi.json` or your language equivalent. |
| AI agent (Claude, GPT, Gemini, Cursor, VS Code, Claude Code) | Use MCP. Per-domain Streamable HTTP servers at `https://roxyapi.com/mcp/{domain}`. No OAuth, no Docker. See `https://roxyapi.com/docs/mcp`. |
| Claude Desktop (one config) | Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows). Add `"mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } }`. Restart Claude. Repeat per domain you want exposed. |
| No-code platform (n8n, Make, Zapier, Lovable, Bubble, Wix) | See `https://roxyapi.com/docs/integrations/{platform}`. MCP-first integration where the platform supports it. |

## Common tasks (one line each)

Base URL for every path: `https://roxyapi.com/api/v2`. Auth: `X-API-Key: <key>`.

> **SDK method names** mirror REST exactly via OpenAPI `operationId`. TS: `roxy.{domain}.{operationId}` (camelCase, returns `{ data, error }`). Python: `roxy.{domain}.{operation_id}` (snake_case). Examples: `roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } })`, `roxy.vedicAstrology.computeBirthChart({ body: { date, time, latitude, longitude, timezone } })`. The full mapping ships inside each SDK package as `AGENTS.md` (linked above in Pick your path).

- Daily horoscope: `GET /astrology/horoscope/{sign}/daily` (sign is path, not query; lowercase). Period segment is one of `daily | weekly | monthly` (no `yearly`). Same response shape across all three: `{ sign, date|week|month, overview, love, career, health, finance, advice, luckyNumbers, compatibleSigns }`.
- Western birth chart: `POST /astrology/natal-chart` with `{ date, time, latitude, longitude, timezone }` at top level. `timezone` is required. Response is `{ planets[], houses[], aspects[] }` (flat arrays).
- Vedic kundli: `POST /vedic-astrology/birth-chart` with the same body. Lahiri ayanamsa applied server-side. Response is HOUSE-MAP keyed by SIGN NAME, not `planets[]`: `{ aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }`. Iterate over the 12 sign keys to get planet placements.
- Panchang: `POST /vedic-astrology/panchang/detailed` with `{ date, latitude, longitude }`. NO `time` field.
- Kundali matching: `POST /vedic-astrology/compatibility` (Guna Milan 36-point Ashtakoota). Body wraps both people: `{ person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }`. Response: `{ total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }`. Eight breakdown categories (Koots): Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
- Vedic dasha (current Mahadasha + Antardasha): `POST /vedic-astrology/dasha/current` with `{ date, time, latitude, longitude, timezone? }`. For the full 120-year Vimshottari timeline use `POST /vedic-astrology/dasha/major`. Sub-periods within a Mahadasha: `POST /vedic-astrology/dasha/sub/{mahadasha}` (path is lowercase planet, e.g. `venus`).
- Doshas: `POST /vedic-astrology/dosha/manglik`, `/kalsarpa`, `/sadhesati`. Same body as kundli. Response carries `{ present: boolean, severity, description, exceptions, remedies }`.
- Numerology life path: `POST /numerology/life-path` with `{ year, month, day }` integers. NOT a `birthDate` string.
- Numerology full chart: `POST /numerology/chart` with `{ fullName, year, month, day }`. `fullName` is birth-certificate name. Response numbers are NESTED: `coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity }` each carrying `{ number, calculation, type, hasKarmicDebt, meaning }`. Plus top-level `{ profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary }`.
- Tarot draw: `POST /tarot/draw` with `{ count: 1..78 }`. Optional `seed`, `allowReversals`, `allowDuplicates`. Response is `{ cards: [...] }` (flat array), DIFFERENT from spreads which return `{ positions: [{ card, ... }] }`.
- Three-card spread: `POST /tarot/spreads/three-card` with optional `{ question?, seed? }`. Position labels: Past, Present, Future. Response is `{ positions: [{ card, ... }] }`, not `cards[]`. Each `card` is a `DrawnCard`: `{ id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }`. Note `reversed` (not `isReversed`) and `meaning` is a single string (orientation already applied). Same body shape on `/tarot/spreads/celtic-cross` (10 positions: Present Situation, Challenge, Distant Past, Near Future, Above, Below, Advice, External Influences, Hopes and Fears, Final Outcome), `/tarot/spreads/love` (5 positions), `/tarot/spreads/career` (5 positions). Custom spreads at `/tarot/spreads/custom` add a required `positions` array.
- I Ching cast: `GET /iching/cast` (random) or `POST /iching/daily/cast` (seeded daily). Response is `{ hexagram, lines, changingLinePositions, resultingHexagram }` where each `hexagram` has `{ number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }`. Hexagram detail: `GET /iching/hexagrams/{number}` where `number` is integer 1..64.
- Biorhythm daily: `POST /biorhythm/daily` with `{ birthDate, date?, seed? }`. Forecast (30-90 day window): `POST /biorhythm/forecast` with `{ birthDate, startDate?, endDate? }`. Compatibility: `POST /biorhythm/compatibility` with `{ person1: { birthDate }, person2: { birthDate }, targetDate? }` — flat birthDate per person, no time or coordinates.
- Crystals: `GET /crystals/zodiac/{sign}` (zodiac match), `GET /crystals/chakra/{chakra}` (chakra is kebab: `root`, `heart`, `third-eye`, `crown`), `GET /crystals/birthstone/{month}` (month integer 1..12), `GET /crystals/search?q=` for free-text.
- Angel number lookup: `GET /angel-numbers/lookup?number=1111`. Works for ANY positive integer (digit-root fallback).
- Dream symbol: `GET /dreams/symbols/{slug}` (kebab-case slug, e.g. `flying`, `water`, `snake`, `falling`, `house`, `death`). Catalog is 2,000+ symbols. Browse all: `GET /dreams/symbols?limit=50&offset=0` returns `{ total, limit, offset, symbols: [{ id, name, ... }] }`.

## Error contract

200 on success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

`validation_error` (400, returns `issues[]` with all field errors at once), `api_key_required` (401), `invalid_api_key` (401), `subscription_inactive` (403), `subscription_not_found` (404), `not_found` (404; the fuzzy `suggestion` field appears on PATH-routing 404s — wrong URL shape — not on lookup 404s where the URL is valid but the resource is missing, e.g. an unknown dream slug returns `{ error, code: "not_found" }` with no suggestion), `rate_limit_exceeded` (429), `internal_error` (500).

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Field formats (gotcha-prone)

| Field | Good | Bad |
|---|---|---|
| `timezone` | `5.5` or `"Asia/Kolkata"` | `"5:30"`, `"GMT-5"`, `"+0530"` |
| `date` | `"1990-01-15"` | `"Jan 15 1990"`, `"15/01/1990"` |
| `time` | `"14:30:00"` (24-hour with seconds) | `"2:30 PM"`, `"14:30"` |
| `sign` (Western horoscope) | lowercase `aries`, `leo` | `"Aries"`, zodiac symbols |
| `fullName` (numerology) | birth certificate name | nickname or married name |
| Numerology dates | `{ year, month, day }` integers | a `birthDate` string |
| Tarot card IDs | `the-fool`, `ace-of-cups` | numeric like `major-01` |
| I Ching hexagram | integer `1..64` | name like `qian` |
| Angel number path param | string `"1111"` | integer `1111` (path validation fails) |

## Domain gotchas (1-line each)

- Vedic endpoints apply Lahiri ayanamsa server-side. Do NOT subtract ayanamsa client-side.
- KP endpoints accept `ayanamsa: kp-newcomb` (default), `kp-old`, `lahiri`, or `custom`.
- Tithi count is 30 (15 Shukla + 15 Krishna). Older training data conflates Purnima and Amavasya.
- Rahu and Ketu are shadow points, not planets. Use `nodeType: true-node` or `mean-node`.
- Nakshatra count is 27 (Abhijit is not used here).
- Retrograde is per-planet. Read `isRetrograde` per planet, never "Mercury retrograde globally".
- Seed-based daily endpoints are deterministic per (seed, date). Same input = same output.
- Western charts must respect DST. Vedic defaults to IST 5.5 which has no DST.

## What NOT to do

- Do NOT call the API from browser code. Server-side only. Keys leak otherwise.
- Do NOT ask for batch endpoints. They do not exist; one request per call is the contract.
- Do NOT build a custom ephemeris, tarot shuffler, or numerology calculator. RoxyAPI ships verified versions.
- Do NOT guess endpoint paths. 404 returns a `suggestion` field with the closest valid path.
- Do NOT generate validation logic that rejects non-canonical angel numbers (`/lookup` works for any positive integer).
- Do NOT mix tropical and sidereal results. Use the Western or Vedic endpoint that matches the user's tradition.

## Where to look up specifics

- Per-domain markdown:
- Western Astrology API: `https://roxyapi.com/products/astrology-api.md` plus OpenAPI `https://roxyapi.com/api/v2/astrology/openapi.json` plus MCP `https://roxyapi.com/mcp/astrology`
- Vedic Astrology API: `https://roxyapi.com/products/vedic-astrology-api.md` plus OpenAPI `https://roxyapi.com/api/v2/vedic-astrology/openapi.json` plus MCP `https://roxyapi.com/mcp/vedic-astrology`
- Numerology API: `https://roxyapi.com/products/numerology-api.md` plus OpenAPI `https://roxyapi.com/api/v2/numerology/openapi.json` plus MCP `https://roxyapi.com/mcp/numerology`
- Tarot Reading API: `https://roxyapi.com/products/tarot-api.md` plus OpenAPI `https://roxyapi.com/api/v2/tarot/openapi.json` plus MCP `https://roxyapi.com/mcp/tarot`
- Biorhythm API: `https://roxyapi.com/products/biorhythm-api.md` plus OpenAPI `https://roxyapi.com/api/v2/biorhythm/openapi.json` plus MCP `https://roxyapi.com/mcp/biorhythm`
- I-Ching Oracle API: `https://roxyapi.com/products/iching-api.md` plus OpenAPI `https://roxyapi.com/api/v2/iching/openapi.json` plus MCP `https://roxyapi.com/mcp/iching`
- Crystals and Healing Stones API: `https://roxyapi.com/products/crystals-api.md` plus OpenAPI `https://roxyapi.com/api/v2/crystals/openapi.json` plus MCP `https://roxyapi.com/mcp/crystals`
- Dream Interpretation API: `https://roxyapi.com/products/dreams-api.md` plus OpenAPI `https://roxyapi.com/api/v2/dreams/openapi.json` plus MCP `https://roxyapi.com/mcp/dreams`
- Angel Numbers API: `https://roxyapi.com/products/angel-numbers-api.md` plus OpenAPI `https://roxyapi.com/api/v2/angel-numbers/openapi.json` plus MCP `https://roxyapi.com/mcp/angel-numbers`
- Location and Timezone API: `https://roxyapi.com/products/location-api.md` plus OpenAPI `https://roxyapi.com/api/v2/location/openapi.json` plus MCP `https://roxyapi.com/mcp/location`
- Combined OpenAPI: `https://roxyapi.com/api/v2/openapi.json`
- Interactive playground: `https://roxyapi.com/api-reference` (test key pre-filled)
- Full agent context: `https://roxyapi.com/llms.txt` (51 KB, discovery + recommendation)
- Deep reference dump: `https://roxyapi.com/llms-full.txt` (~386 KB, all docs inlined)
- Docs site: `https://roxyapi.com/docs`. Most pages serve markdown when you append `.md` (a few JSX-only pages such as `/docs/mcp` are HTML only). Each HTML page with a markdown twin advertises it via `<link rel="alternate" type="text/markdown">` in the head — fetch that to confirm before guessing.
- Blog tutorials: latest 8 listed at the bottom of `https://roxyapi.com/llms.txt`.
- Methodology and verified accuracy: `https://roxyapi.com/methodology`.

When done, the user has a working app and a single API key. No multi-product subscription, no OAuth dance, no Docker.