Getting Started

Welcome to the Mystical API! This guide will help you get up and running with tarot readings and astrological calculations.

Overview

The Mystical API provides:

• Tarot Card Readings - Daily cards, spreads, and Celtic Cross
• Astrology Services - Birth chart calculations and planetary positions
• Clean REST API - Simple, intuitive endpoints
• No Authentication - Open beta access
• High Performance - Sub-200ms response times

Base URL

All API endpoints use this base URL:

https://api.mysticalapi.com/v1

Quick Start

1. Check the API Status

Verify the API is running:

curl https://api.mysticalapi.com/v1/

Response:

{
  "name": "Mystical API",
  "version": "1.0.0",
  "status": "operational",
  "endpoints": {
    "tarot": {
      "daily_card": "POST /tarot/daily-card",
      "three_card": "POST /tarot/three-card",
      "celtic_cross": "POST /tarot/celtic-cross",
      "custom_spread": "POST /tarot/custom-spread",
      "health": "GET /tarot/health"
    },
    "astrology": {
      "natal_chart": "POST /astrology/natal-chart",
      "health": "GET /astrology/health"
    }
  }
}

2. Get Your First Tarot Card

Draw a daily tarot card:

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

3. Try a Three Card Spread

Get a more detailed reading:

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

Available Endpoints

Method	Endpoint	Description
GET	/	API information
GET	/tarot/health	Tarot service health
POST	/tarot/daily-card	Daily card reading
POST	/tarot/three-card	Three card spread
POST	/tarot/celtic-cross	Celtic Cross (10 cards)
POST	/tarot/custom-spread	Custom spread
GET	/astrology/health	Astrology service health
POST	/astrology/natal-chart	Birth chart calculation

JavaScript Example

const API_BASE = 'https://api.mysticalapi.com/v1';

async function getDailyCard() {
  const response = await fetch(`${API_BASE}/tarot/daily-card`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      theme: 'career',
      seed: `daily-${new Date().toISOString().split('T')[0]}`
    })
  });

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

// Usage
getDailyCard().then(reading => {
  // Use the reading data
});

Python Example

import requests

API_BASE = 'https://api.mysticalapi.com/v1'

def get_daily_card(theme='general'):
    response = requests.post(
        f'{API_BASE}/tarot/daily-card',
        json={'theme': theme}
    )

    data = response.json()
    print(f"Your card: {data['card']['name']}")
    print(f"Meaning: {data['meaning']}")
    return data

# Usage
reading = get_daily_card('love')

Rate Limits

• Current: 100 requests/minute per IP
• No authentication required during open beta
• Rate limit headers included in all responses

Next Steps

• Tarot Reading Types
• API Reference
• Authentication (Coming Soon)