# Tarot

Three decks: Rider-Waite-Smith (78 cards), Marseille Tarot (78) and Lenormand (36). Each card in each tarot response has an image, and `POST /v1/interpret/tarot` converts a spread into an interpretation: each position in context, a summary of the whole spread, and one piece of advice.

## Kies de kaartstijl
`GET /v1/tarot/decks` returns each deck, its spreads and styling sets that can be passed as `art` to any tarot route (in the POST body or as `?art=` in GET). All sets are public domain and are served from our CDN.

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

Each card receives an `image` with `urlSmall` (300 px wide, for cards up to approx 150 px on the page), `url` (600 px), `url2x` (1200 px), `width`, `height` and `art`. The spread also returns `back`, the card back, so the page can first show cards face down. Using an `art` from another deck yields `400 INVALID_ART` with a list of allowed values. A card that has no image in the set (the Moon in Lenormand) is listed in `missing` of that set and comes without `image`, so display 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" }
}
```

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

## Kaartteksten zonder model
`GET /v1/public/tarot/texts?cards=the-fool,9-of-swords&lang=uk` works without a key and returns for each card a `description` of three paragraphs (image, upright meaning, reversed meaning) and text about `love`, `career`, `finance`, `health` and `spirit` for `upright` and `reversed`, together with the localized name `name` and up to five `keywords` per side. Without `cards` you get all 78. The texts do not change, so download the cards that the page shows and cache them.

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

## Uitleg van de hele spreiding
`POST /v1/interpret/tarot` accepts a deck, spread, cards and an optional question and writes an interpretation in the language from `language` (21 languages). Cards can be passed as slugs, objects `{ "slug", "reversed" }` or an array `drawn` from any spread response without changes.

<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>

In the response `positions[]` (position, card with `image`, `reversed`, `reading`), `synthesis`, `advice` and `disclaimer`. Rider-Waite-Smith cards also have `nameLocalized` and `positionLocalized` in the interpretation language. The interpretation costs **100 credits** (Tier 4) and is available on the Free plan; with your own model key it's cheaper, see [Your model key](/agent-setup/).

<Aside type="note">
De interpretatie is een gegenereerde tekst gebaseerd op de traditionele betekenis van elke kaart in haar positie. De API koppelt de kaarten, hun positie en posities aan je verzoek en verwijdert interpretaties die een kaart overslaan, maar beschouw de tekst als een aanzet tot nadenken, niet als een voorspelling.
</Aside>