Get a 3-card tarot reading

Draws 3 random cards (Past / Present / Future) and generates an AI interpretation via Claude Sonnet. Real-time response (~4s) - this is synchronous, the full result is returned in the POST response (no polling). Saved permanently.

Request: Bearer token | optional header X-Enforce-Paywall: true

Body: question (optional, max 300 chars)

Success: 200 - data contains reading_key (Tarot-XXXXX), cards[] (3 cards: position [Past/Present/Future], name, slug, image_url, orientation, meaning), and ai_interpretation (text). Also returns 200 with success: false and code: PLAN_LIMIT (not an HTTP error) when X-Enforce-Paywall: true is sent and no unconsumed tarot-reading purchase exists (get one via POST /subscriptions/checkout with slug tarot-reading first - checkout never generates the reading itself, this endpoint is always the separate step-2 call, paid or free-via-coupon; every 3-card reading consumes its own credit - there's no free-forever unlock, unlike the other one-time reports). If a purchase is still pending (paid moments ago, webhook not yet processed), this call reconciles it against Razorpay live before deciding - if confirmed paid the credit activates and the reading proceeds normally; if not, the message is "We're still verifying your payment..." instead of the plain "this report needs to be purchased" text shown when no attempt exists at all

A failed call never consumes the credit: the reading row is only ever written to the DB AFTER the AI interpretation succeeds - if this call errors (e.g. 503 when Claude is unavailable), nothing was saved and the purchased credit is untouched. Just call this endpoint again with the same purchase - no need to call POST /subscriptions/checkout again first.

Errors: 401 - expired/invalid token | 406 - missing/revoked token | 404 - user not found | 503 - AI temporarily unavailable, retry (credit not consumed, see above)

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Successful Response

Bodyapplication/json

Example

{
    "success": true,
    "message": "Success",
    "data": {
        "reading_key": "Tarot-44290",
        "cards": [
            {
                "position": "Past",
                "name": "The Chariot",
                "slug": "the-chariot",
                "image_url": "https://cdn.hastaai.in/tarot/the-chariot.jpg",
                "orientation": "upright",
                "meaning": "Victory, determination, willpower.",
                "takeaway": "Career: the discipline that won your past battles is still your greatest asset."
            },
            {
                "position": "Present",
                "name": "The Hierophant",
                "slug": "the-hierophant",
                "image_url": "https://cdn.hastaai.in/tarot/the-hierophant.jpg",
                "orientation": "upright",
                "meaning": "Tradition, guidance, beliefs.",
                "takeaway": "Guidance: seek advice from someone you trust before deciding."
            },
            {
                "position": "Future",
                "name": "The Empress",
                "slug": "the-empress",
                "image_url": "https://cdn.hastaai.in/tarot/the-empress.jpg",
                "orientation": "upright",
                "meaning": "Fertility, abundance, nurturing.",
                "takeaway": "Growth: a season of abundance is coming - keep tending what you've planted."
            }
        ],
        "ai_interpretation": "Your past was driven by The Chariot's sheer willpower - you fought hard and won through discipline. The Hierophant now invites you to seek wisdom beyond your own effort, leaning on tradition and trusted guidance. The Empress ahead promises a season of abundance and creativity that blooms from what you have patiently tended."
    }
}

🟠401Unauthorized

🟠404Record Not Found

🟠406Parameter Error

🟠422Parameter Error