# Tarot Reading API

> Production-ready tarot card reading API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Complete 78-card Rider-Waite-Smith deck with domain-specific interpretations for love, career, health, and spiritual growth. Celtic Cross, three-card, love, career, yes/no oracle, daily card, and custom spreads. Seeded reproducibility for personalized daily readings. Card images included. 10+ endpoints optimized for tarot apps, AI tarot chatbots, fortune-telling platforms, and spiritual wellness products.

Launch a tarot reading app with 78-card authenticity. In days.

- Product page: https://roxyapi.com/products/tarot-api
- OpenAPI spec: https://roxyapi.com/api/v2/tarot/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/tarot
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 10+

## Features

- Complete 78-card Rider-Waite-Smith deck: 22 Major Arcana + 56 Minor Arcana with upright and reversed meanings, domain interpretations (love, career, health, spiritual), and rich symbolism
- Traditional spreads: Three-Card (past/present/future), Celtic Cross (10-card), Love (5-card relationship), Career (7-card SWOT), plus custom spread builder (1-10 positions)
- Yes/No oracle readings with Major Arcana weighted answers (Yes, No, Maybe) and detailed reasoning for quick decision-making features in apps and chatbots
- Daily tarot card with seeded reproducibility, date-based consistency for personalized daily readings, and share-friendly deterministic draws
- High-quality Rider-Waite card images (345x480px JPEG) served via CDN with card descriptions, keywords, and imagery metadata for professional tarot app UIs
- AI-optimized JSON responses with structured card data, spread positions, and contextual interpretations, perfect for MCP-powered tarot chatbots and LLM integration
- Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter

## Use Cases

- Build tarot reading apps with authentic Rider-Waite-Smith interpretations: upright and reversed meanings for all 78 cards with domain-specific guidance for love, career, health, and spiritual growth
- Add daily tarot features to wellness and self-discovery platforms: date-based seeded draws ensure consistent personalized cards each day with shareable results
- Build AI tarot chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers tarot endpoints and delivers conversational readings with zero integration code
- Power career and life coaching platforms with Celtic Cross (10-card), SWOT career spreads, and yes/no oracle readings for decision-making and guidance features
- Create relationship and dating app features with love spreads analyzing emotional dynamics, compatibility, challenges, and partnership potential
- Ship fortune-telling and divination platforms combining tarot with astrology, numerology, dreams, and I-Ching for comprehensive spiritual guidance under one API key

## Languages

en, de, es, fr, hi, pt, ru, tr

## Endpoints

- `GET /api/v2/tarot/cards` List all 78 tarot cards
- `GET /api/v2/tarot/cards/{id}` Get detailed tarot card information
- `POST /api/v2/tarot/draw` Draw random tarot cards with reproducible results
- `POST /api/v2/tarot/daily` Get daily tarot card reading
- `POST /api/v2/tarot/yes-no` Get yes/no answer to your question
- `POST /api/v2/tarot/spreads/three-card` Three-Card Spread: Past, Present, Future
- `POST /api/v2/tarot/spreads/celtic-cross` Celtic Cross Spread (10 cards)
- `POST /api/v2/tarot/spreads/love` Love Spread (5 cards)
- `POST /api/v2/tarot/spreads/career` Career Spread (7 cards)
- `POST /api/v2/tarot/spreads/custom` Custom Spread Builder

## Example Response

```
POST /api/v2/tarot/yes-no
```

```json
{
  "question": "Should I accept the job offer?",
  "answer": "Yes",
  "strength": "Strong",
  "card": {
    "id": "the-star",
    "name": "The Star",
    "arcana": "major",
    "reversed": false,
    "keywords": [
      "hope",
      "inspiration",
      "renewal",
      "serenity"
    ],
    "imageUrl": "https://roxyapi.com/img/tarot/major/star.jpg"
  },
  "interpretation": "Strong Yes: The Star suggests forward momentum. Hope and renewal are flowing into your situation. Trust the path ahead..."
}
```

## Quick Start

```bash
curl -H "X-API-Key: ${ROXY_API_KEY}" -H "Content-Type: application/json" \
  https://roxyapi.com/api/v2/tarot/...
```

For full request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/tarot/openapi.json.