---
title: "Three-Card Spread"
method: POST
path: "/v1/tarot/spread/three-card"
tags: ["Tarot"]
---

# Three-Card Spread

`POST /v1/tarot/spread/three-card`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/tarot/spread/three-card`
- Auth: HTTP bearer

Past / Present / Future tarot spread: draws 3 unique cards, one for each position. The positions are past (what led here), present (current situation), future (where this leads). Each position includes the card data, its orientation, the position meaning, and the active interpretation for that orientation.

## Request body

- SpreadRequest
  - `allow_reversed` boolean: If true, each card has a 50% chance of appearing reversed.
  - `question` string, nullable: Optional question or intention for the reading.

## Response `200`

Successful Response

- ApiResponseSpreadResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` SpreadResponse, required
    - `spread_type` string, required: Spread type: 'three_card' or 'celtic_cross'
    - `positions` DrawnCardSchema[], required
      - `card` TarotCardSchema, required
        - `id` string, required: Unique slug identifier e.g. 'the-fool'
        - `name` string, required: Full card name e.g. 'The Fool'
        - `arcana_type` string, required: 'major' or 'minor'
        - `suit` string, nullable: Suit for minor arcana: wands, cups, swords, pentacles. Null for major arcana.
        - `number` integer, required: Card number. Major arcana: 0-21. Minor arcana: 1=Ace, 11=Page, 12=Knight, 13=Queen, 14=King.
        - `element` string, required: Elemental correspondence: fire, water, air, earth, spirit
        - `astrology_correspondence` string, required: Astrological planet or sign correspondence
        - `keywords_upright` string[], required: Upright keywords
        - `keywords_reversed` string[], required: Reversed keywords
        - `upright_meaning` string, required: Full upright interpretation
        - `reversed_meaning` string, required: Full reversed interpretation
        - `yes_no` string, required: Yes/No polarity: 'yes', 'no', or 'maybe'
        - `description` string, required: Visual description of the card imagery
      - `is_reversed` boolean, required: True if the card was drawn in reversed orientation
      - `position` string, nullable: Spread position name e.g. 'past', 'present', 'outcome'
      - `position_meaning` string, nullable: What this spread position represents
      - `active_meaning` string, required: The meaning to apply — upright_meaning when is_reversed=False, reversed_meaning when True
      - `active_keywords` string[], required: Active keywords for this orientation
    - `question` string, nullable: The question posed, if provided

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)