# 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"
```

#### `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"
```

#### `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"
```

#### `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"
```

### Meta

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

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


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