POST/v1/tarot/spread/three-card

Three-Card Spread

Past / Present / Future spread. Draws 3 unique cards and assigns them to positions: 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 parameters

allow_reversedoptional

boolean

If true, each card has a 50% chance of appearing reversed.

questionoptional

string | null

Optional question or intention for the reading.

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.spread_type

string

Spread type: 'three_card' or 'celtic_cross'

data.positions

array[object]

data.positions[].card

object

data.positions[].card.id

string

Unique slug identifier e.g. 'the-fool'

data.positions[].card.name

string

Full card name e.g. 'The Fool'

data.positions[].card.arcana_type

string

'major' or 'minor'

data.positions[].card.suit

string | null

Suit for minor arcana: wands, cups, swords, pentacles. Null for major arcana.

data.positions[].card.number

integer

Card number. Major arcana: 0-21. Minor arcana: 1=Ace, 11=Page, 12=Knight, 13=Queen, 14=King.

data.positions[].card.element

string

Elemental correspondence: fire, water, air, earth, spirit

data.positions[].card.astrology_correspondence

string

Astrological planet or sign correspondence

data.positions[].card.keywords_upright

array[string]

Upright keywords

data.positions[].card.keywords_reversed

array[string]

Reversed keywords

data.positions[].card.upright_meaning

string

Full upright interpretation

data.positions[].card.reversed_meaning

string

Full reversed interpretation

data.positions[].card.yes_no

string

Yes/No polarity: 'yes', 'no', or 'maybe'

data.positions[].card.description

string

Visual description of the card imagery

data.positions[].is_reversed

boolean

True if the card was drawn in reversed orientation

data.positions[].position

string | null

Spread position name e.g. 'past', 'present', 'outcome'

data.positions[].position_meaning

string | null

What this spread position represents

data.positions[].active_meaning

string

The meaning to apply — upright_meaning when is_reversed=False, reversed_meaning when True

data.positions[].active_keywords

array[string]

Active keywords for this orientation

data.question

string | null

The question posed, if provided

Errors

authentication_failed

Missing or invalid API key.

ephemeris_unavailable

Upstream ephemeris service error.

insufficient_tier

API key tier does not include this endpoint.

internal_error

Unexpected server error.

ip_rate_limit_exceeded

Too many requests in a short window.

payload_too_large

Request body exceeds the size limit.

resource_not_found

Referenced resource was not found.

validation_error

Request body failed schema validation.

Related endpoints

• Celtic Cross Spread
• Yes/No Tarot Reading

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/tarot/spread/three-card" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_reversed":true,"question":"What should I focus on now?"}'

Python

import asterwise
from asterwise.api.tarot_api import TarotApi
from asterwise.models.spread_request import SpreadRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = SpreadRequest(
    allow_reversed=True,
    question="What should I focus on now?",
)

with asterwise.ApiClient(configuration) as client:
    api = TarotApi(client)
    result = api.tarot_three_card(spread_request=request)
    print(result)

TypeScript

import { createClient, createConfig, tarotThreeCard } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await tarotThreeCard({
  client,
  body: {
      "allow_reversed": true,
      "question": "What should I focus on now?"
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "spread_type": "three_card",
    "positions": [
      {
        "card": {
          "id": "the-hermit",
          "name": "The Hermit",
          "arcana_type": "major",
          "suit": null,
          "number": 9,
          "element": "earth",
          "astrology_correspondence": "Virgo",
          "keywords_upright": [
            "solitude",
            "inner guidance",
            "... and 3 more items"
          ],
          "keywords_reversed": [
            "isolation",
            "loneliness",
            "... and 3 more items"
          ],
          "upright_meaning": "The Hermit calls for a period of solitude and deep introspection. Wisdom is found within, not in the noise of the world.…",
          "reversed_meaning": "Reversed, The Hermit warns of excessive isolation, loneliness, or refusal to accept guidance. Withdrawal has become avoi…",
          "yes_no": "maybe",
          "description": "An old man in grey robes stands alone on a snowy peak. He holds a lantern in one hand, a staff in the other. Stars are i…"
        },
        "is_reversed": true,
        "position": "past",
        "position_meaning": "The past — what has led to this moment",
        "active_meaning": "Reversed, The Hermit warns of excessive isolation, loneliness, or refusal to accept guidance. Withdrawal has become avoi…",
        "active_keywords": [
          "isolation",
          "loneliness",
          "... and 3 more items"
        ]
      },
      {
        "card": {
          "id": "four-of-swords",
          "name": "Four of Swords",
          "arcana_type": "minor",
          "suit": "swords",
          "number": 4,
          "element": "air",
          "astrology_correspondence": "Jupiter in Libra",
          "keywords_upright": [
            "rest",
            "recuperation",
            "... and 3 more items"
          ],
          "keywords_reversed": [
            "restlessness",
            "burn-out",
            "... and 2 more items"
          ],
          "upright_meaning": "The Four of Swords calls for rest, recovery, and temporary withdrawal from the world. The body and mind need sanctuary.…",
          "reversed_meaning": "Reversed, the Four of Swords warns of burn-out, restlessness preventing needed recovery, or refusing to rest when the bo…",
          "yes_no": "maybe",
          "description": "A knight in effigy lies on a tomb in a church, hands in prayer. Three swords hang on the wall above; one lies beneath. A…"
        },
        "is_reversed": false,
        "position": "present",
        "position_meaning": "The present — the current situation and energy",
        "active_meaning": "The Four of Swords calls for rest, recovery, and temporary withdrawal from the world. The body and mind need sanctuary.…",
        "active_keywords": [
          "rest",
          "recuperation",
          "... and 3 more items"
        ]
      },
      "... and 1 more item"
    ],
    "question": "What should I focus on now?"
  }
}