Tarot API
A free tarot API with no key: all 78 Rider-Waite cards with upright and reversed meanings, Waite's original descriptions, suit filters and random draws. Live example included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the Tarot API?
Tarot API is a free, key-free REST API serving the full 78-card Rider-Waite tarot deck. Each card carries its upright and reversed meanings, its suit and numeric value, and the original descriptive text from A. E. Waite's 1911 Pictorial Key to the Tarot.
The dataset is the reason to use this rather than typing card meanings into a JSON file yourself. The `desc` field is not a modern paraphrase — it is Waite's own description of each card, several hundred words of it, which is public domain and unusually rich source material for a small API. Combined with `meaning_up` and `meaning_rev` you get both the short reading and the long imagery in one call.
The addressing scheme rewards five minutes of attention. Cards are identified by a short name that encodes the deck position: `ar00` through `ar21` for the Major Arcana, and suit-prefixed codes for the Minor. That makes deterministic lookups trivial, and it means a three-card spread can be stored as three short strings. There is a `/cards/random?n=` endpoint for draws, but be aware that `/cards/search` is a loose text match across meanings — searching for `fool` will also return cards whose reversed meaning mentions foolishness, which surprises people.
Quick facts
- Base URL
https://tarotapi.dev/api/v1- Authentication
- No key, no account, no attribution requirement. The underlying text is public domain.
- Rate limit
- No published limit. The deck is 78 static records — fetch `/cards` once and cache it forever.
- Pricing
- Free and open source.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the Tarot API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Look up The Fool by its short name
GET https://tarotapi.dev/api/v1/cards/ar00
curl 'https://tarotapi.dev/api/v1/cards/ar00'const res = await fetch("https://tarotapi.dev/api/v1/cards/ar00");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://tarotapi.dev/api/v1/cards/ar00", timeout=20)
res.raise_for_status()
print(res.json()){
"nhits": 1,
"card": {
"type": "major",
"name_short": "ar00",
"name": "The Fool",
"value": "ZERO",
"value_int": 0,
"meaning_up": "Folly, mania, extravagance, intoxication, delirium, frenzy, bewrayment.",
"meaning_rev": "Negligence, absence, distribution, carelessness, apathy, nullity, vanity.",
"desc": "With light step, as if earth and its trammels had little power to restrain him, a young man in gorgeous vestments pauses at the brink of a precipice among the great heights of the world; he surveys the blue distance before him-its expanse of sky rather than the prospect below. His act of eager walking is still indicated, though he is stationary at the given moment; his dog is still bounding. The edge which opens on the depth has no terror; it is as if angels were waiting to uphold him, if it came about that he leaped from the height. His countenance is full of intelligence and expectant dream. He has a rose in one hand and in the other a costly wand, from which depends over his right shoulder a wallet curiously embroidered. He is a prince of the other world on his travels through this one-all amidst the morning glory, in the keen air. The sun, which shines behind him, knows whence he came, whither he is going, and how he will return by another path after many days. He is the spirit in search of experience. Many symbols of the Instituted Mysteries are summarized in this card, which reverses, under high warrants, all the confusions that have preceded it.\nIn his Manual of Cartomancy, Grand Orient has a curious suggestion of the office of MyParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name_short | path segment | Optional | Card code. `ar00`-`ar21` for the Major Arcana; Minor Arcana use a suit prefix such as `cups` or `wands`. ar00 |
n | integer | Optional | On `/cards/random`, how many cards to draw. 3 |
q | string | Optional | On `/cards/search`, a loose text query across names and meanings. Broader than it looks. love |
suit | string | Optional | Filter to one suit: `cups`, `swords`, `wands` or `pentacles`. cups |
type | string | Optional | Filter by arcana: `major` or `minor`. major |
Response fields
nhitsinteger- How many cards matched. Present on single lookups too, where it is 1.
card / cardsobject or array- Single lookups return `card`; searches and random draws return a `cards` array. Handle both.
name_shortstring- The card's code — this is its stable identifier.
namestring- Display name, e.g. "The Fool".
typestring- `major` or `minor`.
value / value_intstring / integer- Rank as a word and as a number. `value_int` is what you sort on.
meaning_up / meaning_revstring- Upright and reversed readings, a comma-separated list of keywords.
descstring- Waite's full description of the card's imagery — often several hundred words.
What you can build with the Tarot API
- Build a daily-card or three-card-spread web app
- Seed a tarot learning tool with authentic period source text
- Generate card imagery prompts from the `desc` field
- Practise handling APIs that return a single object or an array depending on the route
- Add a card-of-the-day feature to a newsletter or bot
Common errors and how to fix them
404
Unknown card code.
Fix: Major Arcana are zero-padded: `ar00`, not `ar0`. There is no card `ar22` — the Major Arcana ends at 21.
Search returns the wrong card
`/cards/search` matches against meanings as well as names.
Fix: For an exact card use `/cards/{name_short}`. Reserve search for genuinely exploratory queries.
Response shape changes between calls
Single lookups return `card`, multi-card routes return `cards`.
Fix: Normalise at the edge of your client: wrap `card` into a one-element array and work with one shape internally.
Tarot API — frequently asked questions
Is there a free tarot API with no API key?
Yes. Tarot API serves all 78 Rider-Waite cards with no key, no account and no attribution requirement, because the underlying text is public domain.
Which deck does it cover?
The Rider-Waite-Smith deck, with descriptions taken from A. E. Waite's 1911 Pictorial Key to the Tarot. That is why the `desc` field reads like a century-old book — it is one.
Does it return card images?
No. It is text only: names, meanings and descriptions. You supply your own artwork, which is just as well, since most modern Rider-Waite illustrations are still in copyright in some jurisdictions.
How do I draw a random spread?
Call `/cards/random?n=3` for a three-card draw. The API returns distinct cards in the array, so you do not need to deduplicate a spread yourself.
Tools that pair with this API
Random List Picker
Paste a list and pick random winners without repeats, or shuffle the whole list. A fair random name and item picker for giveaways, draws and raffles.
Random Playing Card Generator
Deal random playing cards from a real 52-card deck shuffled with Fisher–Yates. Draw without replacement, add jokers, use multiple decks and track what remains.
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
Tarot API is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.