Tarot API Integration: 78-Card Deck for Your App

Tarot is one of the most engaging features you can add to a wellness, spirituality, or entertainment app. Whether you are building a daily reflection tool, a fortune-telling game, or a journaling platform that pairs cards with horoscopes, a reliable tarot card API gives you the full 78-card Rider-Waite-Smith deck with structured meanings — no image licensing headaches and no hand-curated lookup tables. This guide walks through the GitStrology tarot API end to end: the deck structure, the spreads, the JSON response shape, and a complete daily-tarot feature you can ship in an afternoon.

Understanding the 78-Card Tarot Deck

A standard tarot deck contains 78 cards divided into two main groups: the Major Arcana and the Minor Arcana. The word “arcana” means secrets or mysteries, and together these two groups tell a complete symbolic story.

The 22 Major Arcana

The Major Arcana consists of 22 trump cards, numbered 0 through 21. These are the archetype cards — The Fool, The Magician, The High Priestess, The Empress, The Emperor, The Hierophant, The Lovers, The Chariot, Strength, The Hermit, Wheel of Fortune, Justice, The Hanged Man, Death, Temperance, The Devil, The Tower, The Star, The Moon, The Sun, Judgement, and The World. They represent major life themes and turning points. In a reading, a Major Arcana card carries more narrative weight than a Minor Arcana card.

The 56 Minor Arcana

The Minor Arcana consists of 56 cards divided into four suits of 14 cards each. Each suit runs Ace through 10, plus four court cards: Page, Knight, Queen, and King. The four suits are:

• Wands 🪄 — fire, passion, creativity, action, ambition
• Cups 🏆 — water, emotion, relationships, intuition
• Swords ⚔️ — air, intellect, conflict, communication
• Pentacles 🪙 — earth, money, work, the material world

The Minor Arcana reflects day-to-day life and smaller-scale events. Together, the 22 Major and 56 Minor cards give you a rich vocabulary of 78 distinct symbols to draw from.

The GitStrology Tarot API Endpoint

The tarot API exposes a single REST endpoint with a spread query parameter that controls how many cards are drawn and how they are interpreted:

GET https://api.gitstrology.dev/v1/tarot?spread={single|three|celtic}

The three supported spreads are:

• spread=single — draws 1 card. Perfect for a daily draw or a quick “card of the moment.”
• spread=three — draws 3 cards in a past, present, and future layout.
• spread=celtic — draws 10 cards in the classic Celtic Cross spread, one of the most detailed and widely used tarot spreads.

Each draw costs 3 credits regardless of spread size, so a single-card draw and a full 10-card Celtic Cross both cost the same. See the tarot endpoint reference for the full parameter list. If you are new to the API, start with the quickstart guide to grab an API key.

Making Your First Tarot Request

Authenticate with the X-API-Key header and request a single-card draw:

curl "https://api.gitstrology.dev/v1/tarot?spread=single" \
  -H "X-API-Key: gs_live_xxxxx"

The response returns a structured card object wrapped in the standard GitStrology envelope. Every card includes its upright meaning and a separate reversed meaning, along with a boolean indicating whether the card was drawn reversed:

{
  "data": {
    "cards": [
      {
        "name": "The Star",
        "number": 17,
        "suit": null,
        "arcana": "major",
        "meaning": "Hope, renewed faith, inspiration, a guiding light after darkness.",
        "reversed": false,
        "reversedMeaning": "Despair, lost faith, disconnection from inner truth."
      }
    ],
    "spread": "single"
  },
  "credits": { "used": 3, "remaining": 97 }
}

The cards array always reflects the spread size: one element for single, three for three, and ten for celtic. Major Arcana cards have a suit of null, while Minor Arcana cards return the suit name ("wands", "cups", "swords", or "pentacles"). The credits object tells you exactly how many credits the call consumed and your remaining monthly balance.

Using the SDK

The official TypeScript SDK provides a gs.tarot() method that wraps the endpoint. By default it performs a single-card draw:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY });

// Returns a single-card draw by default
const draw = await gs.tarot();

const card = draw.data.cards[0];
console.log(card.name);        // "The Star"
console.log(card.arcana);      // "major"
console.log(card.reversed);    // false
console.log(card.meaning);     // upright interpretation
console.log(draw.credits.remaining); // 97

Note that gs.tarot() returns a single draw — one card by default. To request a larger spread, pass the spread option:

// Three-card past / present / future reading
const three = await gs.tarot({ spread: "three" });

// Full 10-card Celtic Cross
const celtic = await gs.tarot({ spread: "celtic" });

celtic.data.cards.forEach((card, i) => {
  console.log(${i + 1}., card.name, card.reversed ? "(reversed)" : "");
});

Building a Daily Tarot Feature

A daily tarot draw is a compelling retention mechanic. Users return each day for a fresh card and its reflection prompt. Here is a complete example that fetches a single card, maps the suit to an emoji, and renders a daily reading:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY! });

const SUIT_EMOJI: Record<string, string> = {
  wands: "🪄",
  cups: "🏆",
  swords: "⚔️",
  pentacles: "🪙",
};

