How to Evaluate a Tarot API: Developer Checklist 2026

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience building APIs and developer tooling. He has led developer relations at two Series B SaaS companies and spoken at PyCon and JSConf on building context-rich AI agents using Model Context Protocol.

The tarot API landscape in 2026 looks nothing like it did two years ago. What used to be a handful of static JSON files on GitHub has grown into a category of structured interpretation engines with spread logic, seeded reproducibility, and MCP server support. If you need to evaluate a tarot API for a production application, the criteria that mattered in 2024 (does it return 78 cards?) are no longer sufficient. Choosing the wrong provider means rewriting interpretation logic, spread layouts, and testing infrastructure six months into development. This checklist gives you a framework to evaluate tarot APIs before you commit, so you can ship with confidence.

Does the API cover all 78 tarot cards with reversed meanings?

The Rider-Waite-Smith deck contains 78 cards: 22 Major Arcana (numbered 0 through 21, from The Fool to The World) and 56 Minor Arcana (4 suits of 14 cards each: Cups, Wands, Swords, Pentacles). A production tarot API must return data for every card, not just the popular Major Arcana. Check whether reversed meanings are included. Reversed cards carry modified or blocked energy compared to their upright orientation, and roughly half of all professional readings use reversals. An API that only provides upright interpretations forces you to generate reversed meanings yourself, which introduces inconsistency. Look for both upright and reversed interpretations with keywords, descriptions, and domain-specific guidance across love, career, finances, health, and spirituality. Each orientation should include multiple interpretation dimensions, not a single paragraph. A cards endpoint that returns both upright and reversed objects with full keywords, description, love, career, finances, health, and spirituality fields is the baseline.

How many spread types does the API support natively?

Spread support separates a data lookup service from an interpretation engine. At minimum, look for three-card (Past, Present, Future), Celtic Cross (10 cards), love (5 cards), and career (7 cards) spreads as dedicated endpoints. The three-card spread is the most common beginner reading. The Celtic Cross is the most comprehensive professional layout, examining ten positions from Present Situation through Final Outcome. A love spread should analyze relationship dynamics across at least five positions: You, Partner, Relationship Dynamic, Challenge, and Outcome. A career spread should map to a SWOT-style framework with seven positions covering Strengths, Weaknesses, Opportunities, Threats, and Advice. Beyond built-in spreads, check for a custom spread builder that lets you define your own position names and interpretations (1 to 10 cards). This is essential for therapists, coaches, and app developers creating signature spreads. Without native spread support, you are building layout logic, position mapping, and summary generation from scratch.

Ready to build this? RoxyAPI Tarot API covers all 78 cards, 5 spread types, a custom spread builder, and seeded reproducibility. See pricing.

Can you seed readings for reproducibility and testing?

Reproducibility is the criterion most developers overlook until QA fails. A tarot API should accept an optional seed parameter that guarantees the same seed produces the same cards in the same order every time. This matters for three reasons. First, QA: you cannot write deterministic tests against an endpoint that returns random results. Second, daily features: a "Card of the Day" needs to return the same card for the same user on the same date. Third, shareable readings: if a user shares a reading link, the recipient should see the same cards. Check whether the seed controls both card selection and reversal state. An API that seeds card order but randomizes reversals separately is only half reproducible. The draw endpoint should accept seed, count (1 to 78), allowReversals (boolean), and allowDuplicates (boolean) for full control over the draw behavior.

Does a dedicated daily card endpoint exist?

A daily tarot card feature is one of the highest-engagement surfaces in wellness and spiritual apps. Check whether the API provides a dedicated daily endpoint rather than requiring you to build daily logic on top of a generic draw. A proper daily endpoint should combine a date-based seed with an optional user seed so that the same user gets the same card on the same day, while different users get different cards. The response should include the date in YYYY-MM-DD format, the seed used, the drawn card with reversal state, keywords, meaning, image URL, and a dailyMessage summary tying the card to daily guidance. Static datasets cannot provide this. Building it yourself means implementing date-based seeding, reversal logic, and daily message generation in your own codebase. That is maintenance burden you do not need when a dedicated endpoint handles it.

