# Tarot API
> The complete 78-card tarot deck as an API — 22 Major Arcana and 56 Minor Arcana across the four suits (Wands, Cups, Swords and Pentacles). Look up any card by id or name (e.g. The Fool, The Lovers, Ace of Cups) for its upright and reversed meanings and the classic Rider-Waite description, search the whole deck by keyword or theme (e.g. love), browse a single minor suit, or draw a spread of random cards for an instant reading. Each card carries its arcana type, suit, numeric value and both interpretations. Ideal for tarot and astrology apps, daily-card widgets, divination and journaling tools, games and content sites.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tarot-api/..."
```

## Pricing
- **Free** (Free) — 11,500 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 165,000 calls/Mo, 8 req/s
- **Pro** ($9/Mo) — 710,000 calls/Mo, 20 req/s
- **Mega** ($29/Mo) — 2,920,000 calls/Mo, 50 req/s

## Endpoints

### Tarot

#### `GET /v1/card` — A card by id or name

**Parameters:**
- `id` (query, optional, string) — Card id, e.g. ar00 (The Fool) or wands01 Example: `ar00`
- `name` (query, optional, string) — Card name, e.g. The Lovers

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tarot-api/v1/card?id=ar00"
```

**Response:**
```json
{
    "data": {
        "card": {
            "id": "ar00",
            "name": "The Fool",
            "suit": null,
            "type": "major-arcana",
            "value": "ZERO",
            "value_int": 0,
            "description": "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. In his Manual of Cartomancy, Grand Orient has a curious suggestion of the office of Mystic
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/cards` — The whole deck, or one minor suit

**Parameters:**
- `suit` (query, optional, string) — wands | cups | swords | pentacles (omit for all 78) Example: `cups`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tarot-api/v1/cards?suit=cups"
```

**Response:**
```json
{
    "data": {
        "suit": "cups",
        "cards": [
            {
                "id": "cupa",
                "name": "Page of Cups",
                "suit": "cups",
                "type": "minor-arcana",
                "value": "page",
                "value_int": 11,
                "description": "A fair, pleasing, somewhat effeminate page, of studious and intent aspect, contemplates a fish rising from a cup to look at him. It is the pictures of the mind taking form.",
                "meaning_upright": "Fair young man, one impelled to render service and with whom the Querent will be connected; a studious youth; news, message; application, reflection, meditation; also these things directed to business.",
                "meaning_reversed": "Taste, inclination, attachment, seduction, deception, artifice."
            },
            {
                "id": "cukn",
                "name": "Knight of Cups",
                "suit": "cups",
                "type": "minor-arcana",
                "value": "knight",
                "value_int": 12,
                "description": "Graceful, but not warlike; riding quietly, wearing a winged helmet, referring to those higher graces of the imagination which sometimes characterize this card. He too is a dreamer, but the images of the side of sense haunt him in his vision.",
                "meaning_upright": "Arrival, approach--sometimes that of a messenger; advances, proposition, demeanour, invitation, incitement.",
       
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/draw` — Draw random cards for a reading

**Parameters:**
- `n` (query, optional, string) — How many cards (1-10, default 3) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tarot-api/v1/draw?n=3"
```

**Response:**
```json
{
    "data": {
        "cards": [
            {
                "id": "cu06",
                "name": "Six of Cups",
                "suit": "cups",
                "type": "minor-arcana",
                "value": "six",
                "value_int": 6,
                "description": "Children in an old garden, their cups filled with flowers.",
                "meaning_upright": "A card of the past and of memories, looking back, as--for example--on childhood; happiness, enjoyment, but coming rather from the past; things that have vanished. Another reading reverses this, giving new relations, new knowledge, new environment, and then the children are disporting in an unfamiliar precinct.",
                "meaning_reversed": "The future, renewal, that which will come to pass presently."
            },
            {
                "id": "pe03",
                "name": "Three of Pentacles",
                "suit": "pentacles",
                "type": "minor-arcana",
                "value": "three",
                "value_int": 3,
                "description": "A sculptor at his work in a monastery. Compare the design which illustrates the Eight of Pentacles. The apprentice or amateur therein has received his reward and is now at work in earnest.",
                "meaning_upright": "Métier, trade, skilled labour; usually, however, regarded as a card of nobility, aristocracy, renown, glory.",
                "meaning_reversed": "Mediocrity, in work and otherwise, puerility, pe
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search cards by name or meaning

**Parameters:**
- `q` (query, required, string) — Keyword or theme, e.g. love Example: `love`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tarot-api/v1/search?q=love"
```

**Response:**
```json
{
    "data": {
        "cards": [
            {
                "id": "ar06",
                "name": "The Lovers",
                "suit": null,
                "type": "major-arcana",
                "value": "6",
                "value_int": 6,
                "description": "The sun shines in the zenith, and beneath is a great winged figure with arms extended, pouring down influences. In the foreground are two human figures, male and female, unveiled before each other, as if Adam and Eve when they first occupied the paradise of the earthly body. Behind the man is the Tree of Life, bearing twelve fruits, and the Tree of the Knowledge of Good and Evil is behind the woman; the serpent is twining round it. The figures suggest youth, virginity, innocence and love before it is contaminated by gross material desire. This is in all simplicity the card of human love, here exhibited as part of the way, the truth and the life. It replaces, by recourse to first principles, the old card of marriage, which I have described previously, and the later follies which depicted man between vice and virtue. In a very high sense, the card is a mystery of the Covenant and Sabbath. The suggestion in respect of the woman is that she signifies that attraction towards the sensitive life which carries within it the idea of the Fall of Man, but she is rather the working of a Secret Law of Providence than a willing and conscious temptress. It is through her imputed lapse that man shall arise ultimatel
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Suits & usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tarot-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "The 78-card tarot deck (22 Major Arcana + 56 Minor Arcana). /v1/card = a card by id (e.g. ar00 → The Fool) or name, with upright & reversed meanings; /v1/draw = draw n random cards (1-10) for a reading; /v1/search = search cards by name or meaning (e.g. q=love); /v1/cards = the whole deck or one minor suit (suit=wands|cups|swords|pentacles).",
        "suits": [
            "wands",
            "cups",
            "swords",
            "pentacles"
        ],
        "source": "tarotapi.dev",
        "deck_size": 78,
        "endpoints": [
            "/v1/card",
            "/v1/draw",
            "/v1/search",
            "/v1/cards",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:27.872Z",
        "request_id": "e802e1af-1683-48d9-86a9-da5ca8a7ed8f"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/tarot-api
OpenAPI spec: https://www.oanor.com/api/tarot-api/openapi.json