RoxyAPI/claude-plugin

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 164+ endpoints across 12 genuinely distinct data domains under one API key. Calculations verified against NASA JPL Horizons DE441. Remote MCP at https://roxyapi.com/mcp/{domain}. Commercial Use, Clean licensing, no AGPL or GPL.

Production base URL: https://roxyapi.com/api/v2.

Fastest lookup: the Docs MCP (no API key)

If your agent speaks MCP, connect the public Docs server first: https://roxyapi.com/mcp/docs (Streamable HTTP, one tool search_docs, no key). Ask it for any endpoint, field, SDK method, auth detail, or integration step and it answers straight from this reference, so you never guess a path or hardcode a stale example.

{ "mcpServers": { "roxy-docs": { "type": "http", "url": "https://roxyapi.com/mcp/docs" } } }

For live API calls add a per-domain server (https://roxyapi.com/mcp/{domain}) with your X-API-Key.

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=New York
   -> { cities: [{ latitude, longitude, timezone: "America/New_York", utcOffset: -5 }] }
2. POST https://roxyapi.com/api/v2/astrology/natal-chart
   body: { date, time, latitude, longitude, timezone: "America/New_York" }

q accepts bare city (Tokyo), city + country (Berlin Germany), or comma-qualified (Springfield, Illinois). Use the qualified form to disambiguate same-named cities. Case-insensitive, partial matching.

timezone accepts decimal (-5, 5.5) OR IANA string ("America/New_York"). 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.
• Two key types: secret sk_ for server-side (full access, store in env ROXY_API_KEY, never ship to a browser) and publishable pk_ for browsers, widgets, and no-code embeds (safe in client code when locked to your domains with an origin allowlist). Mint either at https://roxyapi.com/account.

Pick your path

User context	Do this
Want a full app to fork and white-label	Skip the wiring: clone a free, MIT-licensed template at https://roxyapi.com/starters (8 total, flagship is the multi-domain AI Astrology Chatbot wired to remote MCP). Add your API key, rebrand, ship in minutes.
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.
PHP project (Laravel, Symfony, Slim, plain PHP)	composer require roxyapi/sdk. PHP 8.2+, built on Saloon v4, named arguments, PHPDoc-typed Request classes (phpstan level 8 clean). The PHP SDK ships AGENTS.md inside the package at vendor/roxyapi/sdk/AGENTS.md. Pre-install preview: https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. Errors throw a single RoxyApiException carrying $e->statusCode, $e->errorCode (machine-readable), and $e->error (human).
.NET project (ASP.NET Core, Blazor, console)	dotnet add package RoxyApi.Sdk. Fully typed, always in sync with the API. The .NET SDK ships AGENTS.md inside the package. Pre-install preview: https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
Need to render the response in a UI	npm install @roxyapi/ui (or @roxyapi/ui-react for React/Next.js). Drop-in MIT-licensed web components for natal charts, kundli wheels, panchang tables, dasha timelines, tarot spreads, biorhythm curves, hexagrams, numerology cards. Stateless: pass the API response as the data prop. CSS custom properties for theming. Vanilla HTML works too via <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>. Ships its own AGENTS.md at node_modules/@roxyapi/ui/AGENTS.md. Source: https://roxyapi.com/ui.
WordPress site	Install RoxyAPI from the WordPress.org Plugin Directory: https://wordpress.org/plugins/roxyapi/ (or in admin: Plugins → Add New → search "RoxyAPI"). Ships Gutenberg blocks + shortcodes covering all 12 domains, plus its own AGENTS.md for AI coding tools. Integration guide: https://roxyapi.com/docs/integrations/wordpress.
Go project	go get github.com/RoxyAPI/sdk-go. Fully typed, one direct runtime dependency, std net/http. Domain-grouped facade: roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). Build dates with roxyapi.Date(...), optional fields with roxyapi.Ptr(...); a 4xx/5xx is a *roxyapi.RoxyError (switch on .Code). Ships its own AGENTS.md in the module. Pre-install preview: https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
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 / PHP: roxy.{domain}.{operationId} / $roxy->{domain}->{operationId} (camelCase). TS returns { data, error }; PHP returns a typed object and throws RoxyApiException on failure. Python: roxy.{domain}.{operation_id} (snake_case). C# (.NET) is path-fluent instead of operationId-based: roxy.{Domain}.{Resource}.GetAsync() or .PostAsync(new() { ... }) (PascalCase mirroring the URL, path params are indexers like roxy.Astrology.Horoscope["aries"].Daily), and throws RoxyError (switch on e.Code). Go mirrors operationId in PascalCase: roxy.{Domain}.{Method}(ctx, ...) returns (*XxxResponse, error) and a 4xx/5xx is *RoxyError (switch on .Code). Examples: roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } }), roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude, timezone } }), roxy.numerology.calculateLifePath({ body: { year, month, day } }), roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } }). 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). Shared core: { sign, overview, love, career, health, finance, compatibleSigns }. Daily adds { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }. Weekly returns { week, advice, luckyNumbers[], luckyDays[] } (note plural). Monthly returns { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] } (no top-level advice).
• 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.
• Human Design bodygraph: POST /human-design/bodygraph with { date, time, timezone } — NO coordinates (HD uses the birth instant, not the observer location, so no Location step). One call returns { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }. Type-only quiz entry: POST /human-design/type. Two-person compatibility: POST /human-design/connection with { personA, personB } (each { date, time, timezone }).
• Forecast: POST /forecast/transits (Western transit-to-natal aspects, ingresses, retrograde stations) and POST /forecast/timeline (cross-domain merge of Western transits, Vedic dasha boundaries, and biorhythm critical days) both take { birthData: { date, time, timezone }, startDate?, endDate? } — 90-day max horizon, events ranked by significance. Annual birthday chart: POST /forecast/solar-return with { date, time, year, latitude, longitude, timezone } (needs coordinates, so call Location first).
• 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 case-insensitive and space-separated: Root, Sacral, Solar Plexus URL-encoded Solar%20Plexus, Heart, Throat, Third Eye URL-encoded Third%20Eye, Crown — kebab third-eye fails validation), 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 or "America/New_York"	"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

• 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: "mean" (default, traditional Vedic) or "true" (osculating).
• 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 put a secret sk_ key in browser code; it leaks. For client-side or widget use mint a publishable pk_ key and lock it to your origins.
• 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
• Human Design API: https://roxyapi.com/products/human-design-api.md plus OpenAPI https://roxyapi.com/api/v2/human-design/openapi.json plus MCP https://roxyapi.com/mcp/human-design
• Forecast API: https://roxyapi.com/products/forecast-api.md plus OpenAPI https://roxyapi.com/api/v2/forecast/openapi.json plus MCP https://roxyapi.com/mcp/forecast
• 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
• Docs MCP (no key): https://roxyapi.com/mcp/docs, one tool search_docs, searches this whole reference live.
• Interactive playground: https://roxyapi.com/api-reference (browse endpoints, paste your key to test live)
• 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.