You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: sync README and AGENTS with canonical domain order
Reorder domains to Western, Vedic, Numerology, Tarot, Biorhythm,
I Ching, Crystals, Dreams, Angel Numbers, Location, Usage. Add
Location-first rule for any coordinate dependent endpoint.
AGENTS gains a Field formats that trip agents table covering
timezone decimal hours (5.5 IST, 5.75 NPT), date and time formats,
latitude longitude decimals, enum values, slugs, and nested person
objects. Timezone cheat sheet covers 24 regions with DST offsets.
Common tasks table reordered by domain priority. MCP equivalents
section added linking REST paths to per domain MCP tools.
`createRoxy` sets the base URL (`https://roxyapi.com/api/v2`) and auth header automatically. Every method returns `{ data, error, response }`.
20
20
21
+
## Critical rule: geocode before any chart endpoint
22
+
23
+
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.
|`roxy.vedicAstrology`| 42 | Vedic / Jyotish: kundli, panchang, Vimshottari dasha, nakshatras, Mangal and Kaal Sarp and Sade Sati doshas, Guna Milan, navamsa, KP chart and ruling planets|
39
+
|`roxy.numerology`|16|Life path, expression, soul urge, personal year, full chart, compatibility, karmic lessons|
40
+
|`roxy.tarot`|10|Daily card, custom draws, three-card, Celtic Cross, yes / no, love spread, 78-card catalog|
### Multi-language responses via `query: { lang }`
91
+
### Multi-language via `query: { lang }`
92
92
93
-
Interpretations are available in 8 languages: `en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`. Pass `lang` as a query param on any supported endpoint. Defaults to `en`.
Supported: `astrology`, `vedicAstrology`, `tarot`, `numerology`, `crystals`, `iching`, `angelNumbers`, `biorhythm`. Not supported (English-only): `dreams`, `location`, `usage`. Languages without translations yet fall back to English.
All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, safe to switch on).
107
+
All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, switch on this).
|`longitude`| Decimal degrees (number) |`77.209` (Delhi), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
185
+
|`sign` (horoscope path) | Lowercase zodiac name |`aries`, `taurus`, `gemini`, ... `pisces`|`"Aries"`, `"♈"`, `"1"`, `"ARIES"` (case-insensitive but prefer lowercase) |
186
+
|`fullName` (numerology) | Birth-certificate name |`"John William Smith"`, `"Priya Rajesh Sharma"`| Nickname, married name, partial name - affects all letter-based calcs |
187
+
|`seed`| Any string (deterministic) |`"user-42"`, `"session-abc-123"`, email hash | Numbers, objects - must be string |
|`person1` / `person2`| Object with full birth data |`{ date, time, latitude, longitude, timezone }` (Western) or `{ date, time, latitude, longitude }` (Vedic) | Separate top-level fields, missing time, partial object |
196
+
|`question` (tarot / iching) | Optional string |`"Should I accept the job offer?"`, `"What should I focus on this week?"`| Leave undefined for general reading. More specific = better interpretation. |
| Los Angeles (PST / PDT) |`-8` / `-7`| Honolulu |`-10`|
214
+
215
+
DST matters. If the birth date falls inside a daylight-saving window, use the summer / DST offset. For Vedic endpoints this is rarely an issue (most users are in India, fixed 5.5), but Western natal charts must respect DST at the time of birth.
216
+
217
+
## MCP equivalents
218
+
219
+
Every method has a matching MCP tool. The MCP server per domain is at `https://roxyapi.com/mcp/{domain}-api`. Tool names follow `{method}_{path_snake_case}`, for example:
220
+
221
+
-`POST /astrology/natal-chart` -> `post_astrology_natal_chart` on `/mcp/astrology-api`
222
+
-`GET /astrology/horoscope/{sign}/daily` -> `get_astrology_horoscope_sign_daily` on `/mcp/astrology-api`
223
+
-`POST /vedic-astrology/birth-chart` -> `post_vedic_astrology_birth_chart` on `/mcp/vedic-astrology-api`
224
+
-`POST /tarot/spreads/celtic-cross` -> `post_tarot_spreads_celtic_cross` on `/mcp/tarot-api`
225
+
226
+
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.
173
227
174
228
## Gotchas
175
229
176
-
-**Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }` — never positional arguments.
177
-
-**Do not guess method names.** Type `roxy.domain.` and let autocomplete show available methods. Method names come from `operationId` in the OpenAPI spec, not URL paths.
178
-
-**Do not use raw `fetch`.** The SDK handles auth headers, base URL, and typed responses.
230
+
-**Geocode first.** Any chart, panchang, synastry, compatibility, or natal endpoint needs coordinates. Call `roxy.location.searchCities` before the chart method.
231
+
-**Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }`.
232
+
-**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.
233
+
-**Do not use raw `fetch`.** The SDK handles auth, base URL, and typed responses.
179
234
-**Do not expose API keys client-side.** Call Roxy from server code, API routes, or server components only.
180
-
-**Chart endpoints need coordinates.** Use `roxy.location.searchCities()` to get latitude/longitude before calling any birth chart or panchang method.
181
-
-**Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings. Timezone is optional (IANA format like `America/New_York`).
182
-
-**All list endpoints may return paginated objects** (e.g. `{ items: [...], total: N }`) rather than raw arrays. Check the type.
235
+
-**Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings.
236
+
-**Western `timezone` is required** (decimal hours, `-5` for EST, `5.5` for IST, `0` for UTC). Vedic endpoints accept an optional `timezone` that defaults to `5.5` (IST).
183
237
-**`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
184
-
-**Errors have `error` (message) and `code` (machine-readable).** Switch on `code`, not `error` — the message may change wording.
238
+
-**Switch on `error.code`, not `error.error`.** The message may change; the code is stable.
239
+
-**List endpoints may return paginated objects** (`{ items, total }`) instead of raw arrays. Check the type.
185
240
186
241
## Links
187
242
188
243
- Full method reference: `docs/llms-full.txt` (bundled in this package)
189
244
- Interactive API docs: https://roxyapi.com/api-reference
190
245
- Pricing and API keys: https://roxyapi.com/pricing
0 commit comments