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.
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
tarot.spread.drawDraws cards deterministically from the local 78-card corpus.
tarot.meanings.applyUses local card meanings as interpretation context.
tarot.output.lockLocks 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
| HTTP | Code | Partner Action |
|---|---|---|
| 400 | INVALID_REQUEST | Fix the payload shape, enum value, required field, or request body before retrying. |
| 401 | AUTH_REQUIRED | Send x-api-key from a trusted server environment. Do not expose keys in browser code. |
| 401 | AUTH_INVALID | Check the key prefix, rotate compromised keys, and verify the target environment. |
| 402 | CREDITS_EXHAUSTED | Upgrade the plan, add credits, or switch to a lower-cost Core Compute route. |
| 403 | AUTH_FORBIDDEN | Use a key scoped for this endpoint or upgrade to the required plan. |
| 404 | NOT_FOUND | Verify the job id, environment, API key, and whether the job belongs to the same workspace. |
| 409 | IDEMPOTENCY_CONFLICT | Reuse idempotency keys only for the same logical operation and identical request payload. |
| 429 | RATE_LIMITED | Back off, retry later, reduce concurrency, or request enterprise limits. |
Related Endpoints