FrankieTarot API

Tarot data.
Your reading.

Build card-driven apps with bilingual references, artwork and spread layouts. Connect over REST or MCP.

Read the API reference ↗
The Fool
0The Fool
The Fool, from the actual redraw artwork. This is a fixed catalog example, not a draw.

The catalog is one part of a reading.

Frankie returns structured card references and spread definitions. Your interface chooses the question, cards, upright or reversed orientation, interpretation and saved state.

A bilingual card catalog

Retrieve names, keywords, descriptions, upright and reversed meanings, three artwork URLs and source details. Stable IDs such as maj00 identify the same card across languages.

Layouts with a purpose

Each spread supplies its card count, ordered position labels and any per-position card pool. The Court spread, for example, asks for a pip card, a court card and a major arcana card.

The same data for an agent

Five UI-free MCP tools expose search, lookup, spread definitions and optional draws. The service does not call a language model or produce a personalized interpretation.

78
cards
11
spreads
en / zh-CN
locales

Start with a known card.

A deterministic lookup is a useful first request. This abbreviated example uses real catalog fields; the live response also contains meanings, artwork URLs and provenance.

Open the live response ↗
curl "https://tarot-api.songhai.site/api/v1/cards/maj00?locale=en"
{
  "id": "maj00",
  "name": "The Fool",
  "names": {
    "en": "The Fool",
    "zh-CN": "愚人"
  },
  "arcana": "MAJOR",
  "suit": null,
  "rank": 0
}

Explore a definition, without drawing.

This small adaptation of the real SpreadLayout component uses the current source dataset. The numbered shapes are positions, not selected cards. Nothing is sent or saved.

    Your first integration

    1. Load the references

      Fetch cards and spreads in en or zh-CN. The default locale is zh-CN; the catalog has no pagination. No service API key is required.

    2. Keep manual choice in your app

      Let the user select a spread and cards, then look up those IDs. The independent Frankie Tarot app provides the interactive table; this service provides its references.

    3. Use automatic draws only by choice

      The optional random-card and spread-draw endpoints create a new sample. Draw only after the user explicitly delegates that action. A reading topic alone does not choose cards for them.

    4. Retain the successful result

      Save card IDs, positions, orientation and the exact definition in the caller. There is no public seed, idempotency key or recovery endpoint; an uncertain retry is a new draw.

    REST for apps. MCP for tools.

    REST offers read-only GET endpoints with CORS. Agent MCP uses Streamable HTTP at /mcp/agent and returns structured content. It is a tool service, not a ChatGPT visual widget or an account system.

    Agent guide ↗

    Official MCP transport & tool concepts ↗

    Registered tools

    • search_tarot_cards
    • get_random_tarot_cards
    • draw_tarot_spread
    • get_tarot_card
    • list_tarot_spreads

    Inside the current reference

    Know what the reference means.

    Source layers stay visible

    Primary meanings carry cited PKT 1911 English passages and editorial Chinese summaries. modernMeanings preserves project-curated extensions; artistic variants, keywords and descriptions are also curated. Read provenance rather than assuming every field is a historical quotation.

    No hidden reading database

    The service has no database or model API dependency. Reading history, recovery, consent, interpretation and orientation belong to the caller. Symbolic meanings are not factual predictions or probabilities.

    Structured failures

    Invalid queries return 400, unknown cards or spreads return 404, and unsupported REST API methods return 405. Handle the error response rather than inventing a successful result.

    Run the service locally

    REST and Agent MCP run at http://127.0.0.1:3001. The separate Vite command edits the full API reference; a static server alone does not run the service.

    Screenshot & contract update guide ↗
    npm ci
    npm run api