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.

Endpoint

POST /v1/tarot/spread/three-card

Request parameters

Field	Type	Required	Description
allow_reversed	boolean	No	If true, each card has a 50% chance of appearing reversed.
question	string \| null	No	Optional question or intention for the reading.

Example request

curl
Python
TypeScript

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

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)

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

Example response

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

Response fields

Field	Type	Description
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

Code	Description	Reference
authentication_failed	Missing or invalid API key.	authentication_failed
ephemeris_unavailable	Upstream ephemeris service error.	ephemeris_unavailable
insufficient_tier	API key tier does not include this endpoint.	insufficient_tier
internal_error	Unexpected server error.	internal_error
ip_rate_limit_exceeded	Too many requests in a short window.	ip_rate_limit_exceeded
payload_too_large	Request body exceeds the size limit.	payload_too_large
resource_not_found	Referenced resource was not found.	resource_not_found
validation_error	Request body failed schema validation.	validation_error

Endpoint​

Request parameters​

Example request​

Example response​

Response fields​

Errors​

Related endpoints​