@roxyapi/sdk - Agent Guide

TypeScript SDK for RoxyAPI. 18+ domains (Western astrology, Vedic astrology, forecast, human design, Chinese astrology, feng shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, location) plus utility namespaces (usage, languages). One API key, fully typed, zero runtime dependencies.

Before writing any code with this SDK, read docs/llms-full.txt in this package for the complete method reference with examples.

Install and initialize

npm install @roxyapi/sdk

import { createRoxy } from '@roxyapi/sdk';

// Retries 429, 500, 502, 503 and 504 by default. Optional settings, shown with their defaults:
// createRoxy(key, { maxRetries: 2, initialDelayMs: 500, maxDelayMs: 30000 })
const roxy = createRoxy(process.env.ROXY_API_KEY!);

createRoxy sets the base URL (https://roxyapi.com/api/v2) and auth header automatically. Every method returns { data, error, response }.

Critical rule: geocode before any chart endpoint

Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs latitude, longitude, and (for Western) timezone. Never ask the user for coordinates. Always call roxy.location.searchCities first.

const { data } = await roxy.location.searchCities({ query: { q: 'New York' } });
const { latitude, longitude, timezone } = data.cities[0];
// `timezone` is the IANA string ("America/New_York"). Pass it directly to any chart endpoint.
// The server resolves it to the DST-correct decimal offset using the date of the chart itself,
// so a January 1990 New York chart gets EST (-5) even when you looked the city up in July.
// `utcOffset` is the offset in force today, not on the birth date, so pass the IANA `timezone` string.

q accepts bare city ('Paris'), city + country ('Berlin Germany'), or comma-qualified ('Springfield, Illinois'). Use the qualified form to disambiguate same-named cities.

Domains

Type roxy. to see all available namespaces. Type roxy.{domain}. to see every method in that domain.

The table above covers every endpoint across 18+ product domains plus usage and languages, and auto-syncs from specs/openapi.json at release time.

Quality guidelines for agents

The rules to follow when writing any call with this SDK. Get these right and the generated types do the rest.

• One options object, hey-api wrapped. Every method takes a single object with path, query, and body keys. Path params go in path, query params in query, request body in body. Never flat named args. Right: roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } }). Wrong: roxy.astrology.getDailyHoroscope({ sign: 'aries' }).
• Always await. Always destructure { data, error, response }. All methods are async. data is the typed success response (undefined on error). error is the typed API error ({ error, code, doc_url }, plus issues on a validation_error; undefined on success). response is the raw fetch Response and is optional in the types, so write response?.status. Switch on error.code, not on error.error. The pair is a discriminated union, so data is typed as possibly undefined until error is checked: write if (error) throw error; before reading data in a strict project, or pass throwOnError: true in the call options to have failures throw and data typed as always present.
• Method names match the OpenAPI operationId verbatim. When in doubt, autocomplete roxy.{domain}. in your editor or grep 'public ' node_modules/@roxyapi/sdk/dist/factory.d.ts. Never invent a method from the URL path or a guess.
• Response field names come from the response schema of the spec. Field access is typed dot syntax (data.cities[0].timezone). TypeScript will catch any invented field at compile time via the generated types - if tsc complains, the field does not exist.
• Look up any operation or field beyond this guide. Query the combined OpenAPI spec at https://roxyapi.com/api/v2/openapi.json with the jq recipe in https://roxyapi.com/AGENTS.md, or search the keyless Docs MCP server at https://roxyapi.com/mcp/docs (one tool, search_docs).
• Do not hand-roll requests. No raw fetch, no axios. The SDK injects auth, the base URL and typed responses; it retries 429, 500, 502, 503 and 504 up to twice by default (see Retries; createRoxy(key, { maxRetries: 0 }) turns that off). Use createRoxy(key) for the common case, or new Roxy({ client }) with createClient from @roxyapi/sdk/client when you need a custom fetch or interceptors.

Critical patterns

Two-step pattern for coordinate-dependent endpoints

const { data, error } = await roxy.location.searchCities({ query: { q: 'London' } });
if (error) throw error;
const { latitude, longitude, timezone } = data.cities[0];
const birth = { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone };

const { data: chart } = await roxy.astrology.generateNatalChart({ body: birth });

One lookup feeds every domain. The same birth object is the body for astrology.generateNatalChart, vedicAstrology.generateBirthChart, vedicAstrology.getCurrentDasha, ayurveda.calculateAyurvedicConstitution and the birthData of forecast.forecastTransits; the instant alone (date, time, timezone) is the body for humanDesign.generateBodygraph, chineseAstrology.generateBaziChart and kabbalah.generateBirthProfile. Never look the city up twice for one person.

GET endpoints - use path for URL params, query for query params

await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
await roxy.crystals.getCrystalsByZodiac({ path: { sign: 'leo' } });
await roxy.crystals.searchCrystals({ query: { q: 'amethyst' } });

POST endpoints - use body for request data

Most valuable endpoints (charts, spreads, calculations) are POST:

await roxy.astrology.generateNatalChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
});

