---
title: "Draw Tarot Cards"
method: POST
path: "/v1/tarot/draw"
tags: ["Tarot"]
---

# Draw Tarot Cards

`POST /v1/tarot/draw`

## Request

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

Draw N random unique cards from the 78-card deck using cryptographic randomness. Each API call produces a fresh independent draw. Count must be between 1 and 78. Default: 1. Set allow_reversed=true to enable reversed card orientation (each card independently has a 50% chance of reversal).

## Request body

- DrawRequest
  - `count` integer: Number of cards to draw (1-78). Default: 1.
  - `allow_reversed` boolean: If true, each card has a 50% chance of appearing reversed.

## Response `200`

Successful Response

- ApiResponseDrawResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` DrawResponse, required
    - `cards` 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
    - `count` integer, required
    - `allow_reversed` boolean, required

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