Saju API › Tarot API

Tarot API

Choose how many cards to draw (1 to 10) or a spread, and the API draws cards without repeats from a 78-card deck (22 Major and 56 Minor Arcana) and returns, as JSON, each card's upright or reversed position, keywords, meaning and card image URL. The product is called "Tarot". There is no AI interpretation; the meaning is the fixed text for each card.

Get Started guide Playground Pricing

Card count, spread and seed

Send either count or spread, not both. With a seed, the same seed, the same card count (or spread) and the same reversal setting always give the same cards; without one, every draw is random. lang chooses the language of card names, keywords and meanings.

Card images

imageUrl and cardBackUrl are 600px-wide WebP images scanned from the original 1909 Rider-Waite deck (Pamela Colman Smith, public domain). The URLs include a version, so they do not change. Show reversed cards by rotating the image 180 degrees.

Where to get an interpretation

Pass the drawn cards to an LLM API as input and write your own reading, or add tarot to a Saju Interpretation API request to read them together with the Saju (Four Pillars) reading.

Request example

{
  "spread": "past-present-future",
  "question": "올해 하반기에 이직해도 될까요?",
  "seed": "user-1042:2026-10-10"
}

Authentication uses the X-Partner-Api-Key header, and the base URL is https://api.hrum.ai/api/v1/partners/v1. Python and JavaScript examples and error handling are in the Get Started guide.

Response example (one card)

{
  "success": true,
  "data": {
    "lang": "ko",
    "count": 3,
    "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
    "reversedAllowed": true,
    "seed": "hrum-example-1",
    "cards": [
      {
        "position": 1,
        "positionLabel": "과거",
        "id": "wands_10",
        "name": "완드의 10",
        "nameEn": "Ten of Wands",
        "arcana": "wands",
        "reversed": true,
        "keywords": ["내려놓기", "위임", "해방"],
        "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.",
        "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp"
      }
    ],
    "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp",
    "question": "올해 하반기에 이직해도 될까요?",
    "costPoints": 20
  }
}

Pricing

Tarot costs ₩20 per call (excl. VAT; ₩22 incl. VAT). Drawing 1 card or 10 counts as one call. Only successful calls are deducted from prepaid credits; 4xx and 5xx error responses are not charged.

Store a result once you have it, and reuse it. Sending the same request again is charged again. The same birth date and time with the same options always gives the same result, so save the first response in your database (for example, keyed by a hash of the request body) and use the saved value from then on at no cost. For results that change by date, such as a daily fortune, include the date in the key and reuse the result for that day only.

Full pricing

Full reference

The full parameter table, response field descriptions and error codes are in the reference: Tarot API reference. Other Saju products are listed under All Saju APIs.

Contact: contact@float.do · Operated by FLOAT Co., Ltd.