Tarot API

Complete API reference for tarot-related endpoints.

Base URL

https://api.mysticalapi.com/v1

Endpoints

Daily Card

Draw a single tarot card for daily guidance.

Endpoint:

POST /tarot/daily-card

Request Body:

{
  "theme": "general",     // optional: general, love, career, spiritual
  "seed": "user123"       // optional: for deterministic draws
}

Response:

{
  "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"
  },
  "theme": "general_guidance",
  "seed_used": "user123",
  "meaning": "Contentment, satisfaction, wishes coming true..."
}

cURL Example:

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

JavaScript Example:

const response = await fetch('https://api.mysticalapi.com/v1/tarot/daily-card', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ theme: 'love' })
});
const data = await response.json();
console.log(`Your card: ${data.card.name}`);

Three Card Spread

Draw three cards in various spread patterns.

Endpoint:

POST /tarot/three-card

Request Body:

{
  "spread_type": "past_present_future",  // optional
  "theme": "love",                       // optional
  "seed": "reading123"                   // optional
}

Spread Types:

• past_present_future - Explore timeline of situation
• situation_action_outcome - Understand path forward
• mind_body_spirit - Holistic wellbeing perspective
• what_why_how - Deep understanding
• strength_weakness_advice - Balanced perspective

Response:

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

Example:

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

Celtic Cross Spread

Traditional 10-card comprehensive reading.

Endpoint:

POST /tarot/celtic-cross

Request Body:

{
  "theme": "general",     // optional
  "seed": "celtic123"     // optional
}

Response:

{
  "spread": {
    "type": "celtic_cross",
    "name": "Celtic Cross",
    "description": "The classic 10-card spread for comprehensive life insights"
  },
  "cards": [
    // Array of 10 positioned cards
  ],
  "patterns": {
    "majorArcanaCount": 4,
    "reversedCount": 3,
    "keyThemes": ["major_life_transition", "inner_work_needed"]
  },
  "theme": "general_guidance"
}

Custom Spread

Create your own spread with custom positions.

Endpoint:

POST /tarot/custom-spread

Request Body:

{
  "positions": [
    { "number": 1, "name": "Mind", "question": "What occupies my thoughts?" },
    { "number": 2, "name": "Heart", "question": "What do I feel?" },
    { "number": 3, "name": "Spirit", "question": "What is my spiritual message?" }
  ],
  "theme": "general",     // optional
  "seed": "custom123"     // optional
}

Response:

{
  "spread": {
    "type": "custom_spread",
    "name": "Custom Spread",
    "description": "Custom 3-card spread with user-defined positions",
    "cardCount": 3,
    "positions": [...]
  },
  "cards": [
    // Array of positioned cards with custom meanings
  ]
}

Health Check

Check tarot service status.

Endpoint:

GET /tarot/health

Response:

{
  "status": "ok",
  "service": "tarot"
}

Error Responses

All endpoints may return these error responses:

• 400 Bad Request - Invalid request parameters
• 405 Method Not Allowed - Invalid HTTP method
• 429 Too Many Requests - Rate limit exceeded (100 req/min)
• 500 Internal Server Error - Server error

Error Format:

{
  "error": "Request validation failed",
  "requestId": "daily_1234567890_abc123",
  "timestamp": "2025-09-24T12:00:00.000Z"
}