API reference · v1

Tarot

Full tarot engine: draw cards for eight spreads, pull clarifying cards that weave a follow-up narrative, fetch readings, and pull the complete 78-card reference deck for your own UI.

6 endpoints · 1 credit per call

Endpoints

Every tarot endpoint

Parameters, copy-paste examples in three languages, and response shapes.

POST/api/v1/tarot/reading

Draw a reading

Draw cards for a spread. Omit cards for a random server draw, or pass user-picked card ids from your own interactive fan. Premium spreads return a full AI interpretation; the single-card daily draw returns a free teaser.

2 credits per call

Parameters

Name	Type	In	Required	Description
spread_type	string	body	optional	single_card, three_card (default), celtic_cross, horseshoe, relationship, career, monthly, year_ahead
spread_id	string	body	optional	Alias for spread_type — accepts frontend slugs like "three-card"
question	string	body	optional	The querent's question (max 1000 chars)
category	string	body	optional	Question category, e.g. love, career
cards	array	body	optional	User-picked cards: [{card_id, position, reversed}] — server draws randomly if omitted
seed	integer	body	optional	Optional seed for deterministic draws
language	string	body	optional	Two-letter language code (default en)

Example request

cURL

curl -X POST "https://api-rho-eight-42.vercel.app/api/v1/tarot/reading" \
  -H "X-API-Key: kundli_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "spread_type": "three_card",
  "question": "What should I focus on this month?",
  "category": "career",
  "language": "en"
}'

Example response

JSON

{
  "reading_id": "9f2a1c4e-6b3d-4a5f-8e7c-2d1a3b4c5d6e",
  "spread_type": "three_card",
  "cards_drawn": [
    {
      "position": "Past",
      "card_name": "The Hermit",
      "orientation": "upright"
    },
    {
      "position": "Present",
      "card_name": "Ace of Pentacles",
      "orientation": "upright"
    },
    {
      "position": "Future",
      "card_name": "The Star",
      "orientation": "upright"
    }
  ],
  "interpretation": {
    "summary": "A period of quiet preparation is paying off..."
  },
  "unlocked": true
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

POST/api/v1/tarot/readings/clarify

Clarifying card

Draw a clarifying card that builds on an existing reading — free, deterministic, zero AI cost. Already-drawn cards are excluded so the clarifier is always new.

1 credit per call

Parameters

Name	Type	In	Required	Description
original_cards	string[]	body	optional	Card names already drawn (excluded from the clarifying draw)
original_question	string	body	optional	The querent's original question for context
language	string	body	optional	Two-letter language code (default en)

Example request

cURL

curl -X POST "https://api-rho-eight-42.vercel.app/api/v1/tarot/readings/clarify" \
  -H "X-API-Key: kundli_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "original_cards": [
    "The Hermit",
    "Ace of Pentacles"
  ],
  "original_question": "What should I focus on this month?",
  "language": "en"
}'

Example response

JSON

{
  "card_name": "The Star",
  "orientation": "upright",
  "narrative": "The Star appears upright as your clarifying card — its themes are hope, renewal, inspiration.",
  "combination": "When we place The Star beside The Hermit, the story deepens...",
  "followups": [
    "What would hope look like as a daily practice?"
  ],
  "actions": [
    "Write down one thing you are quietly hoping for."
  ]
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

GET/api/v1/tarot/reading/{reading_id}

Get a reading

Fetch a previously created reading by its id, including drawn cards and teaser/interpretation state.

1 credit per call

Parameters

Name	Type	In	Required	Description
reading_id	string	path	required	UUID returned by POST /reading

Example request

cURL

curl "https://api-rho-eight-42.vercel.app/api/v1/tarot/reading/{reading_id}" \
  -H "X-API-Key: kundli_abc123..."

Example response

JSON

{
  "reading_id": "9f2a1c4e-6b3d-4a5f-8e7c-2d1a3b4c5d6e",
  "spread_type": "three_card",
  "cards_drawn": [
    {
      "position": "Past",
      "card_name": "The Hermit",
      "orientation": "upright"
    }
  ],
  "unlocked": true
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

GET/api/v1/tarot/reading/{reading_id}/interpretation

Reading interpretation

Unlock the full AI interpretation for a reading id (consumes the matching one-time purchase on the web product; via API it is billed per call).

2 credits per call

Parameters

Name	Type	In	Required	Description
reading_id	string	path	required	UUID returned by POST /reading

Example request

cURL

curl "https://api-rho-eight-42.vercel.app/api/v1/tarot/reading/{reading_id}/interpretation" \
  -H "X-API-Key: kundli_abc123..."

Example response

JSON

{
  "reading_id": "9f2a1c4e-6b3d-4a5f-8e7c-2d1a3b4c5d6e",
  "interpretation": {
    "summary": "A period of quiet preparation is paying off...",
    "positions": [
      {
        "position": "Past",
        "text": "The Hermit marks a retreat..."
      }
    ]
  }
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

GET/api/v1/tarot/spreads

Spread configurations

List every supported spread with its positions and card counts — use it to render your own spread picker UI.

1 credit per call

Parameters

No parameters — call it as-is.

Example request

cURL

curl "https://api-rho-eight-42.vercel.app/api/v1/tarot/spreads" \
  -H "X-API-Key: kundli_abc123..."

Example response

JSON

{
  "three_card": {
    "name": "Three-Card Spread",
    "card_count": 3,
    "positions": [
      "Past",
      "Present",
      "Future"
    ]
  },
  "celtic_cross": {
    "name": "Celtic Cross",
    "card_count": 10,
    "positions": [
      "Present",
      "Challenge",
      "Past"
    ]
  }
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

GET/api/v1/tarot/deck

Card reference deck

The complete 78-card reference: names, arcana, suits, keywords and upright/reversed meanings for rendering your own cards.

1 credit per call

Parameters

No parameters — call it as-is.

Example request

cURL

curl "https://api-rho-eight-42.vercel.app/api/v1/tarot/deck" \
  -H "X-API-Key: kundli_abc123..."

Example response

JSON

[
  {
    "card_id": "0",
    "name": "The Fool",
    "arcana": "major",
    "keywords": [
      "beginnings",
      "innocence",
      "spontaneity"
    ],
    "upright": "New beginnings, spontaneity...",
    "reversed": "Recklessness, poor judgment..."
  }
]

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

Need a key?

Create one from your dashboard and paste it into any example above — every snippet is ready to run.

Get an API key