Tarot API, what to build and how to call it

Ship a daily tarot widget, a yes-no oracle, or a full Celtic Cross reader in under 20 minutes. Card imagery included.

Tarot is the highest-frequency divination surface Roxy ships. /tarot/cards is the highest per-endpoint call count in the catalog because every tarot app fetches the deck once and caches it. The daily card drives notifications, the three-card spread is the entry reading, Celtic Cross is the premium upsell, and yes-no is the highest-converting micro-feature on any tarot surface.

What you can build

Daily-draw tarot widgets for wellness and lifestyle apps
Yes-no impulse features for dating and decision apps
Full Celtic Cross reading apps with 10-position layouts
Tarot chatbots that pick the right spread per question
Card browsers with upright and reversed meanings

Prerequisites

A Roxy API key. Get one on the pricing page.
A seed string if you want deterministic per-user results.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the endpoint

The #1 tarot call is the daily card. Seed it with a user ID and the same user gets the same card all day long (great for push notifications). Pick a language.

curl -X POST https://roxyapi.com/api/v2/tarot/daily \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "user-42"}'

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

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.tarot.getDailyCard({
  body: { seed: 'user-42' },
});

console.log(data.card.name);     // "The Star"
console.log(data.card.imageUrl);
console.log(data.dailyMessage);

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

card = roxy.tarot.get_daily_card(seed='user-42')
print(card['card']['name'])
print(card['card']['imageUrl'])
print(card['dailyMessage'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$card = $roxy->tarot->getDailyCard(seed: 'user-42');
echo $card['card']['name'];
echo $card['card']['imageUrl'];
echo $card['dailyMessage'];

claude mcp add-json --scope user roxy-tarot '{"type":"http","url":"https://roxyapi.com/mcp/tarot","headers":{"X-API-Key":"YOUR_KEY"}}'

Then ask Claude, "draw a daily tarot card for user 42." The agent returns the card name, keywords, and interpretation. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: MCP guide.

The response:

{
  "date": "2026-04-23",
  "seed": "user-42",
  "card": {
    "id": "the-star",
    "name": "The Star",
    "arcana": "major",
    "number": 17,
    "position": "upright",
    "reversed": false,
    "keywords": ["Hope", "faith", "renewal"],
    "meaning": "A welcome reprieve after upheaval.",
    "imageUrl": "https://roxyapi.com/img/tarot/major/star.jpg"
  },
  "dailyMessage": "Your card for today, The Star..."
}

Render the result

Skip building the render layer: RoxyTarotCard from @roxyapi/ui renders the imagery, name, daily message, keywords, and a click-to-flip between upright and reversed. Fetch on your server so the key never reaches the browser, then pass the unwrapped data to the component. Prefer your own design? The response is plain JSON, render it however you like.

'use client';
import { RoxyTarotCard } from '@roxyapi/ui-react';
import type { PostTarotDailyResponse } from '@roxyapi/sdk';

export function DailyCard({ data }: { data: PostTarotDailyResponse }) {
  return <RoxyTarotCard data={data} />;
}

The data you pass is the unwrapped SDK response, not the full { data, error } envelope. For multi-card readings, use RoxyTarotSpread instead (see below).

Ship the rest

Three-card spread, the entry reading

POST /tarot/spreads/three-card returns past, present, future with per-position interpretation plus a top-level summary.

curl -X POST https://roxyapi.com/api/v2/tarot/spreads/three-card \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What should I focus on this month?"}'

Render any spread with RoxyTarotSpread from @roxyapi/ui. It lays out the positions, card imagery, per-position interpretation, and the top-level summary. Set the spread prop to match the endpoint (three-card, celtic-cross, love, yes-no, or draw).

'use client';
import { RoxyTarotSpread } from '@roxyapi/ui-react';
import type { PostTarotSpreadsThreeCardResponse } from '@roxyapi/sdk';

export function ThreeCardSpread({ data }: { data: PostTarotSpreadsThreeCardResponse }) {
  return <RoxyTarotSpread data={data} spread="three-card" />;
}

Celtic Cross, the premium reading

POST /tarot/spreads/celtic-cross returns 10 positions (significator, cross, foundation, past, possible, near future, self, environment, hopes and fears, final outcome) with interpretation per position and a synthesized summary. This is the professional-reader spread.

Yes-no, the highest-converting impulse feature

POST /tarot/yes-no returns Yes, No, or Maybe with a strength indicator, the supporting card, and interpretation. Zero-config, highest conversion-to-first-call on any tarot surface.

Love spread, the couples app bolt-on

POST /tarot/spreads/love returns a relationship-focused spread with positions and a top-level summary.

Custom draws

POST /tarot/draw takes count (1 to 78), optional seed, optional allowReversals (default true), optional allowDuplicates (default false). Every custom spread builds on this.

The full 78-card catalog

GET /tarot/cards returns the deck summary. GET /tarot/cards/{id} returns the full card detail with upright, reversed, keywords, imagery, and meanings by life area. Fetch the catalog once, cache it, show card browsers without round-trips.

See the full list at the Tarot API reference.

Ready-made starter

The /starters/tarot-starter-app starter ships a working Tarot app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, drop in <roxy-tarot-spread> from @roxyapi/ui.

Gotchas

allowReversals: false means no reversed cards, period. It is a config flag, not a cosmic statement. Same with allowDuplicates.
Seed plus date is deterministic. Same (seed, date) always returns the same card. This is by design for push-notification consistency. Do not describe it as "cached" or retry when the response looks familiar.
The response has dailyMessage, not interpretation at the top level. Dig into card.meaning for the card-level meaning.
Card IDs are kebab-case. the-star, three-of-wands, knight-of-cups. Use these in /tarot/cards/{id}.
Image URLs are absolute. imageUrl is the full CDN URL, no prefixing needed.

What to build next

The tarot reading app tutorial builds a daily-card plus three-card-spread app in 30 minutes. For conversational tarot, the AI chatbot tutorial shows MCP wiring. For typed calls, the SDK guide covers all spreads.