await roxy.vedicAstrology.generateBirthChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
});

await roxy.tarot.castCelticCross({ body: { question: 'What should I focus on?' } });

await roxy.numerology.calculateLifePath({ body: { year: 1990, month: 1, day: 15 } });

Multi-language via query: { lang }

Ten languages: en, tr, de, es, fr, hi, pt, ru, zh-Hans, zh-Hant. Defaults to en.

await roxy.tarot.getDailyCard({ body: { date: '2026-04-22' }, query: { lang: 'es' } });
await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
  query: { lang: 'hi' },
});

Supported: astrology, vedicAstrology, forecast, humanDesign, chineseAstrology, fengShui, mesoamericanAstrology, vastu, numerology, kabbalah, tarot, biorhythm, ayurveda, iching, crystals, angelNumbers, languages. English-only: dreams, location, usage. The two Chinese scripts (zh-Hans, zh-Hant) currently ship on Chinese astrology and feng shui; every other domain answers those codes in English per field. To list supported codes at runtime, call roxy.languages.listLanguages().

Common tasks

In the catalog order (Western astrology, Vedic astrology, forecast, Human Design, Chinese astrology, feng shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, location, usage, languages). birth is { date, time, latitude, longitude, timezone } from the two-step pattern above.

Field formats that trip agents

These are the fields AI agents most often get wrong. Copy the format column exactly.

Timezone cheat sheet (most-asked locations)

DST matters. If the birth date falls inside a daylight-saving window, use the summer / DST offset, or pass the IANA string from the location lookup and let the server resolve it. India observes no DST, so a fixed 5.5 is always right there; anywhere else, a natal chart must carry the offset in force at the time of birth.

Astrology domain gotchas for LLMs

LLMs hallucinate confidently in this category. These are the specific traps you will hit when writing client code:

• Ayanamsa is server-side in Vedic. LLMs default to tropical / Western math. Vedic endpoints apply sidereal Lahiri ayanamsa server-side. KP endpoints accept ayanamsa of kp-newcomb (default), kp-old, lahiri, or custom. Do not try to "correct" server output by subtracting ayanamsa in client code.
• Tithi count is 30, not 2. 15 Shukla (waxing) plus 15 Krishna (waning). Older LLM training data conflates Purnima and Amavasya as single tithis. Our panchang response carries a paksha field ("Shukla" or "Krishna") plus a tithi number, so there are 30 distinct tithis in a lunar month.
• Rahu and Ketu are shadow points, not planets. They do not appear in a real ephemeris. Endpoints accept nodeType of "mean" (smooth mean node, traditional Vedic default) or "true" (osculating node with perturbation corrections) to select which calculation to use.
• Nakshatra count is 27. Abhijit is sometimes treated as a 28th in some schools, but this API uses the standard 27. roxy.vedicAstrology.listNakshatras() returns an array of length 27.
• Retrograde is per-planet, not global. Natal chart planets and Vedic meta include isRetrograde: boolean per planet. KP planet lists use retrograde. Never generate "Mercury retrograde globally" UI copy, check the specific planet in the response.
• Tarot reversals are a product choice. allowReversals: false on a tarot draw means no reversed cards in that draw, period. It is not cosmically meaningful, it is a config flag.
• Angel number lookup works for any positive integer. Digit-root fallback covers non-canonical numbers. Do not generate validation logic that rejects anything other than 111 / 222 / 333.
• Seed-based daily endpoints are DETERMINISTIC per (seed, date) pair. Same seed plus same date returns the same reading. This is by design for push-notification consistency. Do not describe it as "cached" or retry on stale responses.
• Timezone affects Western calculations more than Vedic. Western natal charts must respect DST at the time of birth. Vedic endpoints default to IST (5.5) which is DST-free. Pass the IANA timezone string from the location lookup ("America/New_York", "Asia/Kolkata") directly to chart calls and the server resolves the DST-correct offset for the chart date. Never pass the utcOffset of the city record (the offset in force today) or the clock of the user right now.

Error handling

On a failure error is { error, code, doc_url }. The error field is human-readable (may change wording). The code field is machine-readable (stable, switch on this). The HTTP status and the Retry-After header are on response; retryAfterSeconds(response) reads the wait in seconds. A network failure (DNS, timeout, connection reset) is not an API error: the call throws fetch failed, so use try/catch where that matters.

const { data, error, response } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

if (error) {
  console.error('Status:', response?.status, 'Code:', error.code, 'Message:', error.error);
  return;
}
console.log(data.sign, data.overview);

Every error returns { error, code, doc_url }. Switch on code; error is readable text and may change. Each meaning below says whether and when to retry, and Retry-After carries the wait when the response sends it. Every code is documented at https://roxyapi.com/docs/errors.

Retries

