Tarot card API for developers

Everything a tarot app needs, in one module

Readings and a full card encyclopedia live in the Tarot module (14 endpoints). Every endpoint has its own reference page with request fields and a cURL example.

Four decks, each with its own card names

Pass "deck" on any reading. The default is rider_waite.

A real request and response

curl -X POST https://api.grahaapi.com/v1/tarot/single \
  -H "Authorization: Bearer sk-test-your-key" \
  -H "Content-Type: application/json" \
  -d '{"question": "What does my future hold?", "deck": "rider_waite"}'

{"success": true,
 "data": {
  "reading": {
   "reading_id": "745f16a47d9241999378c587d261971a",
   "timestamp": "2026-10-17T09:58:59+00:00",
   "seed_used": null, ...},
  "spread": "single",
  "deck": "rider_waite",
  "question": "What does my future hold?",
  "card": {
   "id": 32,
   "name": "Page of Wands", "name_hi": "दंड का पेज",
   "suit": "wands", "value": "Page",
   "element": "Fire", "element_hi": "अग्नि",
   "keywords": ["career", "page", "fire"], "keywords_hi": ["करियर", "पेज", "अग्नि"],
   "position": "Answer", "position_hi": "उत्तर",
   "reversed": true,
   "interpretation_en": "Reversed, enthusiasm fizzles, news disappoints, ...",
   "interpretation_hi": "उल्टा — उत्साह ठंडा, समाचार निराशाजनक, ...", ...},
  "guidance_en": "Message of Page of Wands for your question: ...",
  "guidance_hi": "इस प्रश्न के लिए 'दंड का पेज' कार्ड का संदेश: ..."},
 "meta": {"mode": "test", ...}}

This is what a sk-test- key returned on 2026-10-17 (shortened where you see ...). Test mode runs the real endpoint code on a fixed sample request, so the structure is exactly what production sends. It ignores your own question and seed, and its card is a random draw, so yours will likely differ.

Seeded, reproducible draws

• No seed: cards and upright/reversed orientations come from a cryptographically secure random draw.
• With "seed": 42 (any integer): the same seed and question on the same day return the same cards in the same orientations. Use it for shareable readings, tests and UI previews.
• Card of the day (/daily) is the same all day. Send a per-user seed to give each user their own card.
• Journal-ready: every reading returns reading.reading_id, a timestamp and the seed used, so you can store readings and show history.

English and Hindi in the same response

There is no language switch and no extra charge: each card carries name + name_hi, interpretation_en + interpretation_hi, position + position_hi and its keyword chips as keywords + keywords_hi (two lists in the same order), and verdicts come as answer + answer_hi (Yes / हाँ). Render whichever your user picked, or both.

Free to build on, simple to pay for

• Unlimited test mode: any sk-test- key works on all 14 tarot endpoints, free, forever.
• Free plan: 1,000 real calls a month, no credit card.
• INR pricing: paid plans from ₹499/month. 1 call = 1 call, so a 10-card Celtic Cross costs the same single call as a one-card draw. At the monthly limit calls pause until the 1st or an upgrade; there are no overage bills. See pricing.

What the API does not include

Card images. The API returns structured data (card ID, name, suit, element, keywords and interpretation text), not artwork. Use card art you have the rights to and look it up by the id or name in each response.