Tarot API guide

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

Tarot is the highest-frequency divination surface RoxyAPI 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

1. A RoxyAPI key. Get your API key.
2. A seed string if you want deterministic per-user results.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package 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, error } = await roxy.tarot.getDailyCard({
  body: { seed: 'user-42' },
});
if (error) throw error;

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'];

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var card = await roxy.Tarot.Daily.PostAsync(new() { Seed = "user-42" });

Console.WriteLine(card!.Card!.Name);
Console.WriteLine(card.Card.ImageUrl);
Console.WriteLine(card.DailyMessage);

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

The response:

{
  "date": "2026-04-23",
  "seed": "user-42",
  "card": {
    "id": "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 template

The /templates/tarot-starter-app template ships a working Tarot app you can clone, white-label, and deploy. 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. Without a seed, every caller gets one shared card of the day, so seed with a user ID to give each user their own. 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, and Major Arcana IDs carry no leading article. star, fool, three-of-wands, knight-of-cups. Casing, separators and a leading article are all flexible on input, so Fool, THE_STAR and the-star resolve too, but responses always echo the canonical form. Not numeric like major-01.
• 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. For conversational tarot, the AI chatbot tutorial shows MCP wiring. For typed calls, the SDK guide covers all spreads.