Building a tarot reading feature with an API

To build a tarot reading feature with the Vedika API, you call a single family of REST endpoints under /v2/tarot: a card database for lookups, a set of named spread endpoints (single card, three-card, Celtic Cross, yes/no, love, career and more), and an interpretation layer that returns position-aware meanings. You send a question, the API draws and orients the cards, and returns structured JSON your front end renders into a reading. A deterministic seed lets you reproduce the exact same draw, which matters for saved readings and tests.

This guide covers the endpoints, request and response shapes, a working integration in cURL and JavaScript, deterministic draws, and how to fuse a tarot reading with a real birth chart from the same API. You can try every call against the free sandbox before you provision a key.

What the tarot API gives you

Tarot in the Vedika API is one domain among 700+ operations across 25 domains. The tarot family alone exposes 25 endpoints split into a reference layer and a reading layer:

• Card database (GET): the 78-card deck — 22 Major Arcana and 56 Minor Arcana — plus lookups by suit, by element, by zodiac sign, a single card by name, and a daily card.
• Spread readings (POST): named spreads that draw and orient cards for a question — single card, three-card past/present/future, the ten-card Celtic Cross, yes/no, love, career, relationship, weekly, monthly, chakra, decision, and a custom count.
• Interpretation: each drawn card comes back with its upright or reversed meaning, keywords, suit, and element, plus a position label so your UI knows what each card represents in the spread.

No birth data is required for a pure tarot reading — you only need a question. That keeps the integration light: no geocoding, no timezone handling, no ephemeris call unless you choose to add astrological context.

Authentication and pricing

All tarot endpoints are authenticated and metered per call. Send your key as a header:

x-api-key: vk_live_your_key_here

Each tarot operation is priced individually and billed per request, in the same low per-call band as the rest of the V2 surface — a single-card draw and a Celtic Cross sit at different points because they do different amounts of work. The cost is returned on every response so you can reconcile it. Your monthly plan is a wallet of credits that these calls draw down:

Per-query usage runs roughly $0.01–$0.05 depending on the operation; the full breakdown is on the pricing page. There is no free tier on live keys, but the sandbox is free and needs no key, so you can build and demo the entire feature before you pay anything.

The card database endpoints

Start by pulling reference data so your UI can render the deck, card art labels, and meanings without a reading. These are GET calls with no body:

# All 22 Major Arcana
curl https://api.vedika.io/v2/tarot/cards/major-arcana \
  -H "x-api-key: vk_live_your_key_here"

# A single card by name
curl https://api.vedika.io/v2/tarot/card/The%20Tower \
  -H "x-api-key: vk_live_your_key_here"

# The day's card
curl https://api.vedika.io/v2/tarot/card-of-the-day \
  -H "x-api-key: vk_live_your_key_here"

Other reference routes filter the deck: /v2/tarot/cards/minor-arcana, /v2/tarot/cards/suit/:suit (wands, cups, swords, pentacles), /v2/tarot/element/:element, /v2/tarot/zodiac/:sign, and /v2/tarot/spreads. Each card object carries an id, name, arcana, suit, element, keywords, and both upright and reversed meanings — enough to drive a card-detail view entirely from the API.

Drawing a spread

A reading is a POST with a JSON body. The minimum is a question; you may optionally pass a seed for a reproducible draw. The three-card spread is the most common starting point:

curl -X POST https://api.vedika.io/v2/tarot/draw/three-card \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "How will my new job unfold?"}'

The response is structured around the spread's positions. A trimmed three-card reading looks like this:

{
  "success": true,
  "data": {
    "system": "tarot",
    "reading": {
      "spread": { "id": "three-card", "name": "Past / Present / Future", "cardCount": 3 },
      "question": "How will my new job unfold?",
      "cards": [
        {
          "position": { "index": 0, "name": "Past", "meaning": "What led here" },
          "card": { "name": "Eight of Pentacles", "arcana": "minor", "suit": "pentacles",
                    "element": "earth", "keywords": ["diligence", "skill", "craft"] },
          "isReversed": false,
          "interpretation": "Steady effort and learning have built your foundation."
        }
        /* + Present and Future positions */
      ],
      "summary": "A reading built on focused work and emerging mastery.",
      "timestamp": "2026-06-20T09:14:00.000Z"
    }
  },
  "billing": { "charged": 0.005, "currency": "USD" }
}

Every drawn card returns its position (so your UI labels it correctly), the card object, whether it's isReversed, and the position-appropriate interpretation. The summary stitches the cards into a short narrative you can show above the spread.

Choosing a spread

Swap the path segment to change the spread. All of these accept the same { question, seed } body:

The yes/no endpoint adds an answer and a confidence value so you can render a clear verdict. The compatibility endpoint takes personA and personB and returns a card for each plus a connection card and an element-harmony flag.

A full integration in JavaScript

Here is a self-contained reading function. It uses a generic fetch wrapper so you can drop it into any backend; never call a paid endpoint with your key directly from the browser — proxy it through your own server.

const VEDIKA_BASE = "https://api.vedika.io";
const API_KEY = process.env.VEDIKA_API_KEY; // vk_live_*

