Tarot Cards API

Draw random tarot cards from a full 78-card deck — Major and Minor Arcana, upright and reversed, with short meanings included in every response.

Get your API token

Create an account and subscribe ($9/month) to start using the API.

Create account Sign in

Why use this instead of asking an AI?

When you ask an AI model to "draw a random tarot card" it does not draw randomly — it predicts the most statistically likely answer based on training data. Cards like The Star or The Fool appear far more often than Ten of Swords or Five of Pentacles because they are over-represented in the corpus. This API uses PHP mt_rand() + shuffle() — a real pseudo-random number generator with no bias toward any card, any arcana, or any orientation. Every card in the filtered pool has an exactly equal probability of being drawn.

No hallucinated card names or invented meanings
No popularity bias — obscure Minor Arcana cards have the same draw probability as The World
Stateless — each call is independent; no history or pattern affects the next draw
Deterministic deck — same 78 cards, same meanings, every time

Endpoint

GET /api/tarot

All parameters are optional query strings.

Authentication

Include your API token in every request:

Query parameter: ?token=YOUR_TOKEN
Header: Authorization: Bearer YOUR_TOKEN

Parameters

Parameter	Type	Default	Description
`amount`	integer	`1`	Number of cards to draw. Min `1`, max = total cards in the filtered pool (22 for major, 56 for minor, 78 for all). No duplicates.
`arcana`	string	`all`	Which arcana to draw from: `all`, `major`, or `minor`.
`reversed`	boolean	`true`	Whether cards can appear reversed. `true` = each drawn card has a 50 % chance of being reversed. `false` = all cards are upright.
`version`	string	`abesttools_api_tarot_v1`	Deck version to use. See Deck Versions below.

Response Fields

Field	Type	Description
`data.version`	string	Deck version used.
`data.arcana_filter`	string	Arcana filter applied: `all`, `major`, or `minor`.
`data.reversed_enabled`	boolean	Whether reversed orientation was enabled for this draw.
`data.total_in_pool`	integer	Total cards available after applying the arcana filter.
`data.amount`	integer	Number of cards returned.
`data.cards[].id`	integer	Unique card ID (1–78, stable across requests).
`data.cards[].name`	string	Card name, e.g. `The Fool`, `Ace of Wands`.
`data.cards[].arcana`	string	`major` or `minor`.
`data.cards[].number`	integer	Card number within its arcana. Major: 0–21. Minor: 1–14 per suit.
`data.cards[].suit`	string\|null	For Minor Arcana: `wands`, `cups`, `swords`, or `pentacles`. `null` for Major Arcana.
`data.cards[].orientation`	string	`upright` or `reversed`.
`data.cards[].meaning`	string	Short keyword meaning matching the card's orientation.

Deck Versions

Version key	Cards	Major Arcana	Minor Arcana	Status
`abesttools_api_tarot_v1`	78	22 (The Fool – The World)	56 (Wands, Cups, Swords, Pentacles — Ace through King)	Active

New deck versions (e.g. thematic decks with different meaning flavours) will be added as separate version keys. Existing version keys never change their card list or meanings, so your integration stays stable.

Example Requests

Draw 1 card (default)

GET /api/tarot?token=YOUR_TOKEN

Draw a 3-card spread, Major Arcana only, upright only

GET /api/tarot?token=YOUR_TOKEN&amount=3&arcana=major&reversed=false

Draw a Celtic Cross (10 cards), full deck, reversals enabled

GET /api/tarot?token=YOUR_TOKEN&amount=10

Example Response

{
  "success": true,
  "data": {
    "version": "abesttools_api_tarot_v1",
    "arcana_filter": "all",
    "reversed_enabled": true,
    "total_in_pool": 78,
    "amount": 3,
    "cards": [
      {
        "id": 14,
        "name": "Death",
        "arcana": "major",
        "number": 13,
        "suit": null,
        "orientation": "upright",
        "meaning": "Endings, transformation, transition, change"
      },
      {
        "id": 47,
        "name": "Page of Cups",
        "arcana": "minor",
        "number": 11,
        "suit": "cups",
        "orientation": "reversed",
        "meaning": "Emotional immaturity, creative blocks, insecurity"
      },
      {
        "id": 72,
        "name": "Eight of Pentacles",
        "arcana": "minor",
        "number": 8,
        "suit": "pentacles",
        "orientation": "upright",
        "meaning": "Mastery, skill development, diligence, craftsmanship"
      }
    ]
  }
}

Error Responses

HTTP Status	Reason
`401`	Missing or invalid API token.
`403`	No active subscription.
`422`	Invalid `arcana` value or unknown `version`.