Retries are on by default: a request is resent up to twice after a 429, 500, 502, 503 or 504, or after a connection that was never made (refused or unresolvable host). Pass maxRetries to change the count, or maxRetries: 0 to turn retries off. A read timeout is never retried. The wait follows Retry-After when the response sends it, and a full-jitter backoff otherwise (initialDelayMs 500, maxDelayMs 30000 by default). A Retry-After longer than maxDelayMs, such as the wait for a monthly allowance, is not waited for: the error comes back at once. An abort signal on the call stops any wait. On a persistent failure the total is 1 + maxRetries requests, so 3 by default and exactly 1 with maxRetries: 0.

import { createRoxy, ErrorCodes, retryAfterSeconds } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!, { maxRetries: 4 });

const { data, error, response } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

if (error) {
  if (error.code === ErrorCodes.RateLimitPerMinute || error.code === ErrorCodes.ComputeSaturated) {
    console.warn('retry in', retryAfterSeconds(response), 'seconds');
  } else {
    console.error(response?.status, error.code, error.doc_url);
  }
}

ErrorCodes holds every code as a typed constant (ErrorCodes.RateLimitPerMinute is 'rate_limit_per_minute'), and the ErrorCode type accepts codes added later. retryAfterSeconds(response) returns the Retry-After wait in seconds, or undefined when the response has none.

MCP equivalents

Every method has a matching MCP tool. The remote MCP server per domain is at https://roxyapi.com/mcp/{domain} (Streamable HTTP, no stdio / no self-hosting). Tool names follow {method}_{path_snake_case}, for example:

• POST /astrology/natal-chart -> post_astrology_natal_chart on /mcp/astrology
• GET /astrology/horoscope/{sign}/daily -> get_astrology_horoscope_sign_daily on /mcp/astrology
• POST /vedic-astrology/birth-chart -> post_vedic_astrology_birth_chart on /mcp/vedic-astrology
• POST /tarot/spreads/celtic-cross -> post_tarot_spreads_celtic_cross on /mcp/tarot

Use the SDK for typed TypeScript apps. Use MCP for AI agents (Claude Desktop, Cursor MCP, OpenAI agents) where the agent selects tools based on user intent.

Gotchas

• Geocode first. Any chart, panchang, synastry, compatibility, or natal endpoint needs coordinates. Call roxy.location.searchCities before the chart method.
• Parameters are objects, not positional. Always { path: {...} }, { body: {...} }, or { query: {...} }.
• Do not guess method names. Type roxy.domain. and let autocomplete show them. Method names come from operationId in the OpenAPI spec, not URL paths.
• Do not use raw fetch. The SDK handles auth, base URL, and typed responses.
• Do not expose API keys client-side. Call Roxy from server code only.
• Date format is YYYY-MM-DD, time is HH:MM:SS. Both are strings.
• Western timezone is required and accepts either a decimal (-5 for EST, 5.5 for IST, 0 for UTC) or an IANA string ("America/New_York", "Asia/Kolkata", "UTC"). IANA is resolved to the DST-correct offset for the request date. Vedic endpoints accept an optional timezone that defaults to 5.5 (IST).
• data and error are mutually exclusive. If error is set, data is undefined and vice versa.
• Switch on error.code, not error.error. The message may change; the code is stable.
• A city record has city, province, country, iso2, latitude, longitude, timezone, utcOffset and population. The name is city, never name.
• utcOffset on a city record is the offset in force today. Pass the IANA timezone string to chart calls so the server resolves the offset for the birth date.
• A natal chart planets is a list of objects. Find a body by name: chart.planets.find((p) => p.name === 'Moon').
• In a Vedic chart meta.Moon.rashi is a string and meta.Moon.nakshatra is an object (name, pada, lord). Display meta.Moon?.nakshatra.name.
• A validation_error carries issues, each with path (the dot-separated field, such as time or person1.date), message and code. Loop over them to show every failing field:

  if (error && 'issues' in error) {
    for (const issue of error.issues) console.error(issue.path, issue.message, issue.code);
  }

• sign is matched case-insensitively. Lowercase is canonical.
• Network failures throw. DNS, timeout and connection reset surface as a thrown fetch failed, not as error; wrap calls in try/catch.
• Total requests on a persistent failure = 1 + retries. The default maxRetries of 2 makes 3 requests; maxRetries: 0 makes exactly one.
• List endpoints return a paginated envelope, { total, limit, offset } plus a named array (cities, crystals, hexagrams, symbols), never a bare array. Pass query: { limit } to widen a page; listHexagrams defaults to 20 of 64.

Links

• Full method reference: docs/llms-full.txt (bundled in this package)
• Documentation: https://roxyapi.com/docs
• Interactive API docs: https://roxyapi.com/api-reference
• Pricing and API keys: https://roxyapi.com/pricing
• MCP for AI agents: https://roxyapi.com/docs/mcp
• Templates: https://roxyapi.com/templates
• Source and issues: https://github.com/RoxyAPI/sdk-typescript
• Other SDKs: Python https://pypi.org/project/roxy-sdk/, PHP https://packagist.org/packages/roxyapi/sdk, .NET https://www.nuget.org/packages/RoxyApi.Sdk, Go https://pkg.go.dev/github.com/RoxyAPI/sdk-go, Rust https://crates.io/crates/roxyapi