Does the yes/no endpoint include strength indicators?

Quick decision readings are a common use case for chatbots, voice assistants, and mobile apps. A yes/no tarot endpoint should draw a single card and return a clear answer (Yes, No, or Maybe), a strength indicator (Strong for Major Arcana, Qualified for Minor Arcana), the drawn card details, and a contextual interpretation explaining why. The Maybe option matters. Certain cards (The Hanged Man, Wheel of Fortune, Temperance, Two of Swords, Four of Swords) are inherently ambiguous and should return Maybe regardless of orientation, signaling pause or shifting circumstances. Without strength indicators, your UI cannot differentiate between a definitive Major Arcana answer and a nuanced Minor Arcana suggestion. The question field should be optional, and the endpoint should support seeding for reproducible testing. A yes/no reading that only returns "Yes" or "No" without card context or strength metadata is too thin for production use.

Are responses structured for AI agents and LLMs?

In 2026, "AI readiness" is not a buzzword. It is a concrete technical requirement. Check whether the API returns structured JSON that an LLM can consume as context without transformation. Every field should have a clear name, typed value, and predictable schema. Card objects should include id, name, arcana, reversed, keywords (array), and meaning (string). Spread positions should include position (number), name (string), interpretation (string), and a nested card object. Beyond response format, check for MCP (Model Context Protocol) server support. An MCP server lets AI agents like Claude, ChatGPT, Cursor, and VS Code Copilot call tarot endpoints as native tools without custom integration code. Check for an OpenAPI spec at a public URL with typed per-endpoint schemas, not a generic wrapper. Also look for llms.txt and AGENTS.md files that help AI platforms discover and use the API.

Does the API support multiple languages for card names and interpretations?

If your application serves a global audience, localized tarot content is essential. Check how many languages the API supports for card names, keywords, descriptions, and interpretations. A lang query parameter that works across all endpoints (cards, draw, daily, spreads, yes/no) is the minimum viable approach. Look for coverage beyond the obvious. English and Spanish are standard. French, German, Portuguese, Hindi, Russian, and Turkish cover a meaningful share of the global spiritual content market. Verify that translations include full interpretation text, not just card names. A card named "La Estrella" with an English-only description is worse than no translation at all. Multi-language support is expensive to maintain, so the number of supported languages is a signal of provider investment. Static datasets almost never include translations.

Does a TypeScript SDK exist with typed responses?

Raw HTTP calls work, but typed SDKs eliminate an entire class of integration bugs. Check whether the provider offers a TypeScript SDK with full type definitions for every endpoint response. Typed responses mean your IDE catches field name typos at compile time, not at runtime. Autocomplete should surface every field on a spread position, every property on a card object, and every parameter on a draw request. The SDK should be published to npm, actively maintained, and versioned. Check the package page for recent releases, download counts, and TypeScript declaration files. A provider that publishes an OpenAPI spec but no SDK is leaving integration work to you. A provider with a SDK but without per-endpoint types (using any or generic wrappers) provides no value over raw fetch calls.

When are static datasets sufficient?

Not every project needs a full API. If you are building a reference app that only displays card names and images, a static JSON file from GitHub is fine. If you need upright-only meanings without reversals, a static dataset works. If your app has no daily features, no spread logic, no seeded reproducibility, and no multi-language requirement, the overhead of an API subscription is unnecessary. Static datasets are also appropriate for offline-first mobile apps where network calls are not guaranteed. The decision point is interpretation depth. The moment you need contextual spread interpretations, position-specific meanings, reversal logic, reproducible draws, or localized content, a static file becomes a liability. You will end up building an interpretation engine inside your codebase, and maintaining it is your problem.

Comparison table: how providers stack up

