Tarot API

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.

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?"
}'

{
  "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": "…"
      }
    ]
  }
}

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.

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.