# Tarot API

This endpoint performs a seeded, reproducible draw from the 78-card Rider-Waite-Smith deck for the three-card spread. It returns the spread metadata, the integer seed that governed the shuffle, and the drawn cards with their positions, orientations and meanings — so any reading can be replayed exactly by passing the seed back.

## Endpoint

`POST /v1/tarot/rider-waite/draw/three-card`

- Operation ID: `tarot/rider-waite/draw/three-card`
- Cost: 10 credits (tier 1)
- Typical latency: 58 ms, measured against production
- Canonical page: https://api.astroway.info/en/astrology-api/tarot/

## What it computes

Given an optional question and an optional seed, the endpoint draws cards from the full 78-card deck for the three-card layout, with each card landing in a defined position and oriented either upright or reversed. The response describes the spread itself, echoes the integer seed used, and lists the drawn cards — each carrying its position label, its orientation, and the meaning attached to that card in that orientation. The seed is the heart of the design: omit it and the server generates one for you and returns it; supply it and you regenerate an identical draw, which makes readings shareable, testable and auditable. The allowReversed flag decides whether reversals are possible at all. Other spreads — single-card, Celtic Cross, horseshoe, relationship and year-ahead — are sibling endpoints driven by the same deck and seeding mechanism.

## When to use it

Reach for this when you want a tarot reading that you can reproduce on demand rather than a one-off random draw. Capture the returned seed and you can re-render the exact same three cards later — in a shared link, a saved reading, a regression test, or a support ticket — without storing the card list yourself. Use a fixed seed in tests so your UI and copy render deterministically, and let the server mint a fresh seed in production for genuine variety. Reach for the three-card spread specifically when you want a compact past/present/future-style structure; switch to a sibling endpoint when a layout with more positions suits the experience better.

## Request parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `question` | string | no | An optional free-text question to associate with the reading; it is recorded with the draw but does not alter which cards are dealt. |
| `seed` | number | no | An optional integer that fixes the shuffle; pass the seed from a prior response to regenerate an identical draw. |
| `allowReversed` | boolean | no | An optional boolean (default true) that controls whether cards may appear reversed; set false to draw upright cards only. |

## Example request

```bash
curl -X POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "question": "How will my new project unfold?"
}'
```

## Example response

```json
{
  "ok": true,
  "data": {
    "spread": {
      "slug": "three-card",
      "name": "Three Card",
      "cardCount": 3
    },
    "seed": 4044793529,
    "drawn": [
      {
        "position": {
          "index": 0,
          "name": "Past"
        },
        "card": {
          "slug": "knight-of-wands",
          "name": "Knight of Wands"
        },
        "reversed": false,
        "meaning": "…"
      }
    ]
  }
}
```

## Notes

Card imagery is the Rider-Waite-Smith deck (A. E. Waite & Pamela Colman Smith, 1909), which is in the public domain. Set allowReversed to false to draw upright cards only — useful for beginner-friendly readings where reversed meanings would add confusion. The same seed reproduces a draw only for the same spread and the same allowReversed setting.

## Related techniques

- https://api.astroway.info/en/astrology-api/numerology/

---

Full machine-readable spec: https://api.astroway.info/v1/openapi.json
Agent instructions: https://api.astroway.info/AGENTS.md