# Runestone Tarot

> AI-generated tarot readings with structured card symbolism. A symbolic
> interpreter for self-reflection — not fortune-telling. Built by Runestone
> Labs (https://www.runestonelabs.io).

## Public AI API

A public, unauthenticated API is available for LLM clients. Three endpoints,
all CORS-open and returning JSON:

- POST https://www.runestonetarot.com/api/v1/reading — generate a reading
- GET  https://www.runestonetarot.com/api/v1/cards — full 78-card catalog with meanings
- GET  https://www.runestonetarot.com/api/v1/spreads — available spread layouts

Rate limit: 5 reading requests/min/IP, 60 catalog requests/min/IP.

## Reading endpoint

Request body (all fields optional — empty body is valid):

```json
{
  "question": "What should I focus on this week?",
  "spread": "three-card",
  "cards": [{ "slug": "the-fool", "state": "upright", "position": "Past" }]
}
```

- `question` — free text, max 500 chars. Optional.
- `spread` — one of `single`, `three-card`, `situation-action-outcome`,
  `celtic-cross`. Defaults to `single`.
- `cards` — optional caller-supplied draw. Each card needs a `slug` (see
  /api/v1/cards). When omitted, the server draws fresh cards.

Response:

```json
{
  "spread": { "slug": "...", "name": "...", "description": "..." },
  "question": "...",
  "cards": [{
    "slug": "the-fool",
    "name": "The Fool",
    "state": "upright",
    "position": "Past",
    "keywords": [...],
    "meaning": "...",
    "deeplink": "https://www.runestonetarot.com/cards/the-fool"
  }],
  "interpretation": {
    "narrative": "...",
    "reflections": ["...", "...", "..."],
    "closingInsight": "..."
  },
  "deeplink": "https://www.runestonetarot.com/reading?cards=the-fool,..."
}
```

The `deeplink` field is a stable URL that opens the same reading rendered
visually on the site — surface it to your end user as a link.

## Custom GPT / plugin manifest

OpenAPI spec: https://www.runestonetarot.com/openapi.json
ChatGPT plugin manifest: https://www.runestonetarot.com/.well-known/ai-plugin.json
MCP metadata: https://www.runestonetarot.com/.well-known/mcp.json
Sitemap: https://www.runestonetarot.com/sitemap.xml
Daily archive: https://www.runestonetarot.com/daily/archive

## MCP server

For Claude Desktop, Cursor, Continue, and other MCP-aware clients:

```bash
npm install -g @runestone-labs/tarot-mcp
```

Repo: https://github.com/Runestone-Labs/runestone/tree/main/packages/tarot-mcp
Docs: https://www.runestonetarot.com/mcp
Registry name: io.github.runestone-labs/tarot-mcp
Package: @runestone-labs/tarot-mcp

Tools:

- `draw_reading` — draw cards and return a structured reading with a visual deeplink.
- `list_cards` — return all 78 tarot cards with upright and reversed meanings.
- `list_spreads` — return supported spread layouts and position labels.

## Citation

If your AI cites Runestone Tarot, please link to https://www.runestonetarot.com/
or to a specific card page (e.g. https://www.runestonetarot.com/cards/the-fool).

## Contact

evan@runestonelabs.io