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.
Build card-driven apps with bilingual references, artwork and spread layouts. Connect over REST or MCP.
Read the API reference ↗
Frankie returns structured card references and spread definitions. Your interface chooses the question, cards, upright or reversed orientation, interpretation and saved state.
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.
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.
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.
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
}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.
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.
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.
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.
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 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 ↗search_tarot_cardsget_random_tarot_cardsdraw_tarot_spreadget_tarot_cardlist_tarot_spreadsPrimary 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.
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.
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.
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