Selected-card Tarot Interpretation API
Connect a physical deck, your own card picker or an existing reading to the same 78-card meaning corpus. Submit the observed cards in order and receive original interpretations without drawing a new set.
POST /v1/tarot/interpretations50,000 monthly credits · 12 response languages · predictable request pricing. Plan details ↗
What this API provides.
Turn the cards your user actually selected into localized interpretations, keeping their positions, orientations and saved reading identity intact.
Submitted order and repeated observations preserved
Immutable reading_id for saved retrieval and idempotent replay
Portable JSON export with an integrity digest
Send
- Read the stable IDs from GET /v1/tarot/cards
- Send cards with card_id, upright/reversed orientation and a position label
- Choose locale and an optional spread_name; use a stable Idempotency-Key
Receive
- The exact supplied cards with original localized meanings
- reading_id, source facts and corpus/method versions
- Tenant-scoped saved reading and self-contained JSON export
Real input. Real output.
Explore a completed engine response using fictional sample data. Adapt the request to your application and use the JSON to build your interface.
{
"locale": "en",
"cards": [
{
"card_id": "major_lovers",
"orientation": "upright",
"position": "connection"
},
{
"card_id": "swords_03",
"orientation": "reversed",
"position": "reflection"
}
]
}{
"request_id": "50f5c205fa97f8ba9c7a3b77dc843f4e",
"api_version": "v1",
"locale": "en",
"data": {
"reading_id": "50f5c205fa97f8ba9c7a3b77dc843f4e",
"spread": "custom",
"cards": [
{
"fact_id": "tarot.card.1",
"position": "connection",
"card_id": "major_lovers",
"number": 6
},
{
"fact_id": "tarot.card.2",
"position": "reflection",
"card_id": "swords_03",
"number": 3
}
],
"method": {
"algorithm": "user-supplied-cards-v1",
"selection": "user_supplied",
"random_draw": false,
"order": "submitted_order",
"repeated_cards": "preserved_as_supplied",
"deck_id": "celestack-standard-78",
"corpus": "celestack-original-compositional-v1"
}
},
"interpretation": {
"locale": "en",
"kind": "tarot/interpretations",
"disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
"coverage": {
"total_facts": 2,
"selected_facts": 2,
"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": "connection",
"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 preview highlights selected fields. Download the complete JSON for every value, array and interpretation; credits_used shows the cost of this operation.
cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/tarot/interpretations' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: tarot-interpretation-api-example-001' \
--data '{
"locale": "en",
"cards": [
{
"card_id": "major_lovers",
"orientation": "upright",
"position": "connection"
},
{
"card_id": "swords_03",
"orientation": "reversed",
"position": "reflection"
}
]
}'Example computed 2026-11-18. Full fixture manifest, engine versions and SHA-256 checksums ↗
Ways to use it.
- Interpret a user’s physical or custom on-screen draw
- Restore the same reading across sessions and devices
- Ground an AI follow-up in saved card facts
12 response locales
English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.
Calculation values remain language-independent. Machine-readable field names stay stable across languages. Review localized interpretations as part of your product’s editorial workflow.
Calculation notes.
- This endpoint interprets the supplied observations; repeated card IDs remain repeated observations.
- Hosted JSON is retained for seven days. Export and keep your own JSON for longer use. Its SHA-256 digest detects changes and is not a proof-of-origin signature.
- Card metadata and original meanings are provided; artwork is supplied by your own licensed deck.
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. Choose the billing schedule that fits your build, or talk to us about custom capacity.
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.
Does this draw different cards?
Your supplied IDs, orientations, labels and order are preserved. There is no random draw or seed in this endpoint.
How do I restore a reading?
Use GET /v1/tarot/readings/{reading_id} with a read-scoped key from the owning organization. The /export suffix returns portable JSON. The SDK can restore your own exported file locally after hosted retention ends.
What do repeated reads cost?
Saved retrieval and export consume no calculation credits and never create a new reading. A new interpretation request uses one credit; idempotent replay reuses the existing result.
What does access cost?
Access is USD 39.99 per month or USD 299 billed annually. 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.