async function drawTarot(spread, question, seed) {
  const res = await fetch(`${VEDIKA_BASE}/v2/tarot/draw/${spread}`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(seed ? { question, seed } : { question })
  });

  if (res.status === 402) {
    throw new Error("Wallet balance too low — top up to continue.");
  }
  if (!res.ok) {
    throw new Error(`Tarot API error: ${res.status}`);
  }

  const { data, billing } = await res.json();
  return {
    cards: data.reading.cards.map(c => ({
      position: c.position.name,
      name: c.card.name,
      reversed: c.isReversed,
      meaning: c.interpretation,
      keywords: c.card.keywords
    })),
    summary: data.reading.summary,
    cost: billing.charged
  };
}

// usage
const reading = await drawTarot("three-card", "What should I focus on this month?");
console.log(reading.summary);

Handle 402 explicitly — that is the wallet-empty signal — and read the billing.charged field to track spend per reading. The same pattern works in Python:

import os, requests

def draw_tarot(spread, question, seed=None):
    body = {"question": question}
    if seed:
        body["seed"] = seed
    r = requests.post(
        f"https://api.vedika.io/v2/tarot/draw/{spread}",
        headers={"x-api-key": os.environ["VEDIKA_API_KEY"]},
        json=body,
    )
    r.raise_for_status()
    return r.json()["data"]["reading"]

reading = draw_tarot("celtic-cross", "How do I approach this career change?")
print(reading["summary"])

Deterministic draws with a seed

By default each draw is random. Pass a seed string and the same seed always produces the same cards in the same orientations. This is the single most useful detail for building a real feature:

• Saved readings: store the seed, not the full card list, and re-derive the exact reading on demand.
• One-reading-per-day: seed with userId + date so a user's card of the day is stable until midnight.
• Tests: assert against a fixed seed so your snapshot of a reading never flakes.

curl -X POST https://api.vedika.io/v2/tarot/draw/single \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "Focus for today", "seed": "user_4821-2026-06-20"}'

Run that twice and you get an identical card. Drop the seed and you get a fresh pull each time.

Fusing tarot with a real birth chart

The reason to build tarot on an astrology API rather than a standalone deck library is that the same key unlocks real chart computation. Tarot is one of three systems plus several others the API serves — Vedic (sidereal), Western (tropical), and KP, alongside Jaimini, Tajaka, Lal Kitab and numerology. You can pull a card spread and a natal chart together for a richer reading.

The chart side runs on the XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, published to crates.io, PyPI and npm). It is validated against JPL DE440 and swetest reference data, with positions agreeing to well within a tenth of a degree across a large test corpus — astronomical precision for where the planets are, distinct from any interpretive claim about a reading.

A simple fusion: draw a spread, then ask the main AI endpoint to read it in the context of the chart.

# 1. Draw cards (deterministic for the user)
curl -X POST https://api.vedika.io/v2/tarot/draw/three-card \
  -H "x-api-key: vk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{"question": "Career direction this year", "seed": "u4821-2026"}'

# 2. Ask the chart-aware AI to weave it together
curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{
    "question": "Read these tarot cards alongside my chart for career direction.",
    "birthDetails": {
      "datetime": "1994-03-12T07:45:00",
      "latitude": 19.076, "longitude": 72.8777, "timezone": "Asia/Kolkata"
    }
  }'

There is also a convenience route, /v2/tarot/astro-fusion, that seeds a draw from a date of birth and attaches an astrological context note, giving you a starting overlay without a second call. For anything narrative, route the result through Vedika AI, which grounds its interpretation rather than free-associating.

Grounding and citations

The card meanings in the responses follow the standard upright and reversed significations of the Rider–Waite–Smith tradition. When a reading is fused with astrological context, any astrological claim in the AI narrative is held to real classical sources — works such as Ptolemy's Tetrabiblos on the Western side and texts like Brihat Parashara Hora Shastra and Phaladeepika on the Vedic side. The API does not invent verse numbers or fabricate authority; interpretive astrological statements trace to sources practitioners are actually trained on.

Key facts

• Tarot lives under /v2/tarot — 25 endpoints: card database (GET) plus named spreads (POST).
• Base URL is https://api.vedika.io; auth is the header x-api-key: vk_live_*.
• A reading needs only a question; pass an optional seed for reproducible draws.
• Responses return per-card position, isReversed, interpretation, keywords, and a spread summary; cost is in billing.charged.
• Per-call pricing runs about $0.01–$0.05; plans are wallets from $12 (Starter) to $240 (Enterprise).
• The free sandbox needs no key, so you can build the whole feature before paying.
• The same key unlocks real chart computation on the open-source XALEN Ephemeris (Apache-2.0; validated against JPL DE440 and swetest), across Vedic, Western and KP plus other systems, in 30 languages.

Where to go next

Build the reading flow against the free sandbox first, then provision a live key when you are ready to ship. Read the endpoint reference in the docs, compare per-call costs on the pricing page, and if you want to layer real charts under your tarot feature, see getting started with the astrology API.