Paste one block, get a complete app on RoxyAPI. Every prompt on this page is written for a coding agent that has never heard of RoxyAPI and is working inside your repo: it says where the truth lives, how to query it, what to build, and how to prove it works, in that order.
Two ways to skip the prompt entirely. Clone a free MIT template and add your key, or connect Remote MCP so a runtime agent discovers all 258+ tools itself.
For a commercial app, choose a monetization model first. Include the paid offer, access limits and delivery flow in your build brief.
This is the context every prompt below assumes. Paste it once per project, before anything else. It turns "I am not sure RoxyAPI supports that" into a lookup.
You are integrating RoxyAPI, one REST API for astrology, Vedic astrology, forecasting, human design, numerology, tarot and 18+ insight domains on one key. Base URL https://roxyapi.com/api/v2. Auth is the X-API-Key header, read from the ROXY_API_KEY environment variable, sent from server code only.
Where the truth lives, in order:
1. https://roxyapi.com/AGENTS.md. Read it in full before any code. It holds the auth rules, the location-first rule, the SDK for this language, request body shapes, the error contract, field formats and domain gotchas.
2. The docs MCP server at https://roxyapi.com/mcp/docs (Streamable HTTP, no key, one tool: search_docs). Search it before every endpoint, field, SDK method and integration step. No MCP in this tool? Fetch https://roxyapi.com/llms.txt instead.
3. The OpenAPI spec at https://roxyapi.com/api/v2/openapi.json, every domain in one document, the paths exactly as you call them. Query it with jq, never read it whole:
# The whole contract, every domain in one file. Query it with jq; never read it into context.
curl -s https://roxyapi.com/api/v2/openapi.json -o roxyapi.json
# Domains: the first path segment of every operation
jq -r '[.paths | keys[] | split("/")[1]] | unique | join(" ")' roxyapi.json
# Operations in one domain: operationId, method, path, summary
jq -r --arg d astrology '.paths | to_entries[] | select(.key | split("/")[1] == $d) | .key as $p | .value | to_entries[] | "\(.value.operationId) \(.key | ascii_upcase) \($p) \(.value.summary)"' roxyapi.json
# The operation for a task: searches paths, operationIds and summaries
jq -r --arg q 'life path' '.paths | to_entries[] | .key as $p | .value | to_entries[] | select("\($p) \(.value.operationId) \(.value.summary)" | test($q; "i")) | "\(.value.operationId) \(.key | ascii_upcase) \($p) \(.value.summary)"' roxyapi.json
# One operation: params, body fields (required marked), an example body built from the spec, response fields, key types
jq --arg op generateNatalChart '.components.schemas as $s | def d: if type == "object" and has("$ref") then $s[.["$ref"] | split("/") | last] else . end; def t: d | (.type // ([.anyOf[]? | .type] | join("|"))) + (if .enum then " " + (.enum | map(tostring) | join("|")) else "" end); def shape: d | if .type == "array" then "[{\(.items | d | .properties // {} | keys | join(","))}]" elif .properties then "{\(.properties | keys | join(","))}" else t end; .paths | to_entries[] | .key as $p | .value | to_entries[] | select(.value.operationId == $op) | .value as $o | ($o.requestBody.content["application/json"].schema | d) as $b | {call: "\(.key | ascii_upcase) \($p)", keyTypes: $o["x-key-types"], params: [$o.parameters[]? | "\(.in) \(.name)\(if .required then " (required)" else "" end): \(.schema | t)"], body: [($b.required // []) as $r | $b.properties // {} | to_entries[] | .key as $k | "\($k)\(if ($r | index($k)) then " (required)" else "" end): \(.value | t)"], example: ($b.properties // {} | map_values(d | .example)), response: ($o.responses["200"].content["application/json"].schema | d | .properties // {} | map_values(shape))}' roxyapi.json
# One nested field of that operation (body or response), one level down, with descriptions
jq -r --arg op generateNatalChart --arg f planets '.components.schemas as $s | def d: if type == "object" and has("$ref") then $s[.["$ref"] | split("/") | last] else . end; .paths[][] | select(.operationId? == $op) | [.requestBody.content["application/json"].schema, .responses["200"].content["application/json"].schema] | map(d | .properties[$f] // empty) | first | d | (.items // .) | d | .properties // {} | to_entries[] | "\(.key): \(.value | d | .type // "object") \(.value | d | .description // "" | .[0:120])"' roxyapi.json
# Every error code, the value to switch on
jq -r '.info["x-error-codes"][] | "\(.status) \(.code): \(.meaning)"' roxyapi.json
Audit before you write the call:
- Use a field only after the operation line prints it. A name you cannot find does not exist: search again, never guess, never assume a sibling domain names it the same way.
- Send enum values exactly as listed, case included.
- Build the first request from example: every value in it is one the operation accepts.
- keyTypes is the x-key-types extension. ["secret"] means a server-side sk_ key only; absent means either key class.
- Switch on the error code, never on the message text.
- Importing into a tool platform or a code generator? Use that one domain's spec, for example /api/v2/astrology/openapi.json, whose paths are relative to /api/v2/astrology. For reading, always the combined one.
Generate types from the spec for typed languages (npx openapi-typescript for TypeScript). Never type a response by hand.
4. Any docs page serves markdown when .md is appended: https://roxyapi.com/docs/sdk.md, https://roxyapi.com/docs/ui.md, https://roxyapi.com/docs/tutorials/ai-chat-widgets.md.
Rules that do not bend:
- Never say a feature is missing without searching the docs and the spec first. Never guess a path: a 404 on a wrong path returns suggestions, the closest valid ones.
- Every chart, horoscope, panchang, dasha and compatibility call needs latitude, longitude and timezone. Resolve them with GET /location/search?q={city} first and pass its timezone through. Never ask a person for coordinates. If the app already resolves places with its own geocoder, keep it and send its values: latitude and longitude in decimal degrees, and timezone as the IANA name of that place (America/New_York, Europe/London, Asia/Kolkata) rather than a fixed offset, so daylight saving resolves for the birth date. Location stays the default because one call returns all three for 5,180,000+ places, ranked across alternate and historic spellings.
- A 200 is clean JSON with no wrapper. Errors are { error, code, doc_url }, and a 400 carries issues[] with every field problem at once. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
- Add ?lang= for any of en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Machine values stay English; human text translates.
- Render a result with the matching component from @roxyapi/ui-react (or @roxyapi/ui for any other stack) before drawing one yourself: RoxyNatalChart, RoxyVedicKundli, RoxyHoroscopeCard, RoxyTarotSpread, RoxyDashaTimeline, RoxyMoonPhase, RoxyLocationSearch and more. Every component and prop is in the UI agent guide, raw markdown to fetch whole with curl -s: https://raw.githubusercontent.com/RoxyAPI/ui/main/AGENTS.md
- Finish with one real call against the live API using the key, and show the response you received.Get your API key. Instant, one key for every domain. Setup for your own tool (MCP config, rules file, secrets panel) is one page each: Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, Replit, Lovable, Bolt.
| Prompt | What it builds | Endpoints |
|---|---|---|
| Add RoxyAPI to an existing app | One feature inside the codebase you already have, in its stack and conventions | Whatever the feature needs |
| AI Astrology Chatbot (Remote MCP) | A chat app whose model calls live calculations as tools and draws every result | All domains |
| AI Spiritual Companion (memory) | A companion that remembers each user: accounts, stored chart, semantic recall | All domains |
| Astrology Birth Chart App | Birth charts, horoscopes, compatibility, synastry, transits, moon, returns, predictive | 39 endpoints |
| Vedic Astrology (Jyotish) App | Kundli, Navamsa, D2 to D60, Dasha, doshas, Gun Milan, Panchang, Shadbala, KP | 58 endpoints |
| Tarot Reading App | Daily card, Celtic Cross and four more spreads, yes or no oracle, 78 card browser | 10 endpoints |
| Numerology Calculator App | Life Path, full chart, compatibility, Personal Year, karmic analysis | 20 endpoints |
| Dream Journal App | Symbol search, daily symbol, A to Z browser, dream log with pattern tracking | 5 endpoints |
Each prompt repeats the three truth sources in its first lines, so it also works alone. Paste it after the block above and let the agent run.
The prompt most people need. It makes the agent find the right endpoint, respect your stack, keep the key server-side, and prove the call before it stops.
Add RoxyAPI to this project. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, and confirm request and response fields with jq against https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md).
## What I want
{one sentence, for example: a page where a user enters birth date, time and city and sees their Sun, Moon and rising sign with a drawn chart wheel}
## How to work
1. Detect the stack and use its client. TypeScript or JavaScript: npm install @roxyapi/sdk, then read node_modules/@roxyapi/sdk/AGENTS.md; every method is roxy.{domain}.{operationId}. Python: pip install roxy-sdk. PHP: composer require roxyapi/sdk. C#: dotnet add package RoxyApi.Sdk. Go: go get github.com/RoxyAPI/sdk-go. Rust: cargo add roxyapi and cargo fetch, then read its bundled AGENTS.md from the Cargo registry source cache. Anything else: a typed client generated from the domain spec. No hand-rolled fetch when an SDK exists.
2. Pick the endpoint with search_docs, then print its request fields and its 200 response fields from the spec. Tell me the operationId you chose and why before writing code.
3. Add ROXY_API_KEY to the env example. Read it in server code only (server action, API route, edge function). If this app has no server (static site, mobile client), stop and say so: the answer there is a publishable pk_ key locked to the site origin, minted at https://roxyapi.com/account?tab=keys, never an sk_ key in a bundle.
4. Resolve the birthplace with GET /location/search?q={city} and pass its latitude, longitude and timezone through. Confirm ambiguous matches before calculating. Debounce the search 300ms and proxy it through the server.
5. Reuse the form and the API client across features. Follow the conventions already in this repo (router, styling, state, tests).
6. Render with the matching @roxyapi/ui-react component when one exists (curl -s https://raw.githubusercontent.com/RoxyAPI/ui/main/AGENTS.md lists every one). Otherwise a plain table of the fields, no invented copy.
7. Handle { error, code, doc_url }: show validation issues[] beside the form. Follow the chosen SDK documented retry behavior without adding a second retry loop. Show a setup message linking https://roxyapi.com/account?tab=keys when the key is missing.
8. Finish by running one real request with the key and pasting the JSON you got back, then the list of files you changed.A conversational app where the model calls live calculations as tools. Nothing is wired by hand: connect a domain server and its tools appear. The fastest route is the template; the prompt also covers building it into an existing chat app.
Build an AI astrology chatbot on RoxyAPI Remote MCP. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for anything you are unsure of, and read https://roxyapi.com/docs/tutorials/ai-chat-widgets.md for how a tool result becomes a drawn chart.
## Fastest path: the template
git clone https://github.com/RoxyAPI/astrology-ai-chatbot, then follow its README and AGENTS.md. Env: ROXY_API_KEY (the RoxyAPI key), LLM_PROVIDER plus the key for that provider, ROXYAPI_PRODUCTS (comma list of domain slugs to expose). Next.js, TypeScript, Vercel AI SDK, MIT. Customize the system prompt, the palette and the enabled domains, then deploy. Stop here unless I asked for a build inside my own app.
## Building it into this app instead
1. Servers: one Remote MCP server per domain at https://roxyapi.com/mcp/{domain}. Streamable HTTP, POST only, stateless. Not SSE, not WebSocket, no local process. Auth is the X-API-Key header on the transport. Connect from server code only.
2. Client: with the Vercel AI SDK, createMCPClient from @ai-sdk/mcp with a Streamable HTTP transport and that header, then pass the discovered tools to the model. Any other framework: its MCP client with the same URL and header.
3. Start with a few domains, not all. astrology, tarot and location cover most first conversations; every connected tool is a definition in front of the model on every turn. Make the list an env var.
4. Pass compact: true on every tool call. Same data, each field name sent once per array, roughly 40 to 52 percent fewer tokens on a detailed chart.
5. System prompt: the model has real calculation tools and must call them for any chart, transit, card or number. It never invents a placement. It resolves a city through the location tool before any chart tool and never asks for coordinates.
6. Draw every result: componentForTool(toolName) from @roxyapi/ui-react returns the component that renders that tool result, so a card draw arrives as cards and a chart as a wheel. Render it above the prose.
7. Streaming replies, message history, light and dark, mobile first. The RoxyAPI key and the model key never reach the browser.
8. Prove it: run one conversation that asks for a natal chart for a named city and show the tool calls the model made and the drawn result.A companion that remembers each person: accounts, a natal chart computed once and stored, every reading kept, semantic recall over the history. Memory is the premium feature in this category and the template ships the seam for gating it.
Build an AI spiritual companion with per-user memory on RoxyAPI. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for anything you are unsure of, and read https://roxyapi.com/docs/tutorials/ai-chat-widgets.md for how a tool result becomes a drawn chart.
## Fastest path: the template
git clone https://github.com/RoxyAPI/ai-spiritual-companion, then follow its README and AGENTS.md. Next.js, TypeScript, Supabase (magic link auth, four tables under row level security, pgvector for recall), Vercel AI SDK, Remote MCP, MIT. Local run: npx supabase start, npx supabase db reset, copy .env.example to .env.local and fill ROXY_API_KEY, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, LLM_PROVIDER and the key for that provider, then npm run dev. npm run verify is the gate before any push. Customize the voices, the enabled domains (ROXYAPI_MCP_PRODUCTS), the onboarding copy and the palette. Stop here unless I asked for a build inside my own app.
## What makes it a companion, keep all of it
1. Onboarding once: birth date, time and city. City is an autocomplete on GET /location/search that resolves coordinates and the IANA timezone silently.
2. The natal chart is computed exactly once per account with POST /astrology/natal-chart through the typed SDK, stored as JSON, and read from the database afterwards. The natal chart tool is withheld from the model so it cannot recompute it; the chart is in the system prompt every turn.
3. Everything else is Remote MCP: servers at https://roxyapi.com/mcp/{domain}, X-API-Key on the transport, compact: true on every call, a small default domain list widened by env.
4. Every reading the companion shows is appended to a readings table with the calculation it was grounded in. Past turns are embedded and searched by meaning, so asking about a feeling finds the turn where it was first described.
5. Privacy split you can state to users: only birth date, time and coordinates are ever sent to be calculated. Journal entries, moods and conversation text stay in the operator database.
6. Per-user spend limits counted off the readings table, not in memory, so they hold on serverless hosts.
7. Every tool result is drawn with componentForTool from @roxyapi/ui-react; the stored chart is drawn with RoxyNatalChart on its own page.
8. Prove it: create an account locally, complete onboarding for a named city, ask two questions on different days, and show that the second answer recalled the first.Birth charts with the big three, daily to yearly horoscopes, compatibility, synastry, transits, moon phases, returns, relocation, predictive techniques and a zodiac reference. 39 endpoints, all typed from one spec.
Build a complete Western astrology app using Next.js (TypeScript) and the RoxyAPI Astrology API. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, then npm install @roxyapi/sdk and read node_modules/@roxyapi/sdk/AGENTS.md: every call is roxy.{domain}.{operationId} with the response types exported by the package, so never hand-roll fetch and never type a response by hand. Print the request and response fields of each operation with jq from https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md) before you use it.
## API
- Base URL https://roxyapi.com/api/v2/astrology. Auth X-API-Key from env ROXY_API_KEY, server-side only.
- Birth data: { date: "YYYY-MM-DD", time: "HH:MM:SS", latitude, longitude, timezone } where timezone is an IANA name ("America/New_York", preferred, DST-correct) or decimal hours (-5, 5.5). Optional houseSystem (placidus default, whole-sign, equal, koch) and nodeType ("true" default, "mean").
- City search: GET https://roxyapi.com/api/v2/location/search?q={city}, proxied through an API route, debounced 300ms. Never ask for coordinates.
- Errors: { error, code, doc_url }; a 400 carries issues[] per field. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
## Endpoints (39)
Charts: POST /natal-chart, /planets, /houses, /aspects, /aspect-patterns
Horoscopes: GET /horoscope/{sign}/daily, /weekly, /monthly, /yearly (sign lowercase; date and timezone query params for scheduling)
Relationships: POST /compatibility-score, /synastry, /composite-chart
Returns: POST /solar-return, /lunar-return, /planetary-returns
Transits: POST /transits, /transit-aspects
Moon: GET /moon-phase/current, /moon-phase/upcoming, /moon-phase/calendar/{year}/{month}
Place: POST /astrocartography, /relocation-chart, /local-space
Predictive: POST /progressions, /solar-arc, /profections
Points: POST /fixed-stars, /arabic-lots, /asteroids, /lilith
Reference: GET /signs, /signs/{id}, /planet-meanings, /planet-meanings/{id}
Print the rest with jq before you assume anything about their bodies.
## Pages
1. Birth chart: POST /natal-chart. Big three (Sun, Moon, ascendant), all 14 bodies (Sun to Pluto, the nodes, Chiron, Black Moon Lilith) with sign, house, degree, retrograde and the interpretation.summary and interpretation.detailed, the aspects with strength and interpretation, the detected patterns, and summary. Draw the wheel with RoxyNatalChart from @roxyapi/ui-react.
2. Horoscopes: sign picker with daily, weekly, monthly, yearly tabs. Show column, overview, love, career, health, finance, advice, moonSign, moonPhase and activeTransits; yearly adds eclipses, retrogrades and key periods. RoxyHoroscopeCard renders it.
3. Compatibility: POST /compatibility-score with person1 and person2 birth data. Score, category breakdown, strengths, challenges. RoxyCompatibilityCard.
4. Synastry: POST /synastry. Inter-chart aspects with relationship context.
5. Transits: POST /transit-aspects with the natal chart. Each transit with interpretation, impact, timing and guidance.
6. Moon: GET /moon-phase/current today, GET /moon-phase/calendar/{year}/{month} as a calendar. RoxyMoonPhase.
7. Reference: GET /signs and GET /planet-meanings as detail pages.
## Rules
- TypeScript strict, no any. One shared birth form and one shared API client reused by every page. Server actions for every call.
- ?lang= selector across en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.
- Loading states, error states, light and dark, mobile first. A setup screen linking https://roxyapi.com/account?tab=keys when ROXY_API_KEY is missing.
- Prove it: run POST /natal-chart for a named city with the key and paste the big three you received.Kundli (D1), Navamsa (D9), divisional charts D2 to D60, Vimshottari Dasha, Manglik, Kalsarpa and Sadhesati doshas, Gun Milan, Panchang, Choghadiya, Hora, Shadbala, Ashtakavarga, the KP system and transits. 58 endpoints, Hindi included.
Build a complete Vedic astrology (Jyotish) app using Next.js (TypeScript) and the RoxyAPI Vedic Astrology API. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, then npm install @roxyapi/sdk and read node_modules/@roxyapi/sdk/AGENTS.md: every call is roxy.{domain}.{operationId} with the response types exported by the package, so never hand-roll fetch and never type a response by hand. Print the request and response fields of each operation with jq from https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md) before you use it.
## API
- Base URL https://roxyapi.com/api/v2/vedic-astrology. Auth X-API-Key from env ROXY_API_KEY, server-side only.
- Birth data: { date: "YYYY-MM-DD", time: "HH:MM:SS", latitude, longitude, timezone } where timezone is an IANA name ("Asia/Kolkata") or decimal hours (5.5). Lahiri ayanamsa is applied server-side; never subtract it yourself. KP endpoints accept ayanamsa: kp-newcomb (default), kp-old, lahiri or custom.
- City search: GET https://roxyapi.com/api/v2/location/search?q={city}, proxied and debounced. Never ask for coordinates.
- Errors: { error, code, doc_url }; a 400 carries issues[] per field. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
## Endpoints (55)
Charts: POST /birth-chart (a house map keyed by sign name, with rashi, nakshatra, interpretations, combustion, planetary war), /navamsa, /divisional-chart with { division: 2|3|4|7|9|10|12|16|20|24|27|30|40|60 }
Dasha: POST /dasha/current, /dasha/major, /dasha/sub/{mahadasha} (planet name: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu)
Doshas: POST /dosha/manglik, /dosha/kalsarpa, /dosha/sadhesati
Compatibility: POST /compatibility (36 point Ashtakoota Gun Milan, person1 and person2 in the body)
Panchang: POST /panchang/basic, /panchang/detailed (no time field), /panchang/choghadiya, /panchang/hora
Strength: POST /shadbala, /ashtakavarga
Transits: POST /transit, /transit/monthly
Aspects: POST /aspects, /aspects/monthly, /aspects/lunar
KP: POST /kp/chart, /kp/planets, /kp/cusps, /kp/ruling-planets, /kp/sublord-changes and more
Positions: POST /planetary-positions, /planetary-positions/monthly
Reference: GET /yoga, /rashis, /nakshatras
Print the rest with jq before you assume anything about their bodies.
## Pages
1. Kundli: POST /birth-chart. Lagna, nine grahas with rashi, nakshatra, pada, house, interpretation, combustion and planetary war. Draw it with RoxyVedicKundli from @roxyapi/ui-react (North and South Indian styles).
2. Navamsa: POST /navamsa with Vargottama planets highlighted. Divisional charts: POST /divisional-chart with a division picker, RoxyDivisionalChart.
3. Dasha: POST /dasha/major as a timeline (RoxyDashaTimeline), POST /dasha/current for today, POST /dasha/sub/{mahadasha} on expand.
4. Doshas: the three endpoints as cards with present, severity, description, exceptions and remedies. RoxyDoshaCard.
5. Gun Milan: POST /compatibility. 36 point score, eight koota breakdown, dosha detection, recommendation.
6. Panchang: POST /panchang/detailed. Tithi, nakshatra, yoga, karana, sunrise, sunset, Rahu Kaal, Yamaganda, Gulika. RoxyPanchangTable. Choghadiya and Hora as day and night tables.
7. Strength: POST /shadbala with its six components, POST /ashtakavarga for BAV and SAV.
8. Transits: POST /transit over the natal chart, POST /transit/monthly as a sign change calendar.
## Rules
- TypeScript strict, no any. One shared birth form and one shared planet component. Server actions for every call.
- Tabs, never every endpoint on page load: birth chart first, the rest on tab switch.
- ?lang= selector with hi first, then en, tr, de, es, pt, fr, ru, zh-Hans, zh-Hant.
- Loading states, error states, light and dark, mobile first. A setup screen linking https://roxyapi.com/account?tab=keys when ROXY_API_KEY is missing.
- Prove it: run POST /birth-chart for a named Indian city with the key and paste the lagna and Moon nakshatra you received.Daily card, Celtic Cross and four other spreads, a yes or no oracle, custom spreads and a 78 card browser with filtering. 10 endpoints.
Build a complete tarot app using Next.js (TypeScript) and the RoxyAPI Tarot API. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, then npm install @roxyapi/sdk and read node_modules/@roxyapi/sdk/AGENTS.md: every call is roxy.{domain}.{operationId} with the response types exported by the package, so never hand-roll fetch and never type a response by hand. Print the request and response fields of each operation with jq from https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md) before you use it.
## API
- Base URL https://roxyapi.com/api/v2/tarot. Auth X-API-Key from env ROXY_API_KEY, server-side only.
- Errors: { error, code, doc_url }; a 400 carries issues[]. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
- Seeded endpoints are deterministic: same seed and date, same cards. Use that for shareable readings.
## Endpoints (10)
- POST /daily: card of the day with its message
- POST /draw { count: 1..78, seed?, allowReversals?, allowDuplicates? } returns { seed, cards: [...] }
- POST /yes-no: a yes or no reading; the field is interpretation
- POST /spreads/three-card, /spreads/celtic-cross, /spreads/love, /spreads/career: each returns { positions: [{ card, ... }] }, not cards[]
- POST /spreads/custom { spreadName?, question?, positions: [{ name, interpretation }] }
- GET /cards returns { total, cards: [...] }; GET /cards/{id} with kebab-case ids such as fool, ace-of-cups, queen-of-swords
Print request and response fields with jq before you assume anything.
## Pages
1. Daily card: POST /daily. Image (imageUrl), name, keywords, meaning, the daily message. Reversed cards handled.
2. Spreads: one page per spread. Each position shows its name, the card image, the card name and the interpretation for that position. Draw them with RoxyTarotSpread from @roxyapi/ui-react.
3. Yes or no: POST /yes-no. Answer, card, interpretation.
4. Card browser: GET /cards in a grid filtered by arcana and suit; GET /cards/{id} as the detail page.
5. Custom spread builder: users name positions, POST /spreads/custom.
## Rules
- TypeScript strict, no any. Shared API client, shared card component, shared error handling. Server actions for every call.
- ?lang= selector across en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.
- Loading states, error states, light and dark, mobile first, card images in a grid. A setup screen linking https://roxyapi.com/account?tab=keys when ROXY_API_KEY is missing.
- Prove it: run POST /spreads/three-card with the key and paste the three card names you received.Life Path, Expression, Soul Urge, Personality, Birth Day, Maturity, Bridge, the full chart, karmic debt and lessons, compatibility, Personal Year, Month and Day, daily number, Chaldean and business names. 20 endpoints.
Build a complete numerology app using Next.js (TypeScript) and the RoxyAPI Numerology API. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, then npm install @roxyapi/sdk and read node_modules/@roxyapi/sdk/AGENTS.md: every call is roxy.{domain}.{operationId} with the response types exported by the package, so never hand-roll fetch and never type a response by hand. Print the request and response fields of each operation with jq from https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md) before you use it.
## API
- Base URL https://roxyapi.com/api/v2/numerology. Auth X-API-Key from env ROXY_API_KEY, server-side only.
- Dates are separate integers, never a string: POST /life-path takes { year, month, day }. POST /expression takes { fullName } (the birth certificate name). POST /chart takes { fullName, year, month, day }. POST /maturity takes { lifePath, expression } already calculated. POST /personal-year takes { month, day, year? } where year is the target year.
- Errors: { error, code, doc_url }; a 400 carries issues[]. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
## Endpoints (20)
Core: POST /life-path, /expression, /soul-urge, /personality, /birth-day, /maturity, /bridge
Full chart: POST /chart (every core number plus karmic and the personal year in one call; numbers are nested under coreNumbers)
Karmic: POST /karmic-debt, /karmic-lessons
Cycles: POST /personal-year, /personal-month, /personal-day, /daily
Names: POST /chaldean, /dual, /business-name
Compatibility: POST /compatibility
Reference: GET /meanings/{number} (1 to 9, 11, 22, 33), GET /compound-number/{number}
Print request and response fields with jq before you assume anything.
## Pages
1. Life Path: POST /life-path. Number, title, description, strengths, challenges, career, relationships, spirituality, and the calculation steps the API returns.
2. Full chart: POST /chart. Every core number, karmic lessons, karmic debt if any, the Personal Year, the summary narrative. RoxyNumerologyCard from @roxyapi/ui-react per number.
3. Single calculators: one page each for expression, soul urge, personality, birth day, maturity.
4. Compatibility: POST /compatibility with two names and two birth dates.
5. Cycles: POST /daily for today, POST /personal-year with theme, opportunities, challenges.
6. Reference: GET /meanings/{number} for 1 to 9 and the masters 11, 22, 33.
## Rules
- TypeScript strict, no any. One shared name and birth date form reused everywhere. Server actions for every call.
- ?lang= selector across en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.
- Show calculation breakdowns wherever the API returns them. Loading states, error states, light and dark, mobile first. A setup screen linking https://roxyapi.com/account?tab=keys when ROXY_API_KEY is missing.
- Prove it: run POST /chart with the key and paste the Life Path and Expression numbers you received.A 2,200+ symbol dictionary with search, a daily symbol, an A to Z browser, random discovery and a local dream log that tracks recurring symbols. 5 endpoints.
Build a dream journal app using Next.js (TypeScript) and the RoxyAPI Dreams API. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for every endpoint and field, then npm install @roxyapi/sdk and read node_modules/@roxyapi/sdk/AGENTS.md: every call is roxy.{domain}.{operationId} with the response types exported by the package, so never hand-roll fetch and never type a response by hand. Print the request and response fields of each operation with jq from https://roxyapi.com/api/v2/openapi.json (the recipe is in AGENTS.md) before you use it.
## API
- Base URL https://roxyapi.com/api/v2/dreams. Auth X-API-Key from env ROXY_API_KEY, server-side only.
- Errors: { error, code, doc_url }; a 400 carries issues[]. Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
## Endpoints (5)
- GET /symbols?q={query}&letter=&limit=&offset= returns { total, limit, offset, symbols: [...] }
- GET /symbols/{id} with a kebab-case slug such as flying, water, snake, falling
- GET /symbols/letters for the alphabetical index
- GET /symbols/random
- POST /daily for the symbol of the day with its interpretation
Print request and response fields with jq before you assume anything.
## Pages
1. Dream entry: a text area, then a search for every symbol the text mentions.
2. Symbol search: GET /symbols?q= debounced 300ms, results from the full dictionary.
3. Symbol detail: GET /symbols/{id}. Meaning, category, related symbols.
4. Browse A to Z: GET /symbols/letters. Daily symbol: POST /daily. Random: GET /symbols/random.
5. Dream log: saved in localStorage with date, text and matched symbols. Recurring symbols surfaced over time.
## Rules
- TypeScript strict, no any. Server actions for every call, localStorage for the log.
- ?lang= selector across en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.
- Debounced search, loading states, error states, light and dark, mobile first. A setup screen linking https://roxyapi.com/account?tab=keys when ROXY_API_KEY is missing.
- Prove it: run GET /symbols?q=water with the key and paste the first three symbol names you received.The order matters more than the words. An agent reads top down and acts on the first thing it can act on.
Hi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.