Tarot Readings Guide

Learn how to create different types of tarot readings with the Mystical API.

Overview

The Mystical API provides comprehensive tarot reading functionality with multiple spread types, deterministic seeding, and rich card data.

Reading Types

Daily Card Reading

The simplest reading - draw one card for daily guidance.

Basic Request:

const response = await fetch('https://api.mysticalapi.com/v1/tarot/daily-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({})
});

const data = await response.json();
console.log(`Your card: ${data.card.name}`);
console.log(`Meaning: ${data.meaning}`);

Themed Reading:

const response = await fetch('https://api.mysticalapi.com/v1/tarot/daily-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    theme: 'career',  // Focus on career matters
    seed: 'user123'   // Deterministic draw
  })
});

Available Themes:

• general - General life guidance
• love - Love and relationships
• career - Career and finance
• spiritual - Spiritual growth

Three Card Spreads

Multiple spread patterns for deeper insights.

Past, Present, Future:

const response = await fetch('https://api.mysticalapi.com/v1/tarot/three-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    spread_type: 'past_present_future',
    theme: 'love'
  })
});

Available Spread Types:

• past_present_future - Timeline of your situation
• situation_action_outcome - Path forward analysis
• mind_body_spirit - Holistic wellbeing
• what_why_how - Deep understanding
• strength_weakness_advice - Balanced perspective

Response Structure:

{
  "spread": {
    "type": "past_present_future",
    "name": "Past, Present, Future",
    "description": "Explore the timeline of your situation"
  },
  "cards": [
    {
      "id": "sw06",
      "name": "Six of Swords",
      "arcana": "Minor Arcana",
      "suit": "swords",
      "orientation": "upright",
      "position": {
        "number": 1,
        "name": "Past",
        "meaning": "Past influences and foundation"
      }
    }
    // ... 2 more cards
  ],
  "theme": "love",
  "seed_used": "reading123"
}

Celtic Cross

The most comprehensive spread with 10 cards.

const response = await fetch('https://api.mysticalapi.com/v1/tarot/celtic-cross', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    seed: 'reading123'
  })
});

Celtic Cross Positions:

1. Present Situation - The heart of the matter
2. Cross/Challenge - What crosses you, obstacles
3. Distant Past - Deep foundations, root causes
4. Recent Past - Recent events that led here
5. Possible Future - Potential outcomes
6. Immediate Future - What will likely happen next
7. Your Approach - Your attitude to the situation
8. External Influences - Outside forces, other people
9. Hopes and Fears - Inner hopes, dreams, anxieties
10. Final Outcome - Ultimate result and resolution

Custom Spreads

Create your own spread layout:

const response = await fetch('https://api.mysticalapi.com/v1/tarot/custom-spread', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    positions: [
      {
        number: 1,
        name: 'Mind',
        question: 'What occupies my thoughts?'
      },
      {
        number: 2,
        name: 'Body',
        question: 'What does my body need?'
      },
      {
        number: 3,
        name: 'Spirit',
        question: 'What is my spiritual message?'
      }
    ],
    seed: 'custom123'
  })
});

Deterministic Readings

Use seeds for consistent, reproducible readings:

// Same seed will always return the same cards
const dailySeed = `daily-${new Date().toISOString().split('T')[0]}`;

const reading1 = await fetch('https://api.mysticalapi.com/v1/tarot/daily-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ seed: dailySeed })
});

const reading2 = await fetch('https://api.mysticalapi.com/v1/tarot/daily-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ seed: dailySeed })
});

// reading1 and reading2 will be identical

Card Data Structure

Each card includes comprehensive information:

{
  "card": {
    "id": "cu09",
    "name": "Nine of Cups",
    "arcana": "Minor Arcana",
    "suit": "cups",
    "number": 9,
    "orientation": "upright",
    "keywords": ["contentment", "satisfaction", "wishes fulfilled"],
    "image_url": "https://storage.googleapis.com/mystical-api/cards/cu09.webp",
    "meaning_up": "Contentment, satisfaction, wishes coming true...",
    "meaning_rev": "Inner dissatisfaction, seeking deeper meaning...",
    "desc": "Traditional description and symbolism"
  }
}

Complete Examples

Daily Career Guidance

curl -X POST https://api.mysticalapi.com/v1/tarot/daily-card \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "career",
    "seed": "career-2025-09-24"
  }'

Relationship Timeline

curl -X POST https://api.mysticalapi.com/v1/tarot/three-card \
  -H "Content-Type: application/json" \
  -d '{
    "spread_type": "past_present_future",
    "theme": "love",
    "seed": "relationship-reading"
  }'

Life Path Analysis

curl -X POST https://api.mysticalapi.com/v1/tarot/celtic-cross \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "spiritual",
    "seed": "life-path-reading"
  }'

Next Steps

• API Reference
• Getting Started
• Authentication (Coming Soon)