# Tarot

Three decks: Rider-Waite-Smith (78 cards), Tarot de Marseille (78) and Lenormand (36). Every card in every tarot response carries a picture, and `POST /v1/interpret/tarot` turns a spread into a reading: each position in context, a synthesis of the whole spread and one piece of advice.

## Pick the card art

`GET /v1/tarot/decks` lists each deck, its spreads and the art sets you can pass as `art` on any tarot route (in the body of a POST, as `?art=` on a GET). All sets are public domain and served from our CDN.

| Deck | `art` | Cards |
|---|---|---|
| Rider-Waite-Smith | `rws-1909` (default), `rws-restored`, `rws-vector` | 78 |
| Tarot de Marseille | `arnoult-1748` | 78 |
| Lenormand | `dondorf` | 35 of 36, no Moon |

Each card gets `image` with `urlSmall` (300 px wide, for cards shown up to about 150 px), `url` (600 px), `url2x` (1200 px), `width`, `height` and `art`. A draw also returns `back`, the card back, so a page can show the cards face down first. An `art` from another deck is a `400 INVALID_ART` that names the valid ones. A card a set has no picture for (the Lenormand Moon) is listed in that set's `missing` and comes without `image`, so draw a text card for it.

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{ "seed": 12345, "art": "rws-restored" }'
    ```
  </TabItem>
</Tabs>

```json
{
  "drawn": [
    {
      "position": { "index": 0, "name": "Past", "meaning": "Forces from the past shaping the situation." },
      "card": {
        "slug": "8-of-pentacles",
        "name": "Eight of Pentacles",
        "image": {
          "url": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles.webp",
          "url2x": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles@2x.webp",
          "urlSmall": "https://cdn.astroway.info/tarot/rws-restored/8-of-pentacles-300.webp",
          "width": 600,
          "height": 1028,
          "art": "rws-restored"
        }
      },
      "reversed": false
    }
  ],
  "back": { "url": "https://cdn.astroway.info/tarot/rws-1909/back.webp", "url2x": "https://cdn.astroway.info/tarot/rws-1909/back@2x.webp", "urlSmall": "https://cdn.astroway.info/tarot/rws-1909/back-300.webp", "width": 600, "height": 1039, "art": "rws-1909" }
}
```

A draw from `POST /v1/tarot/rider-waite/draw/three-card` costs **10 credits**.

## Card texts without a model

`GET /v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=en` needs no key and returns, for each card, a three-paragraph `description` (the picture, the upright meaning, the reversed meaning) and a text on `love`, `career`, `finance`, `health` and `spirit` for both `upright` and `reversed`, with the localised `name` and up to five `keywords` per side. Leave out `cards` for all 78. The texts do not change, so fetch the cards a page shows and cache them.

```bash
curl 'https://api.astroway.info/v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=en'
```

## Read the whole spread

`POST /v1/interpret/tarot` takes the deck, the spread, the cards and an optional question, and writes the reading in the `language` you ask for (21 languages). The cards can be slugs, `{ "slug", "reversed" }` objects, or the `drawn` array of any draw response as it is.

<Tabs>
  <TabItem label="Node.js">
    ```js
    const headers = { 'Content-Type': 'application/json', 'X-Api-Key': process.env.ASTROWAY_API_KEY };
    const api = (path, body) =>
      fetch(`https://api.astroway.info/v1${path}`, { method: 'POST', headers, body: JSON.stringify(body) }).then((r) => r.json());
    
    const { data: spread } = await api('/tarot/rider-waite/draw/three-card', { art: 'rws-1909' });
    const { data: reading } = await api('/interpret/tarot', {
      spread: 'three-card',
      question: 'What should I focus on at work?',
      cards: spread.drawn,
      language: 'en',
    });
    
    for (const p of reading.positions) {
      console.log(p.position, p.card.name, p.reversed ? '(reversed)' : '', p.card.image.url);
      console.log(' ', p.reading);
    }
    console.log('Summary:', reading.synthesis);
    ```
  </TabItem>
</Tabs>

The answer has `positions[]` (position, card with its `image`, `reversed`, `reading`), `synthesis`, `advice` and `disclaimer`. Rider-Waite-Smith cards also carry `nameLocalized` and `positionLocalized` in the reading language. A reading costs **100 credits** (Tier 4) and is available on the Free plan; with your own model key it costs less, see [Bring your own model key](/en/agent-setup/#bring-your-own-model-key).

<Aside type="note">
The reading is generated text built on the traditional meaning of each card in its position. The API pins the cards, their orientation and positions to your request and refuses a reading that skips a card, but treat the prose as reflection, not prediction.
</Aside>