API Reference

Welcome to the Mystical API documentation. This API provides comprehensive tarot reading services and astrology calculations.

Base URL

https://api.mysticalapi.com/v1

Quick Start

1. Check Status - Verify the API is running
2. Draw Cards - Get tarot card readings
3. Calculate Charts - Generate astrological insights

# Check API status
curl https://api.mysticalapi.com/v1/

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

# Get daily horoscope (New in Week 7!)
curl -X POST https://api.mysticalapi.com/v1/astrology/daily-horoscope \
  -H "Content-Type: application/json" \
  -d '{"sign": "leo", "date": "today", "style": "brief"}'

Endpoints Overview

Tarot Services

Endpoint	Method	Description
/tarot/health	GET	Service health check
/tarot/daily-card	POST	Draw a single card
/tarot/three-card	POST	Three card spread
/tarot/celtic-cross	POST	Celtic Cross spread (10 cards)
/tarot/custom-spread	POST	Custom spread layout

Astrology Services

Endpoint	Method	Description	New in Week 7
/astrology/health	GET	Service health check	-
/astrology/natal-chart	POST	Calculate birth chart with advanced house systems	✓ Enhanced
/astrology/daily-horoscope	POST	Generate AI-powered daily horoscope	✓ New

System

Endpoint	Method	Description
/	GET	API information and status

Authentication

The API is currently in open beta and does not require authentication.

Response Format

All responses return JSON with appropriate HTTP status codes:

{
  "card": {
    "id": "cu09",
    "name": "Nine of Cups",
    "arcana": "Minor Arcana",
    "suit": "cups",
    "orientation": "upright"
  },
  "theme": "general_guidance",
  "seed_used": "anonymous_2025-09-24"
}

Error Handling

Errors return appropriate HTTP status codes with enhanced error details:

New Error Codes (Week 7+):

{
  "error": {
    "code": "INVALID_ZODIAC_SIGN",
    "message": "Invalid zodiac sign 'invalid'. Must be one of: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces",
    "details": {
      "provided": "invalid",
      "valid_options": ["aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"]
    }
  },
  "requestId": "daily_1234567890_abc123",
  "timestamp": "2025-09-24T12:00:00.000Z"
}

Common Error Codes:

• INVALID_ZODIAC_SIGN - Invalid zodiac sign provided
• UNSUPPORTED_HOUSE_SYSTEM - Unsupported house system requested
• RATE_LIMIT_EXCEEDED - Request rate limit exceeded
• INVALID_DATE_FORMAT - Invalid date format provided
• HIGH_LATITUDE_DETECTED - High latitude fallback applied (info level)

Rate Limiting

Updated Week 8 Limits:

• Daily Horoscope: 60 requests/minute per IP, 1000/day
• Natal Charts: 30 requests/minute per IP, 500/day
• Tarot Endpoints: 100 requests/minute per IP
• Health Checks: 120 requests/minute per IP
• No authentication required during beta
• Rate limit headers included in all responses

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995260