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.
POST /v1/tarot/readings50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗
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.
One-card, three-card, Celtic Cross and relationship spreads
Custom spreads with 1–12 named positions
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
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.
Original geometric Lovers illustration
The Lovers
Upright theme: choosing in line with shared values. Reflect on one practical choice that fits your circumstances.
Strength
Reversed theme: meeting difficulty with patient courage. Review the tension before deciding how to respond.
Queen of Cups
Reversed theme: blurred boundaries and emotional demands that feel overwhelming. Review the tension before deciding how to respond.
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.
{
"locale": "en",
"spread": "three_card",
"seed": "celestack-demo",
"reversals": true
}{
"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 ↗
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.
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 ↗
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.
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.
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.