Authentication

Current Status

The Mystical API is currently in open beta and does not require authentication. All endpoints are publicly accessible.

Making Requests

Simply make requests to the API endpoints:

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

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

Rate Limiting

Instead of authentication, the API uses IP-based rate limiting:

• Current: 100 requests/minute per IP address
• Daily: No daily limits during beta
• Headers: Rate limit info included in response headers

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Coming Soon: API Keys

API key authentication will be added in the future. When implemented, requests will look like:

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

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

Future API Tiers

When authentication is implemented, these tiers are planned:

Free Tier

• 1,000 requests/month
• Basic endpoints only
• Standard rate limits

Pro Tier

• 10,000 requests/month
• All endpoints
• Higher rate limits
• Priority support

Enterprise

• Unlimited requests
• Custom rate limits
• SLA guarantees
• Dedicated support

Error Handling

Currently, the main authentication-related error is rate limiting:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests from this IP",
  "requestId": "req_123456789",
  "timestamp": "2025-09-24T12:00:00.000Z"
}

Best Practices

While no authentication is required, follow these best practices:

1. Respect Rate Limits

Don't make excessive requests. Spread them out over time.

2. Use Deterministic Seeds

For consistent results, use meaningful seeds:

// Good: predictable daily reading
const seed = `daily-${new Date().toISOString().split('T')[0]}`;

// Good: user-specific reading
const seed = `user-${userId}-${Date.now()}`;

3. Handle Errors Gracefully

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

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to get daily card:', error);
    throw error;
  }
}

4. Cache Responses

Consider caching API responses to reduce requests:

// Cache daily card for 24 hours
const CACHE_KEY = `daily-card-${new Date().toISOString().split('T')[0]}`;
const cachedCard = localStorage.getItem(CACHE_KEY);

if (cachedCard) {
  return JSON.parse(cachedCard);
} else {
  const card = await getDailyCard();
  localStorage.setItem(CACHE_KEY, JSON.stringify(card));
  return card;
}

Stay Updated

• Join our mailing list for API key availability announcements
• Follow the API status page for updates
• Check this documentation regularly for authentication changes

Next Steps

• Getting Started
• Tarot Readings
• API Reference