POSTalphaExperience APIs

Tarot Draw

Draw and interpret tarot spreads from the local 78-card Rider-Waite-Smith corpus with deterministic seed support and paid API metering.

POST /v1/tarot/drawQuickstartOpenAPI JSON
Credits

2 credits per spread

Minimum Plan

Basic+

Billing Lane

Light AI

SDK Helper

tarotDraw / tarot_draw

Inputs
  • +question
  • +spread type
  • +topic
  • +optional seed
  • +image prompt flag
Outputs
  • +drawn cards
  • +card readings
  • +direct answer
  • +synthesis
  • +next action
Tool Functions

Capabilities behind this endpoint

3 functions
tarot.spread.draw

Draws cards deterministically from the local 78-card corpus.

tarot.meanings.apply

Uses local card meanings as interpretation context.

tarot.output.lock

Locks the final response to the actual drawn cards.

Three Card Spread request
{
  "question": "What do I need to know about this relationship?",
  "spread_type": "three_card",
  "topic": "love",
  "seed": "partner-reading-001"
}
Three Card Spread response
{
  "request_id": "req_...",
  "data": {
    "spread": {
      "type": "three_card",
      "cards": [
        { "name": "The Lovers", "position": "situation", "orientation": "upright" }
      ]
    },
    "answer": "The connection is real, but the choice must become conscious."
  },
  "usage": { "lane": "ai", "credits": 2, "billableUnits": 1 }
}
curl
curl https://theleokingai.com/api/v1/tarot/draw \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tarot-draw-subject-123-v1" \
  -d '{
  "question": "What do I need to know about this relationship?",
  "spread_type": "three_card",
  "topic": "love",
  "seed": "partner-reading-001"
}'
Node SDK
import { TheLeoKingApi } from "@theleoking/ai-api";

const api = new TheLeoKingApi({
  apiKey: process.env.LEOKING_API_KEY,
  baseUrl: "https://theleokingai.com/api"
});

const result = await api.tarotDraw(
  {
  "question": "What do I need to know about this relationship?",
  "spread_type": "three_card",
  "topic": "love",
  "seed": "partner-reading-001"
},
  "tarot-draw-subject-123-v1"
);

console.log(result.request_id);
console.log(result.usage.credits);
Python SDK
import os
from theleoking_ai_api import TheLeoKingApi

api = TheLeoKingApi(
    api_key=os.environ["LEOKING_API_KEY"],
    base_url="https://theleokingai.com/api",
)

result = api.tarot_draw(
    {
        "question": "What do I need to know about this relationship?",
        "spread_type": "three_card",
        "topic": "love",
        "seed": "partner-reading-001",
    },
    idempotency_key="tarot-draw-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])
Error Behavior
HTTPCodePartner Action
400INVALID_REQUESTFix the payload shape, enum value, required field, or request body before retrying.
401AUTH_REQUIREDSend x-api-key from a trusted server environment. Do not expose keys in browser code.
401AUTH_INVALIDCheck the key prefix, rotate compromised keys, and verify the target environment.
402CREDITS_EXHAUSTEDUpgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403AUTH_FORBIDDENUse a key scoped for this endpoint or upgrade to the required plan.
404NOT_FOUNDVerify the job id, environment, API key, and whether the job belongs to the same workspace.
409IDEMPOTENCY_CONFLICTReuse idempotency keys only for the same logical operation and identical request payload.
429RATE_LIMITEDBack off, retry later, reduce concurrency, or request enterprise limits.
Related Endpoints