TAROT · JSON REST API

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.

AvailablePOST /v1/tarot/interpretations

50,000 monthly credits · 12 response languages · predictable request pricing. Plan details ↗

Your cards. Their own story.Illustration
BUILD AROUND THE DATA

What this API provides.

Turn the cards your user actually selected into localized interpretations, keeping their positions, orientations and saved reading identity intact.

01

1–12 supplied card IDs, orientations and position labels

02

Submitted order and repeated observations preserved

03

Immutable reading_id for saved retrieval and idempotent replay

04

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
INSPECT BEFORE SUBSCRIBING

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.

Request JSON POST /v1/tarot/interpretations
{
  "locale": "en",
  "cards": [
    {
      "card_id": "major_lovers",
      "orientation": "upright",
      "position": "connection"
    },
    {
      "card_id": "swords_03",
      "orientation": "reversed",
      "position": "reflection"
    }
  ]
}
Response JSON · selected fields
{
  "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 ↗

YOUR PRODUCT, YOUR EXPERIENCE

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 CONVENTIONS

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 ↗

PREDICTABLE ACCESS

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.

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.

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.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API