async function dailyTarot() {
  const draw = await gs.tarot();
  const card = draw.data.cards[0];

  const emoji = card.suit
    ? SUIT_EMOJI[card.suit]
    : "✨"; // Major Arcana

  const orientation = card.reversed ? "Reversed" : "Upright";
  const meaning = card.reversed
    ? card.reversedMeaning
    : card.meaning;

  return {
    title: `${emoji} ${card.name} (${orientation})`,
    reflection: meaning,
    creditsLeft: draw.credits.remaining,
  };
}

const today = await dailyTarot();
console.log(today.title);
// "✨ The Star (Upright)"
console.log(today.reflection);
// "Hope, renewed faith, inspiration..."

Displaying Card Images

The API returns card names, numbers, and meanings as structured data but does not bundle copyrighted card artwork. For production apps you have two clean options. First, use the suit emojis (🪄 🏆 ⚔️ 🪙) plus a Major Arcana glyph (✨) for a lightweight, license-free visual treatment that works in push notifications and compact UI. Second, commission or generate your own card art keyed on the card name field, which is stable and unique across the deck. Avoid scraping Rider-Waite-Smith images from the web — the original artwork is in the public domain in many jurisdictions, but specific photographic reproductions may carry their own copyright.

Three-Card and Celtic Cross Layouts

For richer experiences, the three and celtic spreads return positional cards. The three-card spread maps cleanly to past, present, and future:

const reading = await gs.tarot({ spread: "three" });

const [past, present, future] = reading.data.cards;

console.log("Past:   ", past.name);
console.log("Present:", present.name);
console.log("Future: ", future.name);

The Celtic Cross returns ten cards, each in a named position (the heart of the matter, what crosses you, the foundation, the recent past, the possible outcome, and so on). Refer to the tarot docs for the positional labels attached to each index in a Celtic Cross draw. Each card in any spread can appear upright or reversed, and the reversedMeaning field ensures you always have the correct interpretation without writing your own flip logic.

Combining Tarot with Horoscopes

Tarot pairs naturally with other GitStrology endpoints. A common pattern is to show a user their sun-sign horoscope alongside a daily tarot card, giving users two complementary lenses on their day. Because the horoscope endpoint costs 1 credit and the tarot draw costs 3, a combined “daily digest” costs 4 credits per user per day. On the Pro plan (10,000 credits/month), that covers roughly 2,500 daily digest lookups — enough for a small but active user base. See the rate limits and credits page for the full cost table across plans.

Caching and Credit Strategy

Tarot draws are randomized, so they do not cache as cleanly as deterministic endpoints like moon phase. However, for a daily feature you only need one draw per user per day. Cache the result on your side (in a database, Redis, or even a signed cookie) and reuse it for the rest of the 24-hour window. This keeps your credit spend predictable: one 3-credit draw per active user per day, regardless of how many times they reopen the app.

Handling Reversed Cards in the UI

Roughly half of all draws will come back reversed — the reversed boolean is true whenever the card was flipped upside-down in the spread. Reversed cards carry the reversedMeaning instead of the upright meaning, and they often signal blocked energy, internal conflict, or the shadow side of the archetype. Your UI should make the orientation visually obvious so users understand why the interpretation shifts. A common treatment is to rotate the card image 180 degrees when reversed is true, and to prepend “Reversed:” to the displayed meaning text. Because the API returns both interpretations for every card, you never have to write your own reversal logic — just branch on the boolean:

const interpretation = card.reversed
  ? card.reversedMeaning
  : card.meaning;

const rotation = card.reversed ? "rotate-180" : "";
// <CardImage className={rotation} />

Error and Empty States

Production tarot features should handle the cases where the API is unreachable or a user has run out of credits. A graceful fallback is to show yesterday's cached draw with a note that today's card will refresh shortly, rather than a blank screen. Pair this with the credits.remaining field from the response envelope to surface a low-balance warning before a hard failure. For a full guide to error codes and credit handling, see our authentication and rate limits guide.

Key Takeaways

• A tarot deck has 78 cards: 22 Major Arcana (numbered 0–21) and 56 Minor Arcana across four suits — Wands 🪄, Cups 🏆, Swords ⚔️, and Pentacles 🪙 — each with Ace through 10 plus Page, Knight, Queen, and King.
• The GitStrology tarot endpoint is GET /v1/tarot?spread=single|three|celtic, returning 1, 3, or 10 cards respectively.
• Every card includes name, number, suit, arcana, meaning, a reversed boolean, and reversedMeaning.
• The SDK method gs.tarot() returns a single-card draw by default; pass { spread: 'three' } or { spread: 'celtic' } for larger spreads.
• Each draw costs 3 credits, regardless of spread size.
• Cache daily draws on your side to keep credit spend predictable — one 3-credit draw per active user per day.
• Get started with the quickstart guide, reference the full tarot endpoint docs, and review the pricing plans to pick the right credit tier.

Ready to add tarot to your app? Grab your API key from the dashboard, follow the quickstart, and draw your first card today.