POST/v1/tarot/spread/three-card

Three-Card Spread

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

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

resource_not_found

The requested resource was not found at this endpoint. Verify the URL path and resource identifier.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

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": "eight-of-swords",
          "name": "Eight of Swords",
          "arcana_type": "minor",
          "suit": "swords",
          "number": 8,
          "element": "air",
          "astrology_correspondence": "Jupiter in Gemini",
          "keywords_upright": [
            "restriction",
            "fear",
            "... and 3 more items"
          ],
          "keywords_reversed": [
            "self-limiting beliefs",
            "release",
            "... and 2 more items"
          ],
          "upright_meaning": "The Eight of Swords shows someone who feels trapped but whose bonds are not as tight as they appear. The prison is large…",
          "reversed_meaning": "Reversed, the Eight of Swords signals release from self-imposed limitations, new perspective breaking through fear, and…",
          "yes_no": "no",
          "description": "A bound and blindfolded figure stands surrounded by eight swords stabbed into the ground. Water lies at their feet. The…"
        },
        "is_reversed": true,
        "position": "past",
        "position_meaning": "The past — what has led to this moment",
        "active_meaning": "Reversed, the Eight of Swords signals release from self-imposed limitations, new perspective breaking through fear, and…",
        "active_keywords": [
          "self-limiting beliefs",
          "release",
          "... and 2 more items"
        ]
      },
      {
        "card": {
          "id": "page-of-swords",
          "name": "Page of Swords",
          "arcana_type": "minor",
          "suit": "swords",
          "number": 11,
          "element": "air",
          "astrology_correspondence": "Earth of Air",
          "keywords_upright": [
            "curiosity",
            "restlessness",
            "... and 3 more items"
          ],
          "keywords_reversed": [
            "haste",
            "deception",
            "... and 2 more items"
          ],
          "upright_meaning": "The Page of Swords brings a restless, curious, and vigilant energy. New information arrives. Mental agility and quick th…",
          "reversed_meaning": "Reversed, the Page of Swords warns of haste, gossip, or talk without action. Deceptive communication may be at play.",
          "yes_no": "maybe",
          "description": "A young figure stands on a hilltop, sword raised, looking around with alert eyes. Wind whips the trees and their hair. T…"
        },
        "is_reversed": false,
        "position": "present",
        "position_meaning": "The present — the current situation and energy",
        "active_meaning": "The Page of Swords brings a restless, curious, and vigilant energy. New information arrives. Mental agility and quick th…",
        "active_keywords": [
          "curiosity",
          "restlessness",
          "... and 3 more items"
        ]
      },
      "... and 1 more item"
    ],
    "question": "What should I focus on now?"
  }
}