TAROT · JSON REST API

Tarot Reading API

Request structured card draws with original symbolic text. Card identity, spread position, orientation and meaning remain separate fields, making the result easy to display in your own design.

AvailablePOST /v1/tarot/readings

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Draw from 78 Tarot cards with reproducible seeds, five spread options and original upright/reversed meanings in 12 languages. See actual draw JSON.

01

A full 78-card corpus with upright and reversed meanings

02

One-card, three-card, Celtic Cross and relationship spreads

03

Custom spreads with 1–12 named positions

04

Seed-reproducible sampling without replacement

Send

  • Choose spread and optional reversals
  • Provide a seed to reproduce a draw, or omit it for a fresh generated seed
  • Custom spreads require positions; select one of the 12 locales

Receive

  • cards with ID, name, suit, arcana, position and orientation
  • Original localized meanings and source facts
  • Algorithm, seed, corpus version and no-replacement metadata
ACTUAL REPRODUCIBLE DRAW

The cards in this result.

The first-card illustration is original site artwork. The API returns structured card identities and meanings, rather than an image deck.

VITHE LOVERS

Original geometric Lovers illustration

context · upright

The Lovers

Upright theme: choosing in line with shared values. Reflect on one practical choice that fits your circumstances.

present · reversed

Strength

Reversed theme: meeting difficulty with patient courage. Review the tension before deciding how to respond.

next_step · reversed

Queen of Cups

Reversed theme: blurred boundaries and emotional demands that feel overwhelming. Review the tension before deciding how to respond.

INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/tarot/readings
{
  "locale": "en",
  "spread": "three_card",
  "seed": "celestack-demo",
  "reversals": true
}
Response JSON · selected fields
{
  "request_id": "f16ac1108d1ba8fec227cbe98dca83b7",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "spread": "three_card",
    "cards": [
      {
        "fact_id": "tarot.card.1",
        "position": "context",
        "card_id": "major_lovers",
        "number": 6
      },
      {
        "fact_id": "tarot.card.2",
        "position": "present",
        "card_id": "major_strength",
        "number": 8
      }
    ],
    "method": {
      "algorithm": "sha256-counter-rejection-partial-fisher-yates-v1",
      "seed": "celestack-demo",
      "deck_size": 78,
      "replacement": false,
      "reversals": true,
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2"
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "tarot/readings",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 3,
      "selected_facts": 3,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "tarot.card.1",
        "title": "The Lovers",
        "text": "Upright theme: choosing in line with shared values. Reflect on one practical choice that fits your circumstances.",
        "source": {
          "id": "tarot.card.1",
          "type": "tarot_card",
          "card_id": "major_lovers",
          "position": "context",
          "orientation": "upright",
          "name": "The Lovers",
          "meaning": "Upright theme: choosing in line with shared values. Reflect on one practical choice that fits your circumstances."
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 1
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/tarot/readings' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: tarot-api-example-001' \
+  --data '{
  "locale": "en",
  "spread": "three_card",
  "seed": "celestack-demo",
  "reversals": true
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A Tarot card-draw app
  • Reflective prompts with developer-designed card artwork
  • Repeatable saved readings across sessions

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • Tarot is symbolic reflection and entertainment, not a verified prediction of events.
  • The endpoint returns card data and text, not a licensed third-party deck image collection. The geometric Lovers illustration shown here is original site artwork.
  • A supplied seed reproduces the draw; it must not be presented as a new random outcome each time.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Can the same card appear twice in one reading?

No. The draw samples without replacement from 78 cards. Spread position and orientation are returned for every selected card.

Can I reproduce a saved reading?

Yes. Preserve the seed, spread, reversals setting and relevant corpus/algorithm version. The documented SHA-256 counter algorithm produces the same selected sequence.

Are card images included in the API?

The calculation endpoint returns structured cards and original meanings. It does not supply a third-party image deck. You can use your own properly licensed artwork in your interface.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 1 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API