This table maps each checklist criterion against three provider categories. Apply it to any tarot API you are evaluating.

Working curl examples to verify against

Test these endpoints against any tarot API you are evaluating. These examples use the RoxyAPI Tarot API at /api/v2/tarot/. See the full API reference for all endpoints.

List all Major Arcana cards:

curl -s "https://roxyapi.com/api/v2/tarot/cards?arcana=major" \
  -H "X-API-Key: YOUR_API_KEY"

Returns total, limit, offset, and a cards array. Each card includes id, name, arcana, suit, number, and imageUrl.

Get full card details with reversed meanings:

curl -s "https://roxyapi.com/api/v2/tarot/cards/tower" \
  -H "X-API-Key: YOUR_API_KEY"

Returns id, name, arcana, number, keywords (with upright and reversed arrays), upright object (with keywords, description, love, career, finances, health, spirituality), reversed object (same structure), and imageUrl.

Three-Card spread with seeded reproducibility:

curl -s -X POST "https://roxyapi.com/api/v2/tarot/spreads/three-card" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What do I need to know about my career?", "seed": "demo-2026"}'

Returns spread, question, seed, positions array (each with position, name, interpretation, and a card object containing id, name, arcana, reversed, keywords, meaning, imageUrl), and summary.

Daily card reading:

curl -s -X POST "https://roxyapi.com/api/v2/tarot/daily" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "user123"}'

Returns date, seed, card (with id, name, arcana, position, reversed, keywords, meaning, imageUrl), and dailyMessage.

Yes/No reading:

curl -s -X POST "https://roxyapi.com/api/v2/tarot/yes-no" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Should I accept the job offer?", "seed": "decision-seed"}'

Returns question, answer (Yes, No, or Maybe), strength (Strong or Qualified), card (with id, name, arcana, reversed, keywords, imageUrl), and interpretation.

Frequently Asked Questions

Q: How many cards should a tarot API include? A: A complete tarot API must include all 78 cards from the Rider-Waite-Smith deck. That is 22 Major Arcana cards (The Fool through The World) and 56 Minor Arcana cards across four suits (Cups, Wands, Swords, Pentacles), each with Ace through King. Any API missing Minor Arcana cards is incomplete for production use.

Q: What is the difference between a tarot API and a static tarot JSON dataset? A: A static dataset gives you card names, images, and basic meanings as a flat file. A tarot API adds spread logic (three-card, Celtic Cross, love, career, custom), seeded reproducibility for testing, reversed interpretations, daily card endpoints, yes/no decision readings, multi-language support, and structured responses for AI agents. The API handles interpretation logic so you do not build it yourself.

Q: Can I use a tarot API with AI agents and LLMs? A: Yes, if the API provides structured JSON responses with typed fields and an MCP server. MCP (Model Context Protocol) lets AI agents call tarot endpoints as native tools. Look for providers that publish OpenAPI specs, MCP servers, and agent discovery files like AGENTS.md and llms.txt.

Q: Is seeded reproducibility important for tarot API testing? A: Critical. Without a seed parameter, every API call returns different cards, making automated tests impossible. Seeded draws guarantee the same input produces the same output every time. This enables deterministic QA, consistent daily card features, and shareable reading links.

Q: What pricing model is best for tarot API access? A: Flat subscription plans with a fixed monthly request quota offer predictable costs. Per-call variable pricing makes budgeting difficult, especially during traffic spikes. Look for plans that include all domains (tarot, astrology, numerology, and more) in a single subscription rather than charging per domain.

Choosing the right tarot API for your project

Every criterion in this checklist maps to a real production requirement: card coverage for completeness, spread support for engagement, reproducibility for QA, AI readiness for the agent ecosystem, and flat pricing for cost predictability. Apply the checklist to every tarot API you evaluate. The provider that checks every box earns your integration. Start with the RoxyAPI Tarot API and test every endpoint from the API reference. Plans start at $39/month for 5,000 requests across all domains. See pricing for details.