API Guide

Curious how this API stack works in a real service? Try Saju analysis and AI chat in INTA – Life is Timing, an AI Saju (Four Pillars of Destiny) app that runs on the same engine. INTA is the live reference for this API. INTA's AI voice replies (TTS) run on the same stack too — a voice API is planned for later.

Quickstart

HRUM provides AI that remembers, Saju analysis and LLM resale. Follow these three steps:

The base URLs are https://api.hrum.ai (API) and https://console.hrum.ai (console). The old addresses api.float.do, console.float.do and api.inta.do still work, so if you already integrated, you don't need to change anything.

1. Get an API key - Sign up for the console and create a key on the API keys screen (the key is shown only once, right after you create it). The full path from sign-up to error handling is in the developer Get Started guide.
2. Send a request - Send a POST request following the example below.
3. Handle the response - Pull the Saju data out of the JSON response.

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

Watch your User-Agent: The default User-Agent of Python's standard urllib (Python-urllib/3.x) trips a security rule and gets 403 (error 1010). requests, the OpenAI SDK, Node and curl work fine. If you use urllib or your own HTTP client, set a User-Agent: <app-name>/<version> header yourself. (Measured: python-requests passes · OpenAI/Python passes · node passes · Python-urllib 403)

Save money — store results and reuse them. Every successful request is billed separately. Manseryeok, Zi Wei Dou Shu, Compatibility, Astrology and Lifetime Saju results for the same birth date/time and the same options are identical every time, so store the first response in your DB (for example keyed by a hash of the request body) and use the stored value after that. For results that change by date, such as Today's Saju or Fortune Flow, include the date in the key. See Idempotency for details.

API Reference

HRUM provides AI that remembers, Saju analysis and LLM resale.

• Changed (2026-10-14): Korean response sentences now use one consistent polite style; no content or field changes
• Added (2026-10-14): If a time zone name is not recognized, a successful response carries warnings (UNKNOWN_TIMEZONE). Calculation still uses the default time zone as before, and with no warning the response is the same as before — Response warnings
• Added (2026-10-17): birth in AI Saju Reading, Reading Memory and Report now accepts the same birthplace, time zone and leap-month fields as the Manseryeok API (isLeapMonth, timezone, coordinates, country, zaSiRule, birthTimePrecision). If you don't send them, calculation is the same as before — AI Saju Reading API

RIDM Memory API

Hosts per-end-user conversation memory and adds a memory layer to ridm/* models. Memory is for ridm/* only; OpenAI/Google models are resold as is — same model, different product. Automatic YouTube transcript injection is also supported.

No sessions — one endless session. Call with the same user and the conversation simply continues. On every call the server automatically attaches the latest historyCount conversation turns and recallCount long-term memories (summary, profile, remembered facts, ongoing concerns), so you only need to send the one new message. Two numbers control how far back it looks, and memoryCap sets the maximum number of stored messages per end user. If you'd rather manage history yourself, omit historyCount and send the earlier conversation in messages the OpenAI way.

Long conversations don't get linearly more expensive. Older assistant turns are compressed automatically — the latest 2 turns stay verbatim, and earlier ones shrink step by step from 500 to 200 characters to save input tokens (user turns stay as they are). And when the user asks about something said earlier ("you told me ~ last time"), the server searches the stored conversation and quotes it with date and speaker (included in recalledMemories) — if there is no record, it says so instead of making something up.

LLM API (resale) vs RIDM Memory API — what's the difference

Same model, different product — only the prefix differs; everything else is the same. If the response carries recalledMemories and memorySaved, it went through the RIDM path.

Code example comparison

// LLM API (resale) — no memory
{
  "model": "openai/gpt-5.6-terra",
  "messages": [{ "role": "user", "content": "..." }]
}

// RIDM Memory API — with the memory engine
{
  "model": "ridm/gpt-5.6-terra",  // only the prefix differs
  "user": "user_123",              // required (keeps memory)
  "messages": [{ "role": "user", "content": "..." }]
}

// Difference in the response
// Resale: { "id": "...", "choices": [...], "usage": {...}, "costWon": 1, "costUsd": 0.00045 }
// RIDM: { "id": "...", "choices": [...], "usage": {...}, "costWon": 2, "recalledMemories": [...], "memorySaved": { "id": "turn-...", "keywords": [] } }

POST /api/v1/partners/v1/chat/completions

A conversational LLM call with memory. Calls with the same user/endUserId keep past context.

Request parameters

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/chat/completions \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ridm/gpt-5.6-terra",
    "user": "member-1024",
    "messages": [
      { "role": "user", "content": "Can we pick up where we left off about changing jobs?" }
    ]
  }'

Response example

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1629292800,
  "model": "ridm/gpt-5.6-terra",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 이전 대화를 기억하고 있어요..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 320,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "costWon": 45,
  "recalledMemories": [...],
  "memorySaved": { "id": "turn-1756200000000", "keywords": [] },
  "youtubeUsed": ["abc123def45"]
}

usage has no total_tokens — you get prompt_tokens, completion_tokens, prompt_tokens_details.cached_tokens, and for reasoning models completion_tokens_details.reasoning_tokens (already included in completion_tokens). memorySaved is the saved-turn object or null (cap exceeded, tool-call turn), and youtubeUsed is an array of the video IDs whose transcripts were injected (not URLs).

Streaming (SSE) format

With stream: true, the response comes as named SSE events, not OpenAI chunks. So the OpenAI SDK's stream parser can't read it — parse the SSE yourself (non-streaming responses are OpenAI-compatible).

event: chunk
data: {"delta":"안녕하세요"}

event: message_done
data: {"finish_reason":"stop","usage":{"prompt_tokens":1250,"completion_tokens":320,"prompt_tokens_details":{"cached_tokens":0}},"costWon":45,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]}}

data: [DONE]

Error codes

Codes this API returns in addition to the common errors. With stream: true, errors after the response has started come as event: error ({message, code, status}). Resale models follow the same table.

Notes

• YouTube transcript injection: With youtube:true, the transcript is extracted from the YouTube link in the last message and included in the input tokens. If no transcript can be fetched, the conversation continues without injection and youtubeUsed comes back as an empty array (only the standalone YouTube Summary API returns 400 with no charge).
• Original model compatibility: If the model value is openai/* or google/*, anthropic/*, the original model is called as is, without memory features (cost × exchange rate × 1.10).
• Prompt cache discount: On OpenAI-family models (openai/*, ridm/gpt-*), if you repeatedly send the same prefix (1,024 tokens or more), input tokens that hit the upstream cache are billed at 30% of the input price. You can check this in the response's usage.prompt_tokens_details.cached_tokens and in cachedTokens from GET /usage/logs; whether the cache hits can vary per call depending on upstream policy. Google models have no cache, so the full input price applies. Claude models don't request caching either, so the full input price applies.
• REPORT_ONLY_MODEL excluded: ridm/saju-report is one-shot only with no memory, so it can't be used on this endpoint (400).

Custom Profile

ridm/* models only. Stores and manages arbitrary field-name/value pairs per end user. You can save automatically extracted field values, set values yourself, or include specific fields in this turn's prompt. Values accumulate, and existing values are kept even if the schema changes (soft-update).

Request parameters (POST /api/v1/partners/v1/chat/completions)

Request example (RIDM chat)

{
  "model": "ridm/gpt-5.6-terra",
  "user": "enduser_123",
  "messages": [
    { "role": "user", "content": "Help me plan my kid's birthday party tomorrow" }
  ],
  "extractProfileFields": ["childAge", "interests", "budget", "constraints"],
  "injectProfileFields": ["name", "childAge", "interests"],
  "endUserProfile": {
    "name": "Jane Kim",
    "childAge": "7",
    "interests": "science, art"
  },
  "profileValueMaxChars": 200
}

Profile in the response

Responses to requests that sent profile parameters (message_done when streaming) carry a customProfile field.

"customProfile": {
  "injected": ["name", "childAge", "interests"],  // fields injected into this turn's prompt
  "stored": 4,                                     // number of fields currently stored
  "extractPending": ["budget"]                     // extraction targets that have no value yet
}

Delete API

To delete a specific field, send a DELETE request:

DELETE /api/v1/partners/v1/profile/{endUserId}/field/{key}
X-Partner-Api-Key: your-api-key

Response: { "success": true, "data": { "deleted": true } } — a missing key or an unknown endUserId still returns 200 with "deleted": false (no new end user is created). This API has no error codes of its own — only the common errors.

Limits and constraints

• Field cap: Up to 100 fields per end user. Beyond that, the oldest fields are removed first.
• Value length: 150 characters per field by default, up to 500. Adjustable with profileValueMaxChars.
• Cumulative storage: Values extracted with extractProfileFields accumulate; empty or null values are skipped and the existing value is kept. Fields are deleted only through the DELETE API above (or removed oldest-first automatically past 100). Values set with endUserProfile overwrite extracted values.
• Value length is per request: profileValueMaxChars is not stored and applies only to values stored in that request.
• Soft Update: Existing values are kept even if the schema (field names) changes, and are merged with new values on every call.
• ridm/* only: Resale models (openai/*, google/*) ignore the profile.

LLM API (resale)

Resale of original LLM models such as openai/* and google/* (no memory; original response as is). On resale model requests, user, systemPrompt, recallCount, memoryCap, summaryEvery, emotion and candor are ignored (put system instructions in messages as {"role":"system"}), and the response has no memory fields (recalledMemories etc.). Price = cost × exchange rate × 1.10.

Available models (same list as GET /api/v1/partners/v1/models)

• OpenAI (23): openai/gpt-6-astra · openai/gpt-6-sol · openai/gpt-6-luna · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4 · openai/gpt-5.4-mini · openai/gpt-5.4-nano · openai/gpt-5.2 · openai/gpt-5.1 · openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-4.1 · openai/gpt-4.1-mini · openai/gpt-4.1-nano · openai/gpt-4o · openai/gpt-4o-mini · openai/o3 · openai/o3-mini · openai/o4-mini
• Google (3): google/gemini-3.5-flash · google/gemini-3.5-flash-lite · google/gemini-3.1-pro
• Anthropic (13): See the Claude models section below
• RIDM: For each model above there is a memory model with the same name and a ridm/ prefix (resale price × 1.3), plus ridm/saju-report for Saju reports only (called only through /reading/report).

curl https://api.hrum.ai/api/v1/partners/v1/models \
  -H "X-Partner-Api-Key: your-api-key"

GET /api/v1/partners/v1/models response — not the OpenAI models.list format. Prices are in KRW (₩) per 1M tokens, and the numbers below are examples. Claude models appear in the list only when configured on the server.

{
  "success": true,
  "data": {
    "models": [
      { "modelId": "openai/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1234, "output_cost_krw": 9876, "category": "base" },
      { "modelId": "ridm/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1604.2, "output_cost_krw": 12838.8, "category": "ridm" }
    ]
  }
}

This API has no error codes of its own — only the common errors. It's free.

Thinking (reasoning) models and max_tokens: On models that use hidden thinking/reasoning, thinking tokens count toward the output limit. The server adds a margin to the call, but if max_tokens is very small (e.g. 16), the body may be empty with finish_reason: "length", and tokens consumed upstream are billed. We recommend at least 64. Affected models: openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1 · google/gemini-3.1-pro (including their ridm/ namesakes).

Thinking margin and billed tokens: For models where thinking can't be turned off (openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · google/gemini-3.1-pro) and models with thinking always on (anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1) (including their ridm/ namesakes), the server adds a thinking margin (up to 1,500 tokens) on top of your max_tokens to make sure you get an answer. Thinking tokens are billed at the output rate, so the output tokens actually billed can exceed max_tokens (e.g. a max_tokens 200 request billed 828 tokens: 747 thinking + 81 body). If you need a strict cost cap, use a model whose thinking turns off, such as google/gemini-3.5-flash.

POST /api/v1/partners/v1/chat/completions

Request parameters (no memory layer)

Usage example (OpenAI SDK compatible)

const client = new OpenAI({
  apiKey: 'your-float-api-key',
  baseURL: 'https://api.hrum.ai/api/v1/partners/v1',
  defaultHeaders: { 'X-Partner-Api-Key': 'your-float-api-key' }
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.6-terra',
  messages: [{ role: 'user', content: 'Hello' }]
});
// RIDM model example: model: 'ridm/gpt-5.6-terra'

Response

Non-streaming responses use the OpenAI-compatible schema plus costUsd, costWon and requestId. stream: true is not the OpenAI chunk format, so the OpenAI SDK's stream parser can't read it — parse it yourself following Streaming (SSE) format.

{
  "id": "chatcmpl-1791452814000",
  "object": "chat.completion",
  "created": 1791452814,
  "model": "openai/gpt-5.6-terra",
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0 } },
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" }
  ],
  "costUsd": 0.000162,
  "costWon": 1,
  "requestId": "resale-..."
}

Error codes are the same as in the RIDM Memory API error table. Resale models are also subject to the daily spending cap (RATE_LIMITED).

AI Saju Reading API

Generative AI analyzes a Saju (Four Pillars of Destiny) chart and returns a tailored interpretation and advice. Billed by tokens; returns only the interpretation.

POST /api/v1/partners/v1/reading

Generates an AI Saju reading from a Saju chart. The internal prompts and theory are not disclosed.

Request parameters

Request parameters — tools options

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Is this a good year to change jobs?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "maxLength": 600,
    "tone": "warm"
  }'

Response example

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "usage": {
      "inputTokens": 450,
      "outputTokens": 280
    },
    "costPoints": 18
  }
}

Response fields

Error codes

Codes this API returns in addition to the common errors:

Included modules — Zi Wei Dou Shu · Astrology · Dream Interpretation · Tarot

The Saju AI contains Saju, Zi Wei Dou Shu, astrology, Tarot and Dream Interpretation AIs. The day pillar of the date (today's energy) is reflected in every reading by default, without a separate call (no extra charge). One combined call reads everything together, using the calculated results of the included modules as evidence; leave out what you don't want with exclude. To call just the one AI you need, use only. If you only need the calculated results, you can call the same modules one by one through the calculation endpoints (/ziwei-chart · /astrology (Astrology Total) · /dream · /tarot) and build your own app. /reading/memory takes the same fields.

• Billing: On top of the usual token price (question + persona + evidence blocks of included modules, characters × 0.25 as input tokens, plus output tokens), each included module adds the price of one call to its standalone endpoint. Each evidence block is a summary under 1,500 characters. Modules whose feature is turned off for the account or that have no price are not included. Per-module prices and the expected range per call are on the pricing page.
• Requests that send only the four pillars (saju) have no birth date, so Zi Wei Dou Shu and astrology are not included (Dream Interpretation and Tarot are).
• Relation to tools.astrology: When the astrology module is included, the chart injection from tools.astrology is skipped so the same natal chart isn't added twice. When the astrology module is left out (exclude or feature off), tools.astrology works as before.
• Dream Interpretation safeguard: If the dream text contains crisis language, the AI is not called and help information (support) is returned with costPoints: 0.
• Feature switch: Currently on. If the server setting is turned off, exclude, dream and tarot are ignored even if sent, and the reading, price and response are the same as before included modules existed (no modulesUsed, moduleFees or tarot).

Request example (POST /api/v1/partners/v1/reading) — the Dream Interpretation dictionary is Korean-only, so the dream text stays in Korean

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "I can't stop thinking about last night's dream. What could it mean for me right now?",
  "dream": "큰 뱀이 집 안으로 들어와 내 발 옆에 똬리를 틀었어요",
  "tarot": { "spread": "past-present-future" }
}

Response example

{
  "success": true,
  "data": {
    "interpretation": "뱀이 집 안으로 들어와 곁에 머무는 꿈은...",
    "sajuSource": "computed",
    "modulesUsed": ["saju", "dream", "ziwei", "astro", "tarot"],
    "moduleFees": { "dream": 30, "ziwei": 50, "astro": 20, "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "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"
    },
    "usage": {
      "inputTokens": 3140,
      "outputTokens": 760
    },
    "costPoints": 162
  }
}

Saju only (leave out all other modules) (POST /api/v1/partners/v1/reading)

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "Is this a good year to change jobs?",
  "exclude": ["ziwei", "astro"]
}

Just one AI — only

The Saju AI contains Saju, Zi Wei Dou Shu, astrology, Tarot and Dream Interpretation AIs. Instead of one combined call as above, you can call just the AI you need with only. That AI answers from its own evidence only (chart, natal chart, drawn cards, dream candidates) and nothing else is added.

• Billing: Token price (question + persona + only that AI's evidence block, characters × 0.25 as input tokens, plus output tokens) + that module's one fixed fee. The expected price per call for each domain is on the pricing page.
• Can't be combined with exclude: Sending both returns 400 ONLY_WITH_EXCLUDE. If the input that AI needs is missing, you get 400 ONLY_REQUIRES_INPUT; if that feature is turned off for the account, 400 ONLY_DOMAIN_UNAVAILABLE — it doesn't fall back to a Saju reading. If the chart can't be calculated for the date, 400 ONLY_INPUT_INVALID.
• tarot and dream don't need a birth date. Just send the question and the cards (or the dream text), without birth or saju. An only other than saju doesn't use Saju, so the response has no sajuSource.
• Feature switch: Follows the same server setting as included modules, and is currently on. If the setting is turned off, only is ignored and the call behaves like a regular Saju reading.

Request example — Tarot AI only (POST /api/v1/partners/v1/reading)

{
  "question": "Should I keep pushing ahead with the job change I'm preparing?",
  "only": "tarot",
  "tarot": { "spread": "past-present-future" }
}

Response example

{
  "success": true,
  "data": {
    "interpretation": "과거 자리의 완드의 10 역방향은 오래 짊어진 짐을...",
    "only": "tarot",
    "modulesUsed": ["tarot"],
    "moduleFees": { "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "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"
    },
    "usage": {
      "inputTokens": 1180,
      "outputTokens": 720
    },
    "costPoints": 37
  }
}

Notes

• Only the interpretation is returned: The response contains only the generated interpretation text; internal prompts and Saju theory are not exposed.
• candorApplied: Only when candor was sent as t does the response carry the candor actually applied (t | f). Same for /reading/memory (Candor (working name)).
• Billing basis: Input = (question + persona characters) × 0.25 tokens (+ YouTube transcript characters injected in /reading × 0.25); output = actual completion tokens. Saju injection and system prompts are not billed, and usage.inputTokens is for reference. When included modules (today's fortune · Zi Wei Dou Shu · Astrology · Dream Interpretation · Tarot) are on, their evidence blocks and per-module fixed fees are added. costPoints is the amount actually charged.
• Response language: Questions not in Korean are answered in the same language as the question.
• Unknown birth time: If hour is omitted, the hour pillar is left out and the reading uses the three pillars of year, month and day.

AI Saju Reading · Memory API

Hosts per-end-user conversation memory and continues the reading from past context when the user comes back, for an ongoing, personalized consultation. The price is 1.3× the AI Saju Reading token rate (per 1M tokens: input KRW 3,754 · output KRW 30,030 — Reading is input KRW 2,888 · output KRW 23,100, excl. VAT).

POST /api/v1/partners/v1/reading/memory

Generates an AI Saju reading based on per-end-user memory.

Request parameters

Request parameters — tools options

Response example

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "memory": {
      "used": true,
      "summaryInjected": false,
      "notesInjected": 2,
      "tags": ["직장"],
      "overheadTokens": 120
    },
    "usage": {
      "inputTokens": 750,
      "outputTokens": 380
    },
    "costPoints": 36,
    "toolsUsed": ["memory"]
  }
}

Other response fields (sajuMismatch, toolsSkipped, filesUsed) are the same as in the AI Saju Reading API; automatically recalled documents come in filesRecalled, and with tools.emotion: true you also get emotion. The billing basis (excluding YouTube) is also the same as the Reading API.

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/memory \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "member-1024",
    "question": "About the job change we talked about last time: is next month a good time to make the move?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" }
  }'

Error codes

Codes this API returns in addition to the common errors (401, 400 body validation, 402, 429, 503, etc.):

Memory management API

AI Saju Reading with memory (POST /reading/memory) and RIDM chat (user on ridm/* models) share the same end-user memory store. {endUserId} in the paths below is exactly the value you sent then (for example, if you split chats into sessions, the whole key, such as memberId:chatId).

Request and response examples

# Get stored memory
curl https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "summary": "이직을 고민 중이며 다음 달 면접을 앞두고 있다...",
    "metaSummary": "...",
    "tags": ["이직", "면접"],
    "profile": null,
    "concerns": ["..."],
    "facts": []
  }
}

# Message list (oldest first)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/messages?limit=2&offset=0" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "messages": [
      { "id": "...", "role": "user", "content": "이직 고민이 있어요", "tags": ["이직"], "createdAt": "2026-10-11T09:00:00.000Z" },
      { "id": "...", "role": "assistant", "content": "...", "tags": [], "createdAt": "2026-10-11T09:00:04.000Z" }
    ],
    "offset": 0,
    "limit": 2,
    "total": 18
  }
}

# Tag search (tags as stored: 이직 = job change, 면접 = interview)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/search?endUserId=member-1024&tags=이직,면접" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "query": { "tags": ["이직", "면접"] },
    "results": [
      { "id": "...", "summary": "다음 달 면접 일정을 이야기함", "level": 0, "tags": ["면접"], "createdAt": "2026-10-11T09:00:00.000Z" }
    ]
  }
}

# Save a conversation (no AI generation)
curl -X POST https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/turns \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I'\''m worried about my interview next month" },
      { "role": "assistant", "content": "You'\''ve prepared well. You'\''ll do fine." }
    ],
    "summary": "Call about feeling anxious before next month'\''s interview",
    "tags": ["interview"]
  }'

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "saved": 2,
    "summarySaved": true
  }
}

# Delete everything (memory + uploaded files) — 204, no body
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

Error codes

Codes this API returns in addition to the common errors (401, 400 body validation, 402, 429, 503, etc.):

Notes

• 1.3× rate: Because of memory hosting, input/output token rates are 1.3× those of AI Saju Reading (per 1M tokens: input KRW 3,754 · output KRW 30,030, excl. VAT).
• endUserId required: Each end user needs a unique ID; calls with the same ID keep past context.
• Memory retention: Stored memory is kept until you explicitly delete it.

Saju Report API

One button, no question: a full Saju reading in one go, from the overview to wealth, love and the 10-year luck cycles (Daeun). A one-off paid product, separate from the conversational reading. The default is the dedicated model ridm/saju-report (RIDM's own model specialized for reports — no memory, since it's a one-shot product). The Reading API caps responses at 2,000 characters — for longer write-ups (up to 12 sections, about 6,000 characters), use this Report API.

POST /api/v1/partners/v1/reading/report

Send a birth date (or a Saju chart) and get back a Saju report in Markdown, section by section.

Request parameters

Reports are always written in Korean. Fields not in the table above, such as speed, tools, lang or question, are rejected with 400.

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/report \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "sections": ["총평", "재물운", "연애·인연"]
  }'

Response

{
  "success": true,
  "data": {
    "report": "## 총평\n...",        // full Markdown, section by section
    "sections": ["총평", "..."],
    "sajuSource": "computed",
    "usage": { "inputTokens": 5756, "outputTokens": 2019 },
    "costPoints": 77,
    "model": "ridm/saju-report"
    // "candorApplied": "t"  — only when candor was sent as t (t | f)
  }
}

• Saju injection is free: Manseryeok calculation and injection and the system prompt are not billed. Input billing covers only the persona length; output is the tokens actually used.
• Measured cost: One report with the default 8 sections (about 3,000 characters) costs about 85P (based on output at ₩38,077/1M).
• Retries are billed again. If you want to reuse a response for the same input, store it on the client side (Idempotency).

Error codes

Codes this API returns in addition to the common errors (401, 400 body validation, 402, 429, 503, etc.):

YouTube Summary API

Pulls the captions of a YouTube video and returns a summary or a Q&A answer. Videos without captions return a 400 error (not billed).

POST /api/v1/partners/v1/youtube/summary

Request parameters

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/youtube/summary \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxLength": 1000 }'

Response example

{
  "success": true,
  "data": {
    "summary": "## 0:00~1:30 오프닝\n영상 제목 설명...\n\n## 1:30~5:00 본론\n...",
    "video": {
      "videoId": "dQw4w9WgXcQ",
      "title": "Video Title",
      "channel": "Channel Name"
    },
    "transcriptSource": "supadata",
    "usage": {
      "promptTokens": 7059,
      "completionTokens": 1384
    },
    "costPoints": 51,
    "model": "ridm/gpt-5.6-terra"
  }
}

Notes

• Captions required: no captions → TRANSCRIPT_UNAVAILABLE 400 (not billed).
• Errors: invalid URL or ID 400 INVALID_YOUTUBE_URL / summary generation failed 400 LLM_GENERATION_FAILED / insufficient balance 402 INSUFFICIENT_BALANCE.
• Billing: billed by tokens, at the resale price as is (cost × 1.1) of the model used (default ridm/gpt-5.6-terra) — there is no memory layer, so the RIDM Memory rate (× 1.3) does not apply. costPoints = ceil(input tokens × input rate + output tokens × output rate); rates are per 1M tokens (excl. VAT).
• Measured cost: about 60P per call for a 20–30 minute video (tokens included).
• Use with readings: in the AI Saju Reading API (/reading), tools: { "youtube": true } injects the captions of links in the question (a top-level youtube field is ignored). YouTube injection works only on /reading (not yet on /reading/memory). If you send it to /reading/memory, captions are not fetched and toolsSkipped reports {"tool": "youtube", "reason": "unavailable"}.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Turning the feature on and off

The YouTube Summary API is opt-in per partner account and per request. Manage the account-wide setting under "Feature settings" in the console; per request, enable it with top-level youtube:true for chat and tools: { "youtube": true } for reading.

• Disabled account-wide: responds 403 { code: 'FEATURE_DISABLED', feature: 'youtube' }
• Per request: youtube:true missing or false = no YouTube injection

Document Processing API

Upload PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), CSV, text, Markdown and Hangul (.hwpx) documents, have AI analyze them, and load them into a context-aware knowledge base. Text is extracted automatically; with the "AI analysis" option on, the document is split into context sections and a summary and search tags are generated and stored for each section.

Supported formats and limits

Endpoints

Uploading a file

POST /api/v1/partners/v1/files

Upload the file as a multipart form.

Request fields

cURL example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/files \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "endUserId=user_123" \
  -F "analyze=true"

Response example

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    "originalName": "sample.pdf",
    "mime": "application/pdf",
    "size": 125000,
    "textLength": 8942,
    "charsCapped": false,
    "textPreview": "1장. 개요 ...",
    "summary": "문서 전체 요약...",
    "context": "문서 전체 요약...",
    "status": "analyzed",
    "analysisStatus": "analyzed",
    "analyzeRequested": true,
    "endUserId": "user_123",
    "usage": { "inputTokens": 3100, "outputTokens": 420, "costWon": 1 },
    "totalChunks": 3,
    "createdAt": "2026-08-26T12:34:56Z"
  }
}

List, details, delete

# List — newest first, limit 1–100 (default 20)
curl "https://api.hrum.ai/api/v1/partners/v1/files?endUserId=user_123&limit=20&offset=0" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "files": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "sample.pdf", "status": "analyzed", ... } ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

# Details — upload response fields + extractedText + chunks
curl https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    ...,
    "extractedText": "1장. 개요 ...",
    "chunks": [
      { "id": "...", "chunkIndex": 0, "context": "1장 요약...", "tags": ["개요"], "textLength": 2980 }
    ]
  }
}

# Delete
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{ "success": true, "data": { "deleted": true } }

Using files in chat and readings

Explicit attachment: in Chat completions or AI reading requests, inject up to 5 documents with the fileIds parameter. Analyzed files inject the document summary (up to 500 characters) plus the original text; unanalyzed files inject the original text (original text capped at 40,000 characters per file / 80,000 in total; child chunks are not injected). Injected documents are appended to the last user message and count as input tokens. Resale models support explicit fileIds injection only.

Auto-recall (ridm/* only): on ridm/* chat and reading-memory models, analyzed files whose tags overlap the user's question are found and injected automatically (only when no explicit fileIds are given). The response lists the recalled file IDs in a filesRecalled array.

Chat request example

{
  "model": "ridm/gpt-5.6-terra",
  "messages": [
    { "role": "user", "content": "Can you summarize the main points of this document?" }
  ],
  "fileIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "user": "user_123"
}

Response example

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": { "content": "문서의 주요 내용은..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2500, "completion_tokens": 150 },
  "filesUsed": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

filesRecalled is included only when files were auto-recalled (omitted when empty).

Pricing and billing

• Upload and extraction: free (no tokens billed for text extraction)
• AI analysis (analyze=true): the actual tokens used for boundary detection + per-section summaries + the overall summary are billed at the analysis model's rate. Synchronous for ≤30,000 characters, asynchronous for >30,000 (status: analyzing)
• Chat injection: document text counts as input tokens and is billed like any chat request
• Logs: shown in the console usage log as file_upload (free) and file_analyze (paid, actual tokens)

Turning the feature on and off

Document processing can be enabled or disabled per partner account. Manage it under "Feature settings" in the console; when it is off, every file request returns 403.

• Disabled account-wide: responds 403 { code: 'FEATURE_DISABLED', feature: 'files' }
• Per request: no fileIds = no document injection (handled normally)

Analysis status and chunks

The GET /api/v1/partners/v1/files/:id response includes analysisStatus, extractedText and chunks. chunks is an array only when analysis is complete and totalChunks is 2 or more (each chunk: chunkIndex, context (summary), up to 10 tags); otherwise it is null. The upload response has no chunks.

Notes

• Format check: unsupported formats return 400 { code: 'INVALID_FILE_TYPE' }
• Other errors: missing file 400 FILE_NOT_PROVIDED / over 10MB 400 FILE_TOO_LARGE / unknown file 404 FILE_NOT_FOUND / 400 if :id is not a UUID
• Required for analysis: analyze=true without endUserId returns 400 { code: 'END_USER_REQUIRED' }
• Extraction failure: an error while extracting the document returns 422 { code: 'EXTRACTION_FAILED' }
• Balance check: partner credits are checked before an analysis request. If short, 402 is returned
• Automatic knowledge-base loading: with analyze=true, each section's summary and tags are saved to the knowledge base automatically and become auto-recall candidates. If endUserId is given, they are also added to that user's memory layer.
• Re-upload = new file: every upload creates a new file (new id), and with analyze=true it is analyzed and billed again. Upload a document once and reuse the returned id in fileIds.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Emotion Analysis (Emotion)

Analyzes the emotional state of the user and the AI by riding on the Chat API's summary cycle. There is no separate LLM call — an emotion block is only added to the summary prompt — so there is no extra charge. Supported on ridm/* models only.

Overview

Enabled when:

1. Global: partner_emotion_enabled ✓
2. Partner: "Emotion analysis" is turned on in the console's feature settings
3. Request: emotion: true is set
4. Model: ridm/* models only

Summary interval (summaryEvery)

Emotion analysis runs automatically on every summary cycle. Set the cycle interval with the summaryEvery parameter (default: 5, range: 1–20).

• summaryEvery=1: emotion updates on nearly every turn (the summary runs asynchronously after the response)
• summaryEvery=5: every 5 turns (recommended)
• summaryEvery=20: every 20 turns (fewest updates)
• Summary and emotion cycles are never billed to the partner, whatever the interval.

Request parameters

Request example

{
  "model": "ridm/gpt-5.6-terra",
  "user": "user_123",
  "messages": [
    { "role": "user", "content": "Today was a rough day..." }
  ],
  "emotion": true,
  "summaryEvery": 3
}

Response fields

Response example

{
  "id": "chatcmpl-xyz",
  "choices": [{
    "message": { "content": "오늘 하루가 힘들었군요..." },
    "finish_reason": "stop"
  }],
  "emotion": {
    "user": {
      "type10": "sad",
      "tone": "warm",
      "distribution6": {"joy": 100, "sadness": 600, "anger": 50, "fear": 100, "disgust": 50, "surprise": 0}
    },
    "assistant": {
      "distribution6": {"joy": 200, "sadness": 100, "anger": 0, "fear": 0, "disgust": 0, "surprise": 0}
    },
    "trend": "stable",
    "updatedAt": "2026-08-26T12:34:56Z",
    "turnsSinceUpdate": 0
  },
  "usage": {...}
}

Distribution fields (distribution6)

Trend rules (trend)

• improving: non-positive emotions (sadness+anger+fear+disgust) dropped by 50 or more
• stable: change under 50
• declining: non-positive emotions rose by 50 or more
• null: no data from a previous cycle

Streaming response example (SSE)

In streaming mode (stream: true), the emotional state is included in the data of the event: message_done SSE event.

event: message_done
data: {"finish_reason":"stop","usage":{...},"costWon":2,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]},"emotion":{"user":{"type10":"concerned","tone":"warm","distribution6":{...}},"assistant":{...},"trend":"stable","updatedAt":"2026-08-26T12:34:56Z","turnsSinceUpdate":0}}

data: [DONE]

Cost

• No separate charge: emotion analysis runs inside the summary-cycle prompt, and summary and emotion cycle tokens are not billed to the partner. You pay only for the input and output tokens of the chat turn itself.

Notes

• Before the first cycle: there is no emotion field until the first summary cycle has run (expected behavior).
• Feature off: an emotion: true request while the global or partner feature setting is off returns 403 { code: 'FEATURE_DISABLED', feature: 'emotion' } (same as YouTube and document processing). If you don't send emotion or send false, the field is simply omitted.
• Supported on ridm/* models only. On accounts with the emotion feature on, the emotion field is ignored for resale (openai/*, google/*) requests; on accounts with it off, emotion:true returns 403 FEATURE_DISABLED regardless of model.
• Streaming: in streaming responses, emotion is included in the message_done SSE event.

Saju Image API

Generates AI art that expresses the Five Elements and energy of a person's Saju (Four Pillars of Destiny). Returned as a base64-encoded PNG, at a fixed charge of ₩200.

POST /api/v1/partners/v1/image

Generates a Saju Five Elements image from a date of birth.

Request parameters

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/image \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female", "style": "portrait" }'

Response example

{
  "success": true,
  "data": {
    "imageDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "costPoints": 200
  }
}

Notes

• Fixed price: every image generation is billed ₩200.
• Generation time: generating an image takes 20–30 seconds. Set a generous timeout.
• Base64 encoding: the returned imageDataUri is a base64-encoded PNG and can be used directly in an HTML <img src="{imageDataUri}"> tag.
• Styles: background (background art), icon (minimal icon) and portrait (portrait illustration) change only the mood. All styles have the same size (default 1024×1024 square).
• Timeout: if the upstream does not return an image within 80 seconds, 504 IMAGE_UPSTREAM_TIMEOUT is returned and nothing is billed. Try again.
• Unknown birth time: if hour is omitted, the hour pillar is dropped and the reading uses the three pillars of year, month and day.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Image Generation API (model resale)

POST /api/v1/partners/v1/images/generations

Call GPT-Image and Nano Banana models with one key, in the same format as the OpenAI Images API. Each model, resolution and quality has a fixed per-image price, and the amount in the table is deducted as is (images generated × per-image price). The cost of prompt input tokens is included in the per-image price and is not added separately.

Request parameters

Sending aspect_ratio or resolution to GPT-Image, or requesting a resolution the model does not support, is rejected with 400 INVALID_PARAMETER and not billed.

Other errors: MODEL_NOT_FOUND / INVALID_MODEL (400, unknown model), INVALID_PROMPT (400, the upstream rejected the prompt), UPSTREAM_ERROR, RATE_LIMITED (currently HTTP 400, body status 429), INSUFFICIENT_BALANCE (402).

Price per image (₩, excl. VAT)

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "prompt": "A serene mountain landscape at sunset",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

Response example

{
  "created": 1791452814,
  "data": [ { "b64_json": "iVBORw0KGgo..." } ],
  "costWon": 225,
  "requestId": "..."
}

• GPT-Image and Google direct models return images as b64_json; FAL models return a url.
• costWon = per-image price × images actually generated. If the upstream returns no image at all, nothing is billed.
• The usage (token counts) in GPT-Image responses is for reference only and is not used for pricing.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Error responses use the same {"success": false, ...} format as other APIs (only success responses are unwrapped).

Long-running generation — asynchronous response (202, optional)

High-resolution or multi-image requests can take over a minute. If you add the Prefer: respond-async request header and the result is not ready within 60 seconds, the connection is not held open: you get 202 Accepted with a job ID, and generation continues on the server for up to 240 seconds. If it finishes within 60 seconds, you get the same 200 response as today. Without the header, nothing changes (if it does not finish within 80 seconds, 504 IMAGE_UPSTREAM_TIMEOUT, not billed) — send the header only from clients that are ready to handle 202.

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"model": "google/nano-banana-pro", "prompt": "...", "resolution": "4K"}'

HTTP/1.1 202 Accepted
Location: /api/v1/partners/v1/jobs/imgjob_3f2a...
Retry-After: 5
Preference-Applied: respond-async

{
  "id": "imgjob_3f2a...",
  "object": "image.job",
  "status": "pending",
  "pollUrl": "/api/v1/partners/v1/jobs/imgjob_3f2a...",
  "retryAfter": 5,
  "createdAt": "2026-10-12T03:00:00.000Z",
  "expiresAt": "2026-10-13T03:00:00.000Z"
}

GET /api/v1/partners/v1/jobs/{id}

Poll with the same API key (X-Partner-Api-Key) every Retry-After seconds. Polling is free and does not count toward the daily request limit. It is limited to once every 2 seconds per API key; polling more often returns 429 IMAGE_JOB_POLL_RATE_LIMITED with Retry-After (seconds). Responses are HTTP 200; the state is given by the body's status.

• Billing: deducted once, at the moment the result is ready. While waiting, the expected amount is reserved from the balance; on failure or timeout the reservation is released and nothing is billed. Polling many times does not bill again.
• Retention: results and errors can be fetched for 24 hours after the job is created and are deleted after that (404 afterwards). If images are b64_json, the poll response is just as large (several MB per image) — save it as soon as you receive it. If the whole result exceeds 16MB, it is not stored and the job fails with IMAGE_JOB_RESULT_TOO_LARGE (not billed) — reduce the number of images (n) or the resolution.
• Another partner's job ID, an unknown ID and an expired ID all return the same 404 IMAGE_JOB_NOT_FOUND.

Manseryeok API

POST /api/v1/partners/v1/manseryeok

Includes Saju Identity — the identity field at the end of the response also carries Samjae (three-year misfortune cycle), Sinsal (symbolic stars), Gongmang (void), root strength, seasonal strength, the 10-year / annual luck timeline and a Saju MBTI (no extra charge; null if the calculation fails).

Calculates the Manseryeok (the Korean Four Pillars calendar) natal chart: for the four pillars (year, month, day, hour), the Heavenly Stems and Earthly Branches, Chinese characters, Five Elements, Ten Gods, hidden stems, Nayin, Twelve Life Stages and Sinsal. Using precise solar-term-based calculation, it delivers a complete Saju reading — natal chart analysis (Yongsin (favorable element), Eokbu balancing, Johu (climate) Yongsin, Day Master strength, purity/turbidity, mediating element, illness-and-remedy, Five Elements variables) → ten 10-year luck cycles (Daeun) (including the current cycle, with stem/branch combinations, clashes, punishments and harms) → five years of annual luck (Seun) (grade, relationship and interpretation per year) → Gyeokguk (chart structure) and detailed interpretation → the ten Heavenly Stems theory, seasonal state, Gongmang, phantom characters (heoja), hidden combinations (bihap) and hidden prosperity (amnok) — in 30 top-level base fields plus optional fields (200+ including sub-fields). If the birth time is unknown, only the hour pillar (wonkuk.hour) and trueSolarTime, which needs the actual time, are null; analysis fields such as Yongsin, Gyeokguk and Day Master strength are still returned, calculated from the three pillars of year, month and day (six characters) (birthHour.basis: "three_pillars").

Request parameters

Response fields (30 base + optional fields)

PillarFull structure (sub-fields of each pillar)

Fields of each of wonkuk.year, wonkuk.month, wonkuk.day and wonkuk.hour in the response:

DaeunPeriod structure (each 10-year luck cycle)

SeunYear structure (each year of annual luck)

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2000, "month": 1, "day": 15, "hour": 14, "minute": 30,
    "gender": "male", "calendar": "solar", "timezone": "Asia/Seoul"
  }'

Response example (excerpt: male, 2000-01-15 14:30)

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": {
        "stem": "기", "branch": "묘", "stemHanja": "己", "branchHanja": "卯",
        "ohaeng": "토", "stemSipsin": "정관", "branchSipsin": "상관",
        "jijanggan": ["갑", "을"], "chunghyung": [], "hapPosition": ["半合(반합)"],
        "ungSung": "사", "napEum": "성두토",
        "majorSinsal": ["장성살"],
        "minorSinsal": ["천을귀인", "귀문관살", "원진살", "현침살", "육해살"]
      },
      "month": { ... },
      "day": { ... },
      "hour": { ... }
    },
    "trueSolarTime": null,
    "ohaengBalance": { "목": 1, "화": 2, "토": 3, "금": 1, "수": 1 },
    "yongshin": "수",
    "johuYongshin": "화",
    "yongshinDetail": {
      "method": "억부",
      "primary": "수",
      "secondary": ["금"],
      "reasoning": ["일간 임(수) 신약", "신약 + root 있음(8) → 비겁(수)"],
      "shin": { "yongshin": "수", "huishin": "금", "gishin": "토", "gushin": "화", "hanshin": "목" },
      "favorable_sipsin": ["편인", "정인", "비견", "겁재"],
      "unfavorable_sipsin": ["편관", "정관", "편재", "정재", "식신", "상관"],
      "element_states": { "목": { "count": 1, "state": "lack", "effect": "neutral" }, "...": "5오행" }
    },
    "eokbuYongshin": "수",
    "ilganSummary": "壬水 — 큰 바다의 기운. 지혜롭고 포용력이 넓어요.",
    "daeun": [
      {
        "startAge": 3, "endAge": 13,
        "stem": "병", "branch": "자", "stemHanja": "丙", "branchHanja": "子",
        "ohaeng": "화", "isCurrent": false,
        "stemSipsin": "편재", "branchSipsin": "겁재",
        "sinsal": ["년살", "장성살"]
      },
      {
        "startAge": 13, "endAge": 23,
        "stem": "을", "branch": "해", "stemHanja": "乙", "branchHanja": "亥",
        "ohaeng": "목", "isCurrent": false,
        "stemSipsin": "상관", "branchSipsin": "비견",
        "sinsal": ["지살", "망신살"]
      },
      {
        "startAge": 23, "endAge": 33,
        "stem": "갑", "branch": "술", "stemHanja": "甲", "branchHanja": "戌",
        "ohaeng": "목", "isCurrent": true,
        "stemSipsin": "식신", "branchSipsin": "편관",
        "sinsal": ["천살", "월살"]
      }
      // … cycles 4–10 (startAge 33–93) omitted — the actual response has 10
    ],
    "seun": [
      // 2024 and 2025 entries omitted
      {
        "year": 2026, "stem": "병", "branch": "오", "stemHanja": "丙", "branchHanja": "午",
        "ohaeng": "화", "isCurrent": true, "grade": "good",
        "relations": [
          { "type": "해", "target": "월주", "description": "오-축 해" },
          { "type": "육합", "target": "시주", "description": "오-미 육합" }
        ],
        "summary": "전체적으로 순조로운 흐름이 예상돼요. (해, 육합 작용)",
        "sinsal": ["육해살", "재살"]
      }
      // 2027 and 2028 entries omitted — the actual response has 5: two years either side of this year
    ],
    "branchRelations": [
      { "type": "沖(충)", "pillars": ["축", "미"], "description": "丑未沖 (축미충)" },
      { "type": "半合(반합)", "pillars": ["묘", "미"], "description": "卯未合 (묘미합)" }
    ],
    "gongmang": ["술", "해"],
    "cheonEulGwiIn": ["묘"],
    "wolryeong": "축",
    "daeunNumber": 3,
    "daeunDirection": "역행",
    "gyeokguk": {
      "name": "정관격",
      "summary": "질서·명예·합리"
    },
    "gyeokgukDetail": { ... },
    "cheonganDetail": { ... },
    "hapChungReport": { ... },
    "heojaReport": { ... },
    "gongmangDetail": { ... },
    "ohaengByeonsuHits": [
      {
        "key": "to_wang_deuk_mok",
        "subject": "土", "target": "木",
        "formula_idiom": "방능소통(方能疏通)",
        "description": "토가 왕성한데 목을 얻으면 소통이 된다",
        "category": "wang_geuk_sunwha"
      },
      {
        "key": "gang_to_deuk_geum",
        "subject": "土", "target": "金",
        "formula_idiom": "방제기해(方制其害)",
        "description": "강한 토가 금을 얻으면 그 피해를 막는다",
        "category": "gang_seolgi_sunwha"
      }
    ],
    "strength": {
      "dayMaster": "임",
      "score": -66,
      "result": "신약",
      "level": "중약",
      "breakdown": { "season": -30, "support": 8, "control": -38, "hidden": -9, "root": 8 },
      "root": { "rooted": true, "rootScore": 8 }
    },
    "jeongtak": {
      "verdict": "탁",
      "reasons": ["파괴 십신 2개 감지", "용신 금 생 ✓", "일주 신약"],
      "severity": "극탁"
    },
    "tonggwan": { ... },
    "byeongyak": { ... },
    "countryCodeUsed": null,
    "identity": {
      "rooting_hints": { ... }, "season_strength_hint": { ... }, "sinsal_list": [ ... ],
      "gongmang": { ... }, "samjae": { ... }, "timeline": { ... },
      "mbti_inference": { ... }, "coherence": { ... }
    },
    "ohaengDeficient": []
  }
}

This example was called in 2026, so daeun[].isCurrent and the years in seun depend on the year of the call. { ... } and // lines mark omissions. The request sent no location, so trueSolarTime is null. Add "country": "KR" (or coordinates) to the same request and trueSolarTime holds the correction result ("basis": "country") and countryCodeUsed becomes "KR". For the shape of the correction result, see the lunar input example in the Notes below.

Notes

• Large response: the Manseryeok response contains not only the natal chart but detailed data such as 10-year luck, annual luck, Gyeokguk and Sinsal. Pick only the fields you need.
• Optional fields — the unknown-birth-time contract: hour and minute can be omitted. If hour is omitted, noon is not assumed; the hour pillar is excluded. The response changes as follows.
  • wonkuk.hour = null, trueSolarTime = null
  • ohaengBalance = recalculated from the three pillars of year, month and day (six stem + branch characters)
  • branchRelations and cheonEulGwiIn = only entries formed by the three pillars' branches remain
  • A top-level birthHour is added: { known: false, hourPillar: null, basis: "three_pillars", excludedFields: [], note }. Analysis fields (yongshin, strength, gyeokguk, hapChungReport, ilganSummary, seun, etc.) are not removed; they are returned as values calculated from the three pillars (six characters) (thresholds that depend on the character count are also converted to a six-character basis). These are values derived from the three pillars alone, not noon reference values
  • To detect an unknown birth time, use birthHour.known — not excludedFields.length. That array is now always empty and kept only for compatibility with older clients
  • minute is ignored if sent without hour (minute ?? 0 only when hour is present)
  • Requests that send hour have no birthHour field, and results are the same as before (except identity and ohaengDeficient, added since 2026-10-10). Existing clients that always send hour are not affected. Clients built for the briefly existing "calculate at noon when omitted" behavior should check birthHour.known === false and show the hour-pillar cell as "unknown". strength, gyeokguk, etc. are always returned as three-pillar values (before 2026-09-16 they were removed). The consultation APIs (/reading, /reading/memory, /reading/report) follow the same rule and pass three-pillar values to the model
• Korean field values: all field values (Heavenly Stems, Earthly Branches, Five Elements, etc.) are written in Korean. Sending lang does not change field names; only values (Yongsin, Day Master description, 10-year luck direction, Sinsal names, etc.) are translated. Stem, branch and element codes (stem, branch, ohaeng) and the keys of ohaengBalance stay in Korean in every language. For the full list, see Valid values > Language-independent code values.
• All extra options are optional (2026-10-08): if you send none of lang, calendar, isLeapMonth, birthLatitude, birthLongitude, country, zaSiRule or birthTimePrecision, results are the same as before — except that since 2026-10-10 identity and ohaengDeficient are always appended to the end of the response (values and order of existing keys unchanged). The price is still ₩50/call.
• Change (2026-10-12): the lunar conversion basis was switched to Korea Astronomy and Space Science Institute (KASI) data, changing results for some dates. A non-existent leap month is no longer converted to the regular month; it returns 400 INVALID_LUNAR_DATE.
• Lunar input: with calendar: "lunar", the conversion details lunarInput are added at the top level of the response. The true solar time correction goes in trueSolarTime. Actual engine output (lunar 1990-07-15 14:30, Busan coordinates, lang: "en"):

  {
    "year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30,
    "timezone": "Asia/Seoul", "gender": "male",
    "calendar": "lunar", "birthLatitude": 35.1796, "birthLongitude": 129.0756,
    "lang": "en"
  }
  →
  "lunarInput": {
    "calendar": "lunar", "lunarDate": "1990-07-15", "isLeapMonth": false,
    "leapMonthApplied": false, "solarDate": "1990-09-03"
  },
  "trueSolarTime": {
    "originalLocal": "14:30", "correctedLocal": "14:07",
    "longitudeCorrection": -23.6976, "equationOfTime": 0.3241,
    "totalCorrectionMinutes": -23.4, "dayShift": 0, "dstApplied": false,
    "basis": "coords", ...
  },
  "ilganSummary": "辛 Metal — Jewel energy. Sharp intellect and refined aesthetic sense.",
  "daeunDirection": "Forward"

• Input errors: a lunar date that does not exist (e.g. the 30th of a 29-day month) returns 400 INVALID_LUNAR_DATE, and a request with only one of latitude/longitude returns 400 INVALID_LOCATION; neither is billed. Format errors such as a missing timezone are also 400 (not billed).

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "topic": "career", "lang": "ko"
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          { "component": "ilgan_wolji", "key": "임_신", "text": "..." },
          { "component": "ilgan_strength", "key": "임_신강", "text": "..." },
          { "component": "ilgan_yongshin", "key": "임_화", "text": "..." },
          { "component": "ohaeng_state", "key": "목_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "토_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "수_lack", "text": "..." },
          { "component": "top_sipsin", "key": "인성", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" }
  }
}

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "birthLatitude": 37.5665, "birthLongitude": 126.978,
  "topic": "career", "lang": "ko",
  "layers": ["astro", "ziwei"]
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          ...
          { "component": "top_sipsin", "key": "인성", "text": "..." },
          { "component": "astro_sun", "key": "vir", "text": "...", "label": "별자리로 보면" },
          { "component": "astro_moon", "key": "pis", "text": "..." },
          { "component": "astro_asc", "key": "sag", "text": "..." },
          { "component": "ziwei_ming", "key": "tt_jm", "text": "...", "label": "자미두수로 보면" },
          { "component": "ziwei_palace", "key": "cr_tj", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" },
    "missingSections": 0,
    "layers": {
      "astro": { "included": true, "costWon": 20, "note": null },
      "ziwei": { "included": true, "costWon": 20, "note": null }
    }
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30,
  "gender": "female", "referenceDate": "2026-10-08", "lang": "ko"
}

{
  "success": true,
  "data": {
    "engineVersion": 1,
    "lang": "ko",
    "referenceDate": "2026-10-08",
    "clock": {
      "inputSolarDate": "1990-05-15", "inputTime": "14:30",
      "correctedSolarDate": "1990-05-15", "correctedTime": "14:30",
      "correctionMinutes": 0, "dstApplied": false, "basis": null,
      "hourBranch": { "key": "wei", "label": "미" }
    },
    "chart": {
      "engine": { "name": "iztro", "version": "2.6.1", "config": { ... } },
      "solarDate": "1990-05-15",
      "lunarDate": { "year": 1990, "month": 4, "day": 21, "isLeapMonth": false },
      "yearGanzhi": "경오",
      "yearBasisNote": null,
      "fiveElementsClass": { "key": "earth5", "label": "토오국" },
      "soulPalaceBranch": { "key": "xu", "label": "술" },
      "bodyPalaceBranch": { "key": "zi", "label": "자" },
      "palaces": [
        ...,
        {
          "key": "ming", "label": "명궁",
          "branch": { "key": "xu", "label": "술" },
          "stem": { "key": "bing", "label": "병" },
          "isBodyPalace": false,
          "majorStars": [
            { "key": "ziwei", "label": "자미", "brightness": { "key": "de", "label": "득" }, "mutagen": null },
            { "key": "tianxiang", "label": "천상", "brightness": { "key": "de", "label": "득" }, "mutagen": null }
          ],
          "minorStars": [
            { "key": "lingxing", "label": "영성", "brightness": { "key": "miao", "label": "묘" }, "mutagen": null }
          ],
          "decadal": { "from": 5, "to": 14, "isCurrent": false }
        },
        ...
      ],
      "mutagens": [
        { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "quan", "label": "화권", "starKey": "wuqu", "starLabel": "무곡", "palaceKey": "wealth", "palaceLabel": "재백궁" },
        { "type": "ke", "label": "화과", "starKey": "taiyin", "starLabel": "태음", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "ji", "label": "화기", "starKey": "tiantong", "starLabel": "천동", "palaceKey": "health", "palaceLabel": "질액궁" }
      ],
      "currentDecadal": { "palaceKey": "children", "from": 35, "to": 44 },
      "yearly": { "palaceKey": "wealth", "year": 2026 }
    },
    "features": [
      "bright:紫微=得", "co:紫微+天相@命", "cs:命=胎", "dir:逆", "hua:祿=太陽@子女",
      "lhua:忌=廉貞@流年", "limit:大限@子女", "limit:小限@辰", "ming:戌", "mingzhu:祿存",
      "star:天姚@辰", "star:紫微@命", "year:庚", "yy:陽女", ...
    ],
    "notes": { "lateZiNotice": null, "approximateTimeNote": null }
  }
}

{
  "success": false,
  "statusCode": 400,
  "code": "birth_time_required",
  "message": "Zi Wei Dou Shu needs the birth hour (hour 0-23). ...",
  "partial": {
    "birthYearMutagens": [
      { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양" },
      ...
    ],
    "yearStemStars": [
      { "key": "lucun", "label": "녹존", "branch": { "key": "shen", "label": "신" } },
      ...
    ]
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/identity \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male" }'

{
  "success": true,
  "data": {
    "saju": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { ... }
    },
    "sipsin_map": { "year_cheongan": "비견", "year_jiji": "정관", "month_cheongan": "겁재", ... },
    "strength": { "dayMaster": "경", "score": -60, "result": "신약", "level": "중약", ... },
    "rooting_hints": { ... },
    "season_strength_hint": { "season": "여름", "strength_label": "최약(最弱)", ... },
    "sinsal_list": [ { "id": "shinsal_haksang", "name": "학당", "name_hanja": "學堂", "category": "길신", ... } ],
    "gongmang": { "sun": "갑술순", "void_branches": ["신", "유"], "hits": [] },
    "samjae": { "is_in_samjae": false, "current_year_branch": "오" },
    "yongshin": { "method": "조후", "primary": "수", ... },
    "timeline": { "current": { "daeun": { "startAge": 27, "endAge": 37, "stem": "갑", "branch": "신", ... }, ... } },
    "gyeokguk": { "primary": "비견격", ... },
    "mbti_inference": { "e_i": 48, "s_n": -8, "t_f": 16, "j_p": -18, "inferred": "ESFJ", ... },
    ...
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-mbti \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male", "mbti": "INFJ" }'

{
  "success": true,
  "data": {
    "wonkuk": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { "cheongan": "임", "jiji": "오", "ohaeng": "수" }
    },
    "pillarCount": 4,
    "dayMaster": "경",
    "strength": "신약",
    "ohaengCount": { "목": 0, "화": 3, "토": 1, "금": 3, "수": 1 },
    "ohaengState": { "목": "lack", "화": "balanced", "토": "lack", "금": "balanced", "수": "lack" },
    "dominantSipseong": ["관성"],
    "mbti": {
      "type": "INFJ",
      "source": "letters",
      "axes": {
        "E_I": { "value": 25, "letter": "I", "band": "slight" },
        "S_N": { "value": 25, "letter": "N", "band": "slight" },
        "T_F": { "value": 25, "letter": "F", "band": "slight" },
        "J_P": { "value": 75, "letter": "J", "band": "slight" }
      }
    },
    "sajuLean": {
      "E_I": { "lean": "balanced", "weights": { "E": 1, "I": 1 }, "ruleIds": ["R-MBTI-OHAENG-010", "R-MBTI-STRENGTH-002"] },
      "S_N": { "lean": "S", "weights": { "S": 1 }, "ruleIds": ["R-MBTI-OHAENG-006"] },
      "T_F": { "lean": "T", "weights": { "T": 2 }, "ruleIds": ["R-MBTI-STEM-007"] },
      "J_P": { "lean": "J", "weights": { "P": 1, "J": 2 }, "ruleIds": ["R-MBTI-OHAENG-008", "R-MBTI-SIPSEONG-002"] }
    },
    "comparison": [
      { "axis": "E_I", "label": "에너지 방향(E·I)", "user": "I", "userBand": "slight", "saju": "balanced", "relation": "neutral",
        "text": "에너지 방향(E·I): 사주에서는 어느 한쪽으로 기우는 경향이 뚜렷하지 않아요. 입력은 I 쪽이에요." },
      { "axis": "S_N", "label": "인식 방식(S·N)", "user": "N", "userBand": "slight", "saju": "S", "relation": "different",
        "text": "인식 방식(S·N): 사주와 다른 면을 키운 것으로 볼 수 있어요. 사주는 S 쪽 경향이 있고, 입력은 N 쪽이에요." },
      { "axis": "T_F", ... },
      { "axis": "J_P", "label": "생활 방식(J·P)", "user": "J", "userBand": "slight", "saju": "J", "relation": "same",
        "text": "생활 방식(J·P): 사주와 같은 방향이에요. 사주에서 보이는 J 쪽 경향이 입력에도 드러나요." }
    ],
    "matchedRules": [
      { "id": "R-MBTI-STEM-007", "statement": "庚 일간은 단단한 쇠의 기운으로 읽혀, 기준을 세워 따져 보고 결단하는 쪽(T)으로 기울기 쉬운 경향이 있어요." },
      ...
    ],
    "caveats": [ { "id": "R-MBTI-CAVEAT-001", "statement": "사주와 MBTI를 잇는 이 해석은 고전 명리 이론이 아니라 현대의 해석 관행이에요. ..." }, ... ],
    "caveatRuleId": "R-MBTI-CAVEAT-001",
    "interim": false,
    "kbStatus": "literature",
    "kbVersion": "2026.10.16-2",
    "engineVersion": "saju-mbti-1"
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
  "timezone": "Asia/Seoul", "gender": "male",
  "date": "2026-10-10",
  "temperatureC": 16, "weather": "cloudy", "humidity": 60,
  "mbtiBehavior": true
}

{
  "success": true,
  "data": {
    "date": "2026-10-10",
    "summary": {
      "ilju": "경진",
      "day_master": "경",
      "gyeokguk": "비견격",
      "gyeokguk_reason": "월지 사 중기(경) 투간 [연간=경]",
      "inferred_mbti": "ESFJ",
      "today_mbti": "ESFJ",
      "current_mbti": "ESFJ",
      "strength_label": "신약",
      "yongshin": "수",
      "today_date": "2026-10-10",
      "today_ganji": "정사",
      "today_day_ohaeng": "화",
      "today_sipsin": "정관",
      "flow_score": 60,
      "flow_tier": "good",
      "top_favored_task_type": "routine",
      "top_caution_task_type": "movement",
      "active_sinsal_names": ["학당", "암록", "복성귀인", "화개살", "자형(오오)"],
      "in_samjae": false,
      "daily_flow": "오늘(정사일) 화 에너지가 흘러 소통·확장에 유리해."
    },
    "omen": {
      "relation": { "type": "GEUK", "label": "조율의 날" },
      "color": { "name": "주황", "hex": "#FFA45B", "ohaeng": "화" },
      "food": "고추장비빔밥",
      "keyword": "공개",
      "message": "표현하고 싶은 마음과 주변 반응이 엇갈릴 수 있는 날이에요. 즉흥적인 말보다 한 박자 늦춘 표현이 좋아요.",
      "luckyHour": "오전 11시 ~ 오후 1시",
      "avoidHour": "밤 11시 이후",
      "activity": "칭찬 먼저 하기"
    },
    "taskAffinity": [
      { "taskType": "focus", "score": -0.25, "verdict": "neutral",
        "reason": "길 십신 2개 일치 · 흉 십신 2개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" },
      { "taskType": "creative", "score": -0.75, "verdict": "caution", "reason": "..." },
      ...,
      { "taskType": "routine", "score": 0.25, "verdict": "favored",
        "reason": "길 십신 4개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" }
    ],
    "fashion": {
      "temperatureC": 16, "tempBand": "T3",
      "main": "버건디 자켓", "accent": "가죽 벨트",
      "colorAttachLabel": "반지나 메탈 액세서리에",
      "byTime": {
        "morning": { "main": "버건디 자켓", "accent": "가죽 벨트", "tempBand": "T3" },
        "noon": { ... }, "evening": { ... }
      },
      "mood": {
        "feelsLikeC": 16, "tempBand": "jacket", "humidBand": "normal", "weatherKey": "cloudy",
        "morning": { "headline": "흐린 자켓 새벽", "body": "햇볕 없어 살짝 서늘. 자켓 한 벌.", "carry": [] },
        "noon": { ... }, "evening": { ... }
      }
    },
    "mbtiBehavior": {
      "mbti": "ESFJ",
      "headline": "협력·돌봄",
      "actions": ["약속·일정 챙기기 좋은 날", "주변에 도움 줄 수 있는 일 1개", "집·환경 정돈", "내 페이스도 지키기 — 다 떠안지 않기"],
      "closingLine": "주변과 결이 맞아 흐름이 부드러워요."
    }
  }
}

{
  "dream": "바다에서 커다란 물고기를 두 손으로 잡는 꿈을 꿨어요"
}

{
  "success": true,
  "data": {
    "lang": "ko",
    "mode": "glossary",
    "items": [
      { "keywords": ["바다"], "score": 1 },
      { "keywords": ["물고기"], "score": 0.979 },
      { "keywords": ["손"], "score": 0.749 }
    ]
  }
}

"kbMatches": [
  {
    "ruleId": "R-DREAM-DRAGON-002",
    "area": "DRAGON",
    "polarity": "positive",
    "status": "verified",
    "statement": "『주공해몽서』(돈황본 P.3908, 第十二 龍蛇章)는 뱀(虵=蛇)이 길에 있는 꿈(夢見虵當道者)에 대해 「大吉」라고 적는다(글자대로: 크게 길하다).",
    "quote": {
      "text": "夢見虵當道者大吉",
      "sourceId": "SRC-DREAM-P3908",
      "source": "『周公解夢書』 (敦煌 P.3908)",
      "location": "P.3908 第十二 龍蛇章 f09/左/行3下",
      "foundAt": "dream-pd/dunhuang-p3908-bnf/P3908-TRANSCRIPTION-merged.md:198"
    },
    "caveatRuleIds": [],
    "matchedTerms": ["구렁이", "길"]
  }
]

{
  "modelName": "face_landmarker",
  "modelVersion": "float16/[email protected]",
  "normalization": "face-norm-1",
  "landmarks": [[0.5012, 0.3121, -0.031], … 478개 …],
  "imageWidth": 1080,
  "imageHeight": 1350,
  "hairline": [0.501, 0.182],
  "quality": { "yawDeg": 2.1, "pitchDeg": -3.4, "blendshapes": { "eyeBlinkLeft": 0.05, "jawOpen": 0.02 } }
}

{
  "success": true,
  "data": {
    "normalization": "face-norm-1",
    "keys": { "face.thirds.upper_ratio": 0.3333, "face.brow.length_vs_eye": 1.625, "face.brow.outer_overhang": 0.1648, … },
    "reasons": {},
    "quality": { "rollDeg": 0, "iodPx": 158, "flags": [] },
    "kbMatches": [
      {
        "ruleId": "R-FACE-PALACE-031",
        "area": "PALACE",
        "kind": "interpretation",
        "polarity": "positive",
        "status": "verified",
        "statement": "『古今圖書集成』 相術部彙考 「十二宮訣」 兄弟는 눈썹이 눈보다 길게 지나가면(眉長過目) …라고 적는다 …",
        "quote": { "text": "眉長過目，三四兄弟", "sourceId": "SRC-FACE-HUIKAO", "source": "…", "location": "…", "foundAt": "…" },
        "caveatRuleIds": ["R-FACE-CAVEAT-001"],
        "matchedConditions": [{ "key": "face.brow.outer_overhang", "op": "gt", "value": 0, "actual": 0.1648 }]
      }
    ]
  }
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "lang": "ko",
  "endUserId": "member-1024"
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "creases": [
    { "line": "life", "points": [[0.42, 0.38], [0.36, 0.52], [0.34, 0.71]] },
    { "line": "heart", "points": [[0.78, 0.33], [0.6, 0.31], [0.47, 0.34]] }
  ]
}

"processing": {
  "provider": "OpenAI",
  "model": "gpt-5.6-luna",
  "region": "US",
  "store": false,
  "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제",
  "imageStored": false
}

{
  "success": true,
  "data": {
    "items": [
      {
        "key": "forehead",
        "label": "이마",
        "observation": "이마가 넓고 둥글게 보여요.",
        "reason": "넓은 이마는 생각을 넓게 펼치는 쪽으로 읽혀요. 떠오른 계획을 글로 정리해 두면 장점이 더 살아나요."
      },
      {
        "key": "eyes",
        "label": "눈",
        "observation": "눈매가 길고 가로로 뻗어 있어요.",
        "reason": "긴 눈매는 사람과 상황을 찬찬히 살피는 쪽으로 읽혀요."
      }
    ],
    "summary": "생각을 넓게 펼치고 찬찬히 살피는 인상으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "image",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": []
    }
  }
}

{
  "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"], "strokes": [null, 5, 7], "meanings": ["쇠", null, null] },
  "birth": { "year": 1990, "month": 5, "day": 17, "hour": 9 },
  "consent": { "version": "name-consent-2026-10", "subject": "end_user" }
}

{
  "success": true,
  "data": {
    "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"] },
    "deterministic": {
      "surnameLength": 1,
      "syllables": [
        { "index": 0, "hangul": "김", "hanja": "金", "strokes": 8, "strokeSource": "kb", "strokeNote": null, "strokeRuleId": "R-NAME-STROKE-004", "soundElement": "wood", "soundRuleId": "R-NAME-SOUND-004", "meaning": "쇠", "rootElement": "metal" },
        { "index": 1, "hangul": "민", "hanja": "民", "strokes": 5, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "water", "soundRuleId": "R-NAME-SOUND-010", "meaning": null, "rootElement": null },
        { "index": 2, "hangul": "수", "hanja": "秀", "strokes": 7, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "metal", "soundRuleId": "R-NAME-SOUND-006", "meaning": null, "rootElement": null }
      ],
      "soundFlow": { "elements": ["wood", "water", "metal"], "relations": ["reverse_generating", "reverse_generating"], "generating": 0, "overcoming": 0, "score": 0.5 },
      "suri": {
        "won": { "sum": 12, "number": 12, "grade": "bad" },
        "hyung": { "sum": 13, "number": 13, "grade": "good" },
        "i": { "sum": 15, "number": 15, "grade": "good" },
        "jeong": { "sum": 20, "number": 20, "grade": "bad" }
      },
      "suriMissing": null,
      "yongshin": { "element": "wood", "supplied": true, "suppliedBy": ["sound"] },
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    },
    "interpretation": { "text": "첫 글자는 목, 가운데 글자는 수, 끝 글자는 금 기운이에요. 소리가 서로 부딪치지 않고 이어지는 이름으로 읽혀요." },
    "items": [
      { "key": "sound_flow", "label": "발음오행 흐름", "score": 0.5, "reason": "김(목(木)) → 민(수(水)) → 수(금(金)) · 상생 0 · 상극 0", "ruleId": "R-NAME-SOUND-011" },
      { "key": "suri_hyung", "label": "형격", "grade": "good", "score": 13, "reason": "획수 합 13 → 13수(길)", "ruleId": "R-NAME-MODERN-001" },
      { "key": "yongshin_match", "label": "용신 보완", "grade": "supplied", "reason": "용신 목(木)을 이름이 발음으로 채워 줘요" }
    ],
    "summary": "부드럽게 이어지는 소리에 용신 기운이 담긴 이름으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "name",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    }
  }
}

Tarot API

POST /api/v1/partners/v1/tarot

Set a number of cards (count, 1~10) or a spread (spread), and cards are drawn without repeats from a 78-card deck (22 major · 56 minor). For each card you get upright/reversed, keywords, meaning and the card image URL. There is no AI interpretation — the meaning is the fixed text for that card. That gives you three ways to use it.

• Build an app with Tarot alone — draw the card names, meanings and images from the response straight onto the screen.
• Tarot + LLM interpretation — pass the drawn cards into the LLM API and write your own reading.
• Combine with Saju AI — add tarot to an AI Saju Reading request and the Tarot is read together with the Saju reading (included modules).

Request parameters

Request example

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

curl -X POST https://api.hrum.ai/api/v1/partners/v1/tarot \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "lang": "en", "reversed": false}'

Response example (one card excerpted)

{
  "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
  }
}

• cards[]: position (from 1, draw order = spread position) · positionLabel (spread position name, null when drawn with count) · id (language-independent card ID) · name (requested language) · nameEn · arcana (major | wands | cups | swords | pentacles) · reversed · keywords·meaning (for the drawn orientation) · imageUrl.
• spread: null when drawn with count.
• Card images: imageUrl·cardBackUrl are WebP (600px wide), and the URL contains a version (v2), so it does not change — you can fetch, cache and reuse them. Show reversed cards by rotating the image 180 degrees (there is only one, upright, image per card).
• Image source: scans of the original 1909 Rider-Waite deck (Pamela Colman Smith, public domain). All 78 cards and the back are 1909 original-deck scans from Wikimedia Commons; per-file sources and licenses are in the source ledger. The old URLs (v1) return the same images, so there is no need to change URLs you already stored.
• costPoints: the amount deducted for this call (₩).

Pricing

• One flat fee per call — the same whether you draw 1 card or 10. The price is in the calculation APIs table under pricing. Only successful calls are charged, and repeated calls with the same input are each charged (idempotency).
• Input errors (400) and insufficient balance (402) are not charged. The usage-log endpoint is tarot.
• Calling it before it is open returns 404 tarot_not_enabled (not charged).

Waite source text kb

Once open, kb is added to the response. For each drawn card, it returns the card's upright and reversed meanings from the original text of A. E. Waite, The Pictorial Key to the Tarot (1910, public domain), with rule IDs (R-TAROT-*) and quotes from the original. meaning·keywords above stay as they are; only kb is added, and the price is the same.

• kb.cards[]: position · id · reversed · drawn (meaning for the drawn orientation) · upright · reversedMeaning · positionRule. Each meaning has ruleId · status · statement (Korean) · quotes[] (quote original English text, location section, foundAt line in the original) · variants[] (other descriptions Waite gave, alternative; additional meanings from Part III §4, additional).
• status uses the KB marking as is (verified = original quote present). Where Waite gave no meaning (Two of Cups reversed), it is ruleId: null, status: "disputed".
• method: "celtic-cross": the Celtic method of divination Waite describes in the book (10 cards). Send it instead of count·spread; Waite's meaning for each of the 10 positions comes in positionRule. Other spreads are layouts not in Waite's text, so they have no position source (kb.method: null).
• kb.caveats: Waite's note that meanings change with position, and usage principles (it is a tool for divination and does not replace health, legal or financial decisions).
• Sending method before it is open returns 404 tarot_kb_not_enabled (not charged).

{
  "method": "celtic-cross",
  "seed": "user-1042:2026-10-11"
}

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Send exactly one of count·spread·method. Two or more, or none, gets the common 400.

Natal Chart API (Western astrology) Discontinued

POST /api/v1/partners/v1/natal-chart

Computes a Western astrology natal chart (positions of 7 bodies — Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn — plus the Ascendant) from the date and time of birth. Uranus, Neptune and Pluto are not included. It uses the tropical zodiac of Western astrology, not the solar terms.

Request parameters

Response fields

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/natal-chart \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-05-15",
    "birthTime": "12:00",
    "birthLatitude": 37.5665,
    "birthLongitude": 126.978,
    "birthTimezoneOffset": 540,
    "birthTimePrecision": "exact"
  }'

Response example

{
  "success": true,
  "data": {
    "sun": {
      "body": "Sun",
      "sign": "황소자리",
      "signEn": "Taurus",
      "element": "흙",
      "degreeInSign": 24.03,
      "eclipticLongitude": 54.0343
    },
    "moon": { "body": "Moon", "sign": "염소자리", "signEn": "Capricorn", "element": "흙", ... },
    "mercury": { "body": "Mercury", "sign": "황소자리", "signEn": "Taurus", ... },
    "venus": { "body": "Venus", "sign": "양자리", "signEn": "Aries", "element": "불", ... },
    "mars": { ... },
    "jupiter": { ... },
    "saturn": { ... },
    "ascendant": {
      "body": "Ascendant",
      "sign": "사자자리",
      "signEn": "Leo",
      "element": "불",
      "degreeInSign": 23.13,
      "eclipticLongitude": 143.1256
    },
    "coordsBasis": "coords",
    "engineVersion": "natal-2"
  }
}

Request for the example above: {"birthDate": "1990-05-15", "birthTime": "12:00", "birthLatitude": 37.5665, "birthLongitude": 126.978, "birthTimezoneOffset": 540, "birthTimePrecision": "exact"} (excerpt of actual engine output).

{
  "success": true,
  "data": {
    "sun": { ... }, "moon": { ... }, ...,
    "readings": {
      "dignities": [
        { "key": "Me_dom", "lang": "ko",
          "text": "수성이 본궁인 쌍둥이자리나 처녀자리에 있으면 정보를 모으고 분류해 말로 옮기는 기능이 막힘없이 또렷하게 드러나요. 생각이 많아질 때 하나를 골라 끝까지 파고들면 그 명료함이 실제 성과로 이어져요." },
        { "key": "Sa_dom", "lang": "ko",
          "text": "토성이 본궁인 염소자리나 물병자리에 있으면 책임을 지고 구조를 세워 반복 훈련으로 숙련을 쌓는 기능이 막힘없이 또렷하게 드러나요. 기준이 지나치게 굳어질 때 쉬어 갈 틈을 일정에 남겨 두면 그 인내가 성숙하게 쓰여요." }
      ],
      "aspects": [
        { "key": "Me_Sa_tr", "deviation": 0.04, "lang": "ko",
          "text": "수성과 토성의 트라인은 절제와 의지를 생각에 더해, 서두르지 않고 앞을 내다보며 구조를 짜는 데 힘이 실려요. 변화가 필요한 순간에 익숙한 방식만 고집할 수 있으니 새 방법도 한 번 시험해 보세요." },
        { "key": "Mo_Ma_sq", "deviation": 1.03, "lang": "ko",
          "text": "달과 화성이 스퀘어를 이루면 감정이 올라오는 순간 욱하거나 규칙에 반발하는 쪽으로 기울 수 있어요. 화가 난 뒤 반응을 한 템포 늦추는 연습을 하면 그 뜨거움이 지켜야 할 것을 지키는 힘으로 바뀌어요." }
      ],
      "lang": "ko",
      "costWon": 20
    }
  }
}

Notes

• Price: ₩20 / call (pay as you go) · +₩20 with readings: true (₩40 total)
• Date validation: an invalid date (e.g. Feb 30) or invalid coordinates/timezone returns a 400 error and is not charged.
• Ascendant calculation: needs the birth time + birthTimePrecision (exact/approximate; exact if omitted) + latitude/longitude. If any is missing, ascendant is null.
• Reading paragraph errors: readings: true without the feature enabled for the account gives 404 natal_readings_not_enabled; failure to load the paragraphs gives 503 natal_readings_unavailable — neither is charged.
• Sun/Moon/Ascendant: every planet and angle uses the tropical zodiac (the Western astrology standard).
• Changed 2026-10-17 (engineVersion natal-2): if you send birthTime and omit birthTimePrecision, that time is now used (previously the time was ignored, the chart was calculated at noon and the Ascendant was null). This is the same rule as other endpoints. Calls without birthTime or with an explicit precision give the same results as before.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Astrology Total API

Like Manseryeok, it returns all the astrology calculations in one call. The default is the full natal chart (10 bodies from the Sun to Pluto · lunar nodes · 4 angles · houses (Placidus by default) · aspects · dignities). Add blocks to the request and transits + secondary progressions (timing) and two-person synastry (partner) come in the same response. Use only the parts you need. No LLM is used. Besides numbers and rule keys (features), HRUM's pre-written reading paragraphs (readings) always come along at no extra charge. It is the same shared astrology engine as INTA, and body positions were checked against NASA/JPL Horizons and Swiss Ephemeris reference values (planets within 0.005°). All interpretive parameters (orbs, aspect types, dignity tables) come from rules in classical sources, and for values where the sources disagree (transit and progression orbs), there is no default — you choose (see "Defaults and values you must choose" below).

POST /api/v1/partners/v1/astrology

Birth input is the same as the Natal Chart API (birthDate · birthTime · birthTimePrecision · birthLatitude · birthLongitude · birthTimezoneOffset, default 540 = KST; Korean daylight saving time and the 1954~61 UTC+8:30 period are applied automatically). If birthTimePrecision is omitted, it is unknown (noon-based).

Inside the timing block:

Request example 1 — default (natal only)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["placidus", "whole_sign"]
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "birthLatitude": 37.5665, "birthLongitude": 126.978, "minorAspects": true, "lang": "en"}'

Response example 1 (excerpt, actual engine output)

{
  "success": true,
  "data": {
    "natal": {
      "utc": "1990-05-15T05:30:00.000Z",
      "timePrecision": "exact",
      "timeKnown": true,
      "zodiac": "tropical",
      "lang": "ko",
      "bodies": [
        { "id": "Sun", "longitude": 54.1347, "sign": "Taurus", "signKey": "tau", "signName": "황소자리", "degreeInSign": 24.1347, "speed": 0.9643, "retrograde": false, "dignities": [], "house": { "placidus": 9, "whole_sign": 9 } },
        { "id": "Moon", "longitude": 293.8244, "sign": "Capricorn", "signKey": "cap", "signName": "염소자리", "degreeInSign": 23.8244, "speed": 12.2943, "retrograde": false, "dignities": ["det"], "house": { "placidus": 4, "whole_sign": 5 } },
        ...
      ],
      "nodes": [
        { "id": "MeanNode", "longitude": 311.3535, "sign": "Aquarius", "signName": "물병자리", "speed": -0.0529,
          "south": { "longitude": 131.3535, "sign": "Leo", "signName": "사자자리", ... } },
        { "id": "TrueNode", ... }
      ],
      "angles": { "asc": 173.5996, "mc": 82.8067, "dsc": 353.5996, "ic": 262.8067,
        "ascSign": { "sign": "Virgo", "signName": "처녀자리", ... }, "mcSign": { ... }, "dscSign": { ... }, "icSign": { ... }, "polar": false },
      "anglesOmitted": null,
      "houseSystems": ["placidus", "whole_sign"],
      "houses": {
        "placidus": { "cusps": [173.5996, 199.6989, 229.8749, ...], "bodies": { "Sun": 9, "Moon": 4, "Jupiter": 10, ... } },
        "whole_sign": { "cusps": [150, 180, 210, ...], "bodies": { "Sun": 9, "Moon": 5, ... } }
      },
      "housesExcluded": [],
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Jupiter", "b": "Uranus", "type": "opposition", "code": "op", "key": "Ju_Ur_op", "separation": 179.6986, "orb": 0.3014, "orbLimit": 8, "strength": "exact", "applying": false, "outOfSign": false },
        { "a": "Sun", "b": "Moon", "type": "trine", "code": "tr", "key": "Su_Mo_tr", "orb": 0.3104, "orbLimit": 8, "strength": "exact", "applying": true, "outOfSign": false },
        ...
      ],
      "dignities": { "Sun": [], "Moon": ["det"], "Mercury": [], "Venus": ["det"], "Mars": [], "Jupiter": ["exa"], "Saturn": ["dom"] },
      "moonSignUncertain": false,
      "features": [
        { "type": "planet_sign", "key": "Su_tau" },
        { "type": "dignity", "key": "Mo_det" },
        { "type": "planet_retrograde", "key": "Me_rx" },
        { "type": "planet_house", "key": "Su_h9", "system": "placidus" },
        { "type": "aspect", "key": "Su_Mo_tr", "strength": "exact", "applying": true, "orb": 0.31 },
        { "type": "meta", "key": "time_known" },
        ...
      ]
    },
    "readings": {
      "dignities": [
        { "key": "Mo_det", "text": "달이 염소자리에서 손상 자리에 있으면 감정을 바로 내보이기보다 책임과 일의 질서 속에서 조심스럽게 다루는 경향이 있어요. ...", "lang": "ko" },
        { "key": "Ve_det", ... }, { "key": "Ju_exa", ... }, { "key": "Sa_dom", ... }
      ],
      "aspects": [
        { "key": "Su_Mo_tr", "text": "태양과 달의 트라인은 의지와 정서가 같은 곳을 바라봐, 스스로 길을 내며 생활 전반을 고르게 꾸려 가는 힘이 실려요. ...", "lang": "ko", "deviation": 0.31 },
        { "key": "Su_Sa_tr", ... }, { "key": "Mo_Sa_cj", ... }, ...
      ],
      "lang": "ko"
    },
    "readingsUnavailable": false,
    "costPoints": 50
  }
}

If you do not send timing·partner, the response has no timing·synastry keys at all.

• bodies[]: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto. longitude is ecliptic longitude (0° = vernal equinox, tropical), speed is degrees/day — negative means retrograde: true. Each body carries signName (sign name in the lang language) · degreeInSign (degree within the sign, 0~30°) · house (house number per requested house system, the same value as houses[system].bodies — {} if houses are not calculated), so you can draw a chart table from this alone.
• dignities: dignities of the Sun through Saturn (dom domicile · exa exaltation · det detriment · fal fall, every state that applies). Same values as bodies[].dignities.
• nodes[]: MeanNode (mean node) · TrueNode (true node) = North Node, south = South Node (+180°).
• angles: ASC·MC·DSC·IC. Calculated only when both the birth time (exact/approximate) and coordinates are present. Otherwise null, and anglesOmitted gives the reason (time_unknown | coordinates_missing). In that case houses are not calculated either, and houses is {}.
• houses: per requested system, cusps (starting ecliptic longitude of houses 1~12) + bodies (house number per body).
• houseSystems·houses: the systems actually calculated. For birthplaces inside the polar circles (angles.polar = latitude above about 66.56°), Placidus may be undefined, so Porphyry is calculated instead and marked with houses.porphyry.fallbackFrom = "placidus" (it is never switched silently). The check uses the birthplace latitude, so the same birthplace always gets the same system regardless of time. housesExcluded lists any other systems that could not be calculated, with the reason (this is not an error response).
• aspects[]: orb = degrees off exact, strength = exact (within 2°) · close (within half the limit) · wide, applying = true if moving toward exact (null if unknown), outOfSign = an aspect that crosses a sign boundary (read one step weaker).
• moonSignUncertain: when the time is unknown, true if the Moon changes sign during that day — in that case the Moon's planet_sign in features carries "uncertain": true.
• readings (always included, no extra charge): reading paragraphs pre-written by HRUM. dignities[] = dignities (Sun through Saturn, one strongest state per body), aspects[] = aspects between natal bodies, tightest orb first. Each paragraph has key (same key as in features·aspects[].key) · text · lang (the paragraph's actual language — ko if there is no paragraph in the requested language) · deviation (aspects only, degrees off exact). Only keys with a pre-written paragraph are included and the rest are skipped (nothing is written on the fly) — aspects involving Uranus, Neptune or Pluto and minor aspects have no paragraphs and are left out. Without a birth time, aspects involving the Moon are not included; if the Moon sign is uncertain, the Moon's dignity is not included. The example above (1990-05-15 14:30, Seoul) has 7 of 16 aspects + 4 dignities = 11 paragraphs.
• readingsUnavailable: true if the reading paragraphs could not be loaded — the chart calculation still comes back as is, readings is an empty array, and the price (₩50) stays the same.
• features[]: keys for matching against a rule database. planet_sign Su_ari · planet_retrograde Me_rx · dignity Ma_dom · node_sign MNn_leo·TNn_leo·Nn_leo·Sn_aqu (Nn·Sn are the node chosen by the node option) · angle_sign Asc_sco · planet_house Ve_h7 (+system) · aspect Su_Mo_cj (for nodes, conjunction only, 3° — Mo_Nn_cj·Sa_Sn_cj·Nn_Asc_cj; Ascendant pairs only when the birth time is present) · house_cusp_sign h12_ari (12th-house cusp in Aries) · house_empty h6 (a house with none of the 10 planets) · house_ruler_house h1_h7 (ruler of the 1st house in the 7th) · house_ruler_sign h7_lib (ruler of the 7th house in Libra) — the house ruler is the traditional ruler of the cusp sign (the 7 planets from Sun to Saturn) · planet_rising Ju (in the 1st house, or in the 12th within 6° of the Ascendant) — these five kinds carry +system and appear only when birth time and coordinates are present · planet_solar Ve_cazimi (within 17′ of the Sun) / Me_combust (17′~8°30′, in the same sign as the Sun) / Ma_beams (otherwise within 17°) — the three levels do not overlap · moon_phase waxing·waning · meta time_known (time present — exact·approximate) / time_hour_level (added for approximate) / time_unknown. Aspect keys (aspect·transit·progressed·syn_aspect) carry orb (degrees off exact, two decimal places), plus "outOfSign": true only when the aspect crosses a sign boundary — values to match the rule-key attributes [orb=…]·[outOfSign=true]. If the birth time is unknown, natal aspects involving the Moon carry "uncertain": true. Body abbreviations Su Mo Me Ve Ma Ju Sa Ur Ne Pl, nodes MNn TNn Nn Sn, aspect codes cj (0°) sx (60°) sq (90°) tr (120°) op (180°) · minor ssx (30°) ssq (45°) sqq (135°) qcx (150°).

Request example 2 — with timing (transits + secondary progressions)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "timing": { "at": "2026-10-11T09:00:00+09:00", "orbDegrees": 3, "yearLength": "tropical" }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "timing": {"orbDegrees": 2, "progressions": false}}'

Response example 2 (excerpt; natal has the same shape as example 1)

{
  "success": true,
  "data": {
    "natal": { ... },
    "timing": {
      "at": "2026-10-11T00:00:00.000Z",
      "orbDegrees": 3,
      "natalPoints": ["Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Asc", "MC"],
      "transits": {
        "bodies": [ { "id": "Sun", "longitude": 197.6966, "sign": "Libra", "signName": "천칭자리", "speed": 0.9889, "retrograde": false, ... }, ... ],
        "aspects": [
          { "a": "Mars", "b": "Mercury", "type": "square", "key": "tMa_nMe_sq", "orb": 0.6358, "orbLimit": 3, "strength": "exact", "applying": true, "outOfSign": false },
          ...
        ]
      },
      "progressions": {
        "yearLength": "tropical",
        "yearLengthDays": 365.24219,
        "ageYears": 36.4081,
        "instant": "1990-06-20T15:17:39.048Z",
        "bodies": [ { "id": "Sun", "longitude": 89.0352, "sign": "Gemini", "signName": "쌍둥이자리", ... }, ... ],
        "aspects": [
          { "a": "Uranus", "b": "Mercury", "type": "trine", "key": "pUr_nMe_tr", "orb": 0.0862, "orbLimit": 3, "strength": "exact", "applying": false, "outOfSign": false },
          ...
        ]
      },
      "features": [
        { "type": "transit", "key": "tMa_nMe_sq", "strength": "exact", "applying": true, "orb": 0.64 },
        { "type": "progressed", "key": "pUr_nMe_tr", "strength": "exact", "applying": false, "orb": 0.09 },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• Transit targets (natalPoints): the 10 natal bodies, plus the Ascendant (Asc) and Midheaven (MC) if birth time and coordinates are present. Keys use the prefixes t (transit) and n (natal) — tSa_nSu_cj = transiting Saturn conjunct natal Sun.
• transit_house tSa_h7 (transiting Saturn in the natal 7th house) · progressed_house pMo_h4 (progressed Moon in the natal 4th house): 10 planets each. Natal houses use the default system (Placidus; Porphyry + "fallbackFrom": "placidus" in polar regions), and the keys carry "system" — even if you send a different houseSystems, these two keys use the default system. They do not appear without birth time or coordinates.
• Progressed→natal aspects target natal planets only. Key pSu_nJu_tr = progressed Sun trine natal Jupiter. instant is the moment of the sky used for the progressed chart (birth + ageYears days).
• With progressions: false, timing.progressions is null. If yearLength is omitted, it is tropical (365.24219 days).
• With progressions on, a timing.at earlier than the birth time returns 400 at_before_birth (not charged).
• If the time is unknown, the natal chart is set at noon. Keys targeting the natal Moon (…_nMo_…) and progressed-Moon keys (pMo_…) carry "uncertain": true (the progressed Moon inherits the natal Moon position, so it varies by as much as the noon assumption).

Request example 3 — with partner (synastry)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "partner": { "birthDate": "1992-11-03", "birthTime": "08:10", "birthTimePrecision": "exact", "birthLatitude": 35.1796, "birthLongitude": 129.0756 }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "partner": {"birthDate": "1992-11-03"}}'

Response example 3 (excerpt; natal has the same shape as example 1)

{
  "success": true,
  "data": {
    "natal": { ... },
    "synastry": {
      "partner": {
        "utc": "1992-11-02T23:10:00.000Z",
        "timePrecision": "exact",
        "timeKnown": true,
        "moonSignUncertain": false,
        "bodies": [ { "id": "Sun", "longitude": 220.7903, "sign": "Scorpio", "signName": "전갈자리", "speed": 1.0016, "retrograde": false, "dignities": [], ... }, ... ],
        "angles": { "asc": 252.31, "mc": 175.86, "ascSign": { "sign": "Sagittarius", "signName": "사수자리", ... }, "mcSign": { "sign": "Virgo", "signName": "처녀자리", ... } },
        "anglesOmitted": null
      },
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Moon", "b": "Mars", "type": "opposition", "code": "op", "key": "aMo_bMa_op", "orb": 0.2993, "orbLimit": 10, "strength": "exact", "applying": null, "outOfSign": false },
        { "a": "Neptune", "b": "Uranus", "type": "conjunction", "code": "cj", "key": "aNe_bUr_cj", "orb": 0.3898, "orbLimit": 8, "strength": "exact", "applying": null, "outOfSign": false },
        ...
      ],
      "features": [
        { "type": "syn_aspect", "key": "aMo_bMa_op", "strength": "exact", "orb": 0.3 },
        { "type": "syn_aspect", "key": "aNe_bUr_cj", "strength": "exact", "orb": 0.39 },
        { "type": "astro_syn", "key": "Su_Mo_se" },
        { "type": "syn_sign", "key": "aAsc_bAsc_es" },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• Key prefixes: a = the requesting person, b = partner. aVe_bMa_cj = your Venus conjunct the partner's Mars. Every combination of your 10 bodies (+Ascendant, Midheaven) × the partner's 10 bodies (+Ascendant, Midheaven) is checked (direction matters, so aSu_bMo and aMo_bSu are different keys).
• The Ascendant (Asc) and Midheaven (MC) are calculated only when that person's birth time and coordinates are both present (same rule as for you; for the partner, see synastry.partner.angles/anglesOmitted). Cross aspects involving angles are checked as conjunction and opposition only, at 6°. The one exception is Ascendant–Ascendant conjunction (aAsc_bAsc_cj), allowed up to 17° (Ptolemy's Tetrabiblos — two Ascendants within 17° make a strong bond, rule [orb=17]). The actual separation comes in orb. An angle is calculated whenever the time of the person who owns that angle is known. The Descendant and IC are exact opposites of the Ascendant and Midheaven, so they get no separate keys.
• astro_syn: the 2 strongest sign relations among the 6 classical pairs (Sun–Moon, Venus–Mars, Moon–Venus, Sun–Venus, Moon–Mars, Venus–Saturn). Both directions fold into one key (Su_Mo_se = one person's Sun and the other's Moon share an element). syn_sign: sign relations for every point of yours × every point of the partner's (aAsc_bAsc_ss). If both people's birth times are exact, the Part of Fortune (PoF, day/night formula reversed) is also included as a point (aPoF_bPoF_ss) — the Part of Fortune moves with the Ascendant at about 1° per 4 minutes, so it is not produced for hour-level (approximate) or unknown times. Relation codes: ss (same sign) · op (opposite sign) · se (same element) · es (supporting element) · sm (same modality) · ef (element friction) · nt (unrelated).
• The orb table and minor-aspect setting use the same orbs·minorAspects as the natal chart. Between two natal charts there is no applying or separating, so applying is always null.
• If either person's birth time is unknown, that person's chart is set at noon. Aspects involving that person's Moon carry "uncertain": true in features (the Moon moves about 13° a day, more than the orb). The same applies to aspects paired with the partner's angles (aAsc_bMo_…, and in the other direction aMo_bAsc_…).
• The partner's houses are not calculated (synastry house overlays are not provided).

Defaults and values you must choose

• House system (default placidus): the system the 1819 and 1929 dictionaries describe as "in common use". In polar regions it is replaced by Porphyry and marked with fallbackFrom. If you need another system, choose it with houseSystems.
• Progression year length (default tropical, 365.24219 days): the source texts' "birthday to next birthday" year. The difference from the Julian year (julian) is about 2.5 minutes of progressed time at age 80.
• Transit and progression orb (timing.orbDegrees, required when you send timing): the sources disagree (a range of 8° to 10° before exact). Leaving it empty returns 400.
• Natal aspects involving Pluto, the nodes or the angles are not in the default orb tables: these are points the Leo (1928) and Heindel (1919) orb tables do not cover (Pluto was discovered in 1930). So these points do not appear in natal aspects (they do appear in positions and houses). Only angle cross aspects in synastry are checked, as conjunction/opposition at 6° (Ascendant–Ascendant conjunction only at 17°).

Not provided

• Minor dignities (triplicity, terms, faces), reception, the natal Part of Fortune (used only in synastry syn_sign), dignities of Uranus, Neptune and Pluto, parallels and midpoints
• Progressed angles (progressed ASC·MC) — the sources do not define a method
• DSC·IC values are given, but no features keys are produced for them (the South Node comes as the Sn key)
• New Moon, Full Moon, first quarter and last quarter phase keys (moon_phase is waxing·waning only), oriental/occidental of the Sun, progressed-angle keys
• Synastry house overlays

Pricing

• ₩50 per call, the same as Manseryeok — adding timing·partner blocks, house systems or minor aspects does not change it: one ₩50 charge. The response's costPoints is the amount deducted (₩). The usage-log endpoint is astrology.
• Deducted only when the calculation succeeds. Input errors (400) and insufficient balance (402) are not charged.
• Calling it before it is open returns 404 astrology_not_enabled (not charged).

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Fortune Flow API

From one person's Saju, it calculates how the 10-year luck cycles (Daeun), annual luck (Seun) and monthly luck layer onto the natal chart, and returns numbers for graphs plus a list of relations. One person per call; no LLM. The vertical-axis value is "the Day Master-side score with the luck characters added" — the natal chart's total strength score plus, for each luck character, a share scored with the same per-character table as the natal chart (support, control, hidden stems, roots), clipped to ±100. It does not measure whether fortune is good or bad (R-SAJU-UN-034). The labels strong, balanced and weak (Day Master strength) are those of the natal chart and are not reassigned by luck.

Price: ₩50 per call (same as Manseryeok; the same price even with a wider range or monthly luck). Failed responses such as 400 are not charged.

All numbers come from the same shared Saju engine as INTA. The birth time is read as Korean standard time wall-clock history (1954~61 UTC+8:30, daylight saving time applied automatically) and compared against the solar-term start, so results are the same regardless of server time zone.

Birthplace (added 2026-10-15, saju-flow-5): accepts the same fields as the Manseryeok API (birthLatitude·birthLongitude·country·birthTimePrecision) and applies true solar time correction the same way. When the birth time is close to an hour-pillar, day-pillar or solar-term boundary, the correction changes natal chart characters, so send Fortune Flow the same location you sent Manseryeok to make both results use the same natal chart. Without a location, it uses the same default handling as Manseryeok called without a location (currently no correction) and reports that default in the response's assumedLocation.

POST /api/v1/partners/v1/saju-flow

Request example

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "calendar": "solar",
  "gender": "male",
  "timezone": "Asia/Seoul",
  "range": { "fromYear": 1990, "toYear": 2090 },
  "monthsOfYear": 2026
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-flow \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: chart-123:flow:2026" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "calendar": "solar", "gender": "male", "timezone": "Asia/Seoul", "range": {"fromYear": 1990, "toYear": 2090}, "monthsOfYear": 2026}'

Response example (excerpt, actual engine output)

{
  "success": true,
  "data": {
    "engineVersion": "saju-flow-6",
    "kbVersion": "2026.10.11-7",
    "hourKnown": true,
    "natalAmbiguous": null,
    "natal": {
      "score": -37, "result": "중화", "level": "약약",
      "breakdown": { "season": -30, "support": 36, "control": -28, "hidden": -5, "root": 5 },
      "primaryYongshin": "토",
      "shin": { "yongshin": "토", "huishin": "화", "gishin": "목", "gushin": "수", "hanshin": "금" },
      "ruleIds": ["R-SAJU-STR-001", "R-SAJU-STR-018", "R-SAJU-STR-019", "R-SAJU-YONG-170"]
    },
    "daeun": [
      { "startYear": 1997, "endYear": 2006, "startAge": 7,
        "chars": [
          { "pos": "stem", "char": "임", "hanja": "壬", "ohaeng": "수", "sipsin": "식신", "shinRole": "gushin",
            "share": { "support": 0, "control": -8, "hidden": 0, "root": 0, "total": -8 } },
          { "pos": "branch", "char": "오", "hanja": "午", "ohaeng": "화", "sipsin": "정관", "shinRole": "huishin",
            "share": { "support": 0, "control": -10, "hidden": -5, "root": 0, "total": -15 } }
        ],
        "delta": -23, "line": { "value": -60, "clamped": false },
        "relations": [
          { "type": "자형", "from": "daeun", "with": "yearBranch", "a": "오", "b": "오", "ruleId": "R-SAJU-REL-044", "decisionRuleId": "R-SAJU-UN-036" },
          { "type": "육합", "from": "daeun", "with": "hourBranch", "a": "오", "b": "미", "ruleId": "R-SAJU-REL-015", "decisionRuleId": null }
        ],
        "triples": [], "hapPulim": [ ... ] },
      ...
    ],
    "years": [
      { "year": 2026, "daeunIndex": 2,
        "chars": [ { "pos": "stem", "char": "병", "hanja": "丙", ... "share": { ..., "total": -10 } },
                   { "pos": "branch", "char": "오", "hanja": "午", ... "share": { ..., "total": -15 } } ],
        "delta": -25, "line": { "value": -33, "clamped": false },
        "relations": [
          { "type": "천간합", "from": "seun", "with": "monthStem", "a": "병", "b": "신", "ruleId": "R-SAJU-REL-003", "decisionRuleId": null },
          ...
        ],
        "withDaeun": [], "triples": [],
        "hapPulim": [
          { "kind": "existing", "domain": "jiji", "pair": ["오", "미"], "status": "broken_by_dong",
            "reasonCode": "branch_hap_broken", "params": { "incoming": "오", "origin": "seun" },
            "triggeredBy": { "origin": "seun", "value": "오" },
            "reasonFallback": "동기 오(seun) 도래 → 합반 깨짐" },
          { "kind": "new", "domain": "cheongan", "pair": ["병", "신"], "chartValue": "신", "incomingValue": "병", "incomingOrigin": "seun",
            "reasonCode": "new_stem_hap", "params": { "incoming": "병", "origin": "seun", "partner": "신" },
            "reasonFallback": "병(seun) + 원국 신 → 새 천간 합 형성" },
          ...
        ],
        "ipchunNote": false },
      ...
    ],
    "months": [
      { "index": 1, "startsAt": "2026-02-04T04:55:00+09:00",
        "chars": [ { "pos": "stem", "char": "경", ... }, { "pos": "branch", "char": "인", ... } ],
        "delta": 4,
        "relations": [ { "type": "반합", "from": "wolun", "with": "yearBranch", "a": "인", "b": "오", "ruleId": "R-SAJU-REL-024", "decisionRuleId": "R-SAJU-UN-035" }, ... ] },
      ...
    ],
    "compatInputs": {
      "primaryYongshin": "토",
      "surfaceElementCounts": { "목": 0, "화": 2, "토": 2, "금": 3, "수": 1 },
      "surfaceAbsent": ["목"],
      "hourKnown": true,
      "ruleIds": ["R-SAJU-COMPAT-008", "R-SAJU-COMPAT-009", "R-SAJU-COMPAT-010"]
    },
    "caveats": ["R-SAJU-UN-028", "R-SAJU-PRAC-026", "R-SAJU-UN-034"],
    "birthBeforeIpchun": false,
    "assumedLocation": { "correction": "none" },
    "costPoints": 0
  }
}

Reading the fields

• line: cumulative value — for 10-year luck, natal chart + 10-year luck; for annual luck, natal chart + that year's 10-year luck + annual luck. Each step is clipped to ±100, with clamped: true if clipped (R-SAJU-UN-033). Monthly luck has no cumulative line; only that month's share (delta) is given.
• share: the breakdown of one character's share (support, control, hidden stems, roots). Layer weights are 1:1:1 for 10-year, annual and monthly luck (R-SAJU-UN-030), and roots from luck branches have no cap (R-SAJU-UN-031).
• shinRole: the five-role name for that character's element (Yongsin, Huisin, Gisin, Gusin, Hansin — favorable, helpful, unfavorable, harmful and neutral elements; R-SAJU-YONG-170) — a name, not a score. Every chart gets a five-role table (never null).
• relations: the list of combinations, clashes and punishments between luck characters and natal characters (not added to the score). ruleId is the pair-table rule, decisionRuleId is the rule that justifies applying it to luck too (UN-035 monthly luck, UN-036 self-punishment, UN-037 half combination). withDaeun is annual luck ↔ that year's 10-year luck. If the hour pillar is unknown, relations with the hour pillar are not produced.
• triples: cases where a 10-year or annual luck character completes a three-character Samhap (triple combination) or Banghap (directional combination) together with the natal chart (R-SAJU-UN-037).
• hapPulim: natal combinations touched by 10-year or annual luck characters (combination triggered, released, broken) and newly formed combinations (R-SAJU-HAP-021~027). Monthly luck is not included. Build on-screen text yourself in the app's language from reasonCode and params (incoming the incoming luck character, origin daeun|seun, and target·partner when needed). reasonFallback is always present as a Korean sentence written by the engine, meant only as a fallback to show when the app receives a reasonCode it does not know. There are currently 7 reasonCodes.
  • stem_hap_kept_jaenghap: the natal Heavenly Stem combination stays intact, and a luck character of the same yang stem (incoming) cannot interfere because it is a competing combination (jaenghap).
  • stem_hap_kept_tuhap: the natal Heavenly Stem combination stays intact, and a luck character of the same yin stem (incoming) cannot interfere because it is a jealous combination (tuhap).
  • branch_hap_gi: a luck character (incoming) clashes with one character (target) of a natal six-combination, triggering the combination (hapgi).
  • branch_hap_released: a luck character (incoming) punishes one character of a natal six-combination, releasing the combination.
  • branch_hap_broken: a character identical to one character of a natal six-combination (incoming) arrives through luck, breaking the combination.
  • new_stem_hap: a luck Heavenly Stem (incoming) and a free natal Heavenly Stem (partner) form a new stem combination.
  • new_branch_yukhap: a luck Earthly Branch (incoming) and a natal Earthly Branch (partner) form a new six-combination.
• startAge: the Daeun starting number (age of the first 10-year cycle). Days are counted from 00:00 of the birth date (Korean date) to the solar-term start, without the hour and minute of birth, and rounded with 3 days = 1 year (R-SAJU-UN-038). This rule has been in the ledger since kbVersion 2026.10.11-2.
• ipchunNote: true on the current year's slot only, if the moment of the query (Korea time) is before that year's Ipchun. It marks that from Jan 1 to before Ipchun, the previous year's annual luck is still running. Annual luck uses that year's Ipchun stem-branch (R-SAJU-UN-016).
• birthBeforeIpchun: true if born between Jan 1 and before Ipchun, so the natal year pillar is the previous year's stem-branch (top-level field).
• assumedLocation (since saju-flow-5, top-level field): the default used for the calculation when no location was sent. Currently { "correction": "none" } (no true solar time correction), the same as Manseryeok. If Manseryeok's default changes to a representative longitude, you will get { "correction": "trueSolarTime", "longitude": … }. null if a location (birthLatitude·birthLongitude or country) was sent.
• natalAmbiguous: when the time is unknown and a solar term starts on the birth date, { "pillar": "month" | "year", "termAt" } — the engine decides at noon, so this marks that the month pillar (and the year pillar too, for Ipchun) may differ from reality.
• compatInputs: values that let the app do only set intersections when overlaying several people (Yongsin element, counts of visible characters' elements, elements not visible). No summing or ranking between people is produced.

Pricing

• If sales are switched off, it returns 404 saju_flow_not_enabled (not charged).
• Deducted only when the calculation succeeds. Input errors (400 — a date that does not exist, a range over 101 years, etc.) and 409 are not charged. The response's costPoints is the amount deducted (₩), and the usage-log endpoint is saju-flow.

Error codes

Besides the common errors (401, 400 body validation, 402, 429, 503, etc.), this API returns:

Compatibility API

Calculates the compatibility of two people from their Saju (Four Pillars of Destiny). In one call it returns Saju compatibility (60×60 day-pillar compatibility table · scores and six axes by purpose · Heavenly Stem / Earthly Branch relations · Five Elements balance across all eight characters · Ten Gods · cross Sinsal (symbolic stars)), the intimacy symbol table (symbols and grades from the male/female day-pillar table of a reference text (1995)), zodiac compatibility (three layers — Sun, Moon, Ascendant — plus planets chosen by purpose, and up to two zodiac compatibility paragraphs) and zodiac-animal compatibility (the Earthly Branch relation and grade of the two birth-year animals), plus an overall score (headerBreakdown) that combines five scores with purpose-specific weights. Since 2026-10-16 it also returns a relations table (relations) that collects, position by position, the combinations, clashes, punishments, harms and breaks between the two natal charts, and its score (p2Score). It is the same engine as the compatibility screen in the INTA app, and the same input always gives the same result.

The headline score in the INTA app (the big number) = headerBreakdown.average (62 in the response example below). saju.score.total (59 in the example) is HRUM's own score that averages only the day-pillar table and the eight characters, so it differs from the number on the app screen.

The values shown in the six-axis chart on the INTA app result screen are saju.iljuAxes (saju.axes is a different set, recalculated per purpose). For people whose birth time is known, send personXCountry + personXBirthTimePrecision: "exact" as in the recommended call so the Saju is calculated the same way as in the INTA app (with true solar time correction).

POST /api/v1/partners/v1/compat

Analyzes compatibility based on the Saju of two people.

Request parameters

The details, flow and MBTI options cost nothing extra (still ₩20 per call).

• Time correction: each person's Saju (day pillar · eight-character score · overall score · intimacy symbol table · zodiac animal · authority analysis · yearFlow · relationship narrative) is calculated once and shared by every item. If you don't send coordinates, personXCountry or precision exact, the input time is used as is (same as the Manseryeok API). If you need the same compatibility as the INTA app (Korean, time entered directly), send personXCountry: "KR" (+ personXBirthTimePrecision: "exact") for both people — see the recommended call below. People without a birth time are not corrected. The default (no correction unless sent) does not change.
• Changed 2026-10-11: when coordinates are sent, the Saju also gets true solar time correction (before, they were used only for zodiac compatibility). This change makes Saju and zodiac use the same time base within one response, so calls that were already sending coordinates may see different Saju scores and day pillars. Responses for new fields and for calls without coordinates are unchanged.
• Day pillars are code values: the values of saju.personA.ilju and saju.personB.ilju (e.g. 계미) are Korean stem-branch code values regardless of lang. For display names, convert them with the Manseryeok API glossary (glossary) or the Chinese-character form (癸未; for English and Thai 癸未 (Gye-mi)).

Recommended call (same result as the INTA app)

For people whose birth time is known, send the country of birth together with "exact". The true solar time correction then matches the INTA app, so even people born near a two-hour period boundary get the same day pillar and scores as in the app.

{
  "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
  "personACountry": "KR", "personABirthTimePrecision": "exact",
  "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
  "personBCountry": "KR", "personBBirthTimePrecision": "exact",
  "purpose": "yeonae_attraction", "details": true
}

Response example

Below is real engine output (A male 1990-09-04 14:30, B female 1992-02-20 10:15, dating, no coordinates). The always-included fields added on 2026-10-10 (saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame) are left out of this example — see the options example below. For these two people the values are the same even with the recommended call (KR + exact).

{
  "success": true,
  "data": {
    "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
    "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
    "tti": {
      "userTti": "말", "partnerTti": "원숭이",
      "relation": { "type": null, "detail": null, "relations": [] },
      "tier": "흉"
    },
    "saju": {
      "purpose": "yeonae_attraction",
      "hourKnown": { "a": true, "b": true },
      "personA": { "ilju": "임신" },
      "personB": { "ilju": "병인" },
      "score": { "total": 59, "grade": "맞춰 가면 좋아요",
                 "breakdown": { "ilju": 53, "authority": 65, "eightChar": 65 } },
      "axes": { "attraction": 25, "stability": 59, "growth": 58,
                "communication": 24, "passion": 74, "longevity": 65 },
      "pattern": { "name": "폭발형",
                   "description": "에너지가 크게 부딪히는 뜨거운 관계예요. 감정이 커질 때 잠시 쉬어 가는 규칙이 도움이 돼요." },
      "relation": { "summary": "천간충 + 인신충",
                    "stem": { "type": "천간충", "detail": "병임충" },
                    "branches": [ { "type": "지지충", "detail": "인신충" } ] },
      "elements": { "basis": "eight", "aLacks": [], "bProvidesToA": [], "bLacks": ["토"], "aProvidesToB": ["토"] },
      "tenGods": { "aView": "편재", "bView": "편관(칠살)" },
      "bestFor": ["단기 끌림"],
      "weakFor": ["결혼·동거"],
      "highlights": [ "상대의 시지에 나의 천을귀인 (사) 발현 — 상대가 나의 해결사" ],
      "iljuAxes": { "attraction": 45, "stability": 16, "growth": 88,
                    "communication": 60, "passion": 70, "longevity": 50 }
    },
    "categoryNarrative": {
      "category": "romantic", "purpose": "yeonae_attraction", "lang": "ko",
      "text": "상대 쪽의 즉각적인 열정과 나 쪽의 자유로운 흐름은 불과 물처럼 정면으로 맞부딪혀서, 처음 만났을 때의 팽팽한 긴장감이 곧 끌림이 되기 쉬워요. 짧고 뜨거운 설렘이 큰 관계라, 감정이 치솟는 날엔 하루쯤 식힐 틈을 두면 더 즐겁게 만날 수 있어요.",
      "styleVersion": "v2"
    },
    "costPoints": 20,
    "classic1995": {
      "symbol": "××", "grade": "대흉", "score": 50,
      "ttiRelation": { "type": null, "detail": null, "relations": [] },
      "conflictFrame": false
    },
    "relations": [
      { "positions": ["month", "month"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "stemChung", "tier": "clash",
        "ruleIds": ["R-SAJU-REL-008", "R-SAJU-COMPAT-110"], "chars": ["壬", "丙"] },
      { "positions": ["year", "year"], "kind": "napeumSaeng", "tier": "gather",
        "ruleIds": ["R-SAJU-BASE-037", "R-SAJU-COMPAT-111"], "chars": ["庚午", "壬申"] },
      { "positions": ["chart", "chart"], "kind": "banghap", "tier": "gather",
        "ruleIds": ["R-SAJU-REL-021", "R-SAJU-COMPAT-104"], "chars": ["巳", "午", "未"] }
    ],
    "p2Score": 57,
    "astroSynastry": {
      "self": {
        "sun": { "signEn": "Virgo", "element": "earth", "modality": "mutable" },
        "moon": { "signEn": "Pisces", "element": "water", "modality": "mutable", "uncertain": false },
        "ascendant": { "signEn": "Sagittarius", "element": "fire", "modality": "mutable", "uncertain": false, "countryBasis": true },
        "venus": { "signEn": "Leo", ... }, "mars": { "signEn": "Gemini", ... },
        "mercury": { ... }, "jupiter": { ... }, "saturn": { ... }
      },
      "partner": { "sun": { "signEn": "Pisces", ... }, "moon": { "signEn": "Virgo", ... }, ... },
      "layers": [
        { "key": "sun", "relation": "opposite", "selfSign": "Virgo", "partnerSign": "Pisces",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "moon", "relation": "opposite", "selfSign": "Pisces", "partnerSign": "Virgo",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "ascendant", "relation": "neutral", "selfSign": "Sagittarius", "partnerSign": "Taurus",
          "textKey": "compat.astro.relation.neutral",
          "text": "뚜렷한 결 없이 각자의 스타일을 존중하면 되는 조합이에요" }
      ],
      "purposeBodies": [
        { "body": "venus", "relation": "opposite", "selfSign": "Leo", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "body": "mars", "relation": "same_element", "selfSign": "Gemini", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.same_element",
          "text": "같은 원소 — 서로의 방식을 바로 알아볼 만큼 편안할 수 있어요" }
      ],
      "caveats": ["compat.astro.caveat.ascendantCountryBasis"],
      "caveatTexts": ["상승궁은 출생 도시가 없어 국가 대표 좌표로 추정했어요"],
      "score": 64
    },
    "astroReadings": [
      { "key": "Su_Mo_ss", "lang": "ko",
        "text": "한쪽의 태양과 다른 쪽의 달이 같은 별자리에 놓이면, 한 사람이 향하는 방향을 다른 사람의 마음이 낯설지 않게 알아보는 깊은 공명이 생기기 쉬워요. 닮은 만큼 같은 그림자도 함께 커질 수 있으니 서로의 빈틈을 웃으며 짚어 주면 좋아요." },
      { "key": "Ve_Ma_op", "lang": "ko",
        "text": "한쪽의 금성과 다른 쪽의 화성이 정반대 별자리에 놓이면, 서로에게 없는 매력을 알아보며 끌리는 보완의 흐름이 생기기 쉬워요. 원하는 속도와 표현 방식이 반대로 기울 수 있으니 서로의 선을 말로 정해 두면 그 끌림이 편안하게 이어져요." }
    ],
    "headerBreakdown": {
      "sixAxis": 55, "authority": 65, "full8": 65, "classic": 57, "natal": 64,
      "average": 62, "purpose": "yeonae_attraction",
      "weights": { "sixAxis": 0.2, "authority": 0.3, "full8": 0.2, "classic": 0.1, "natal": 0.2 }
    },
    "engineVersion": "compat-2",
    "lang": "ko"
  }
}

• saju (Saju compatibility) is the main part. In rare cases where the day pillar cannot be calculated it is null — then show only tti
• saju.score.total: 0–100. Average of the day-pillar table score and the eight-character analysis score (each in breakdown). grade is a plain-language grade — 아주 잘 맞아요 (very good match, 85+) · 잘 맞아요 (good match, 75+) · 무난해요 (fine, 65+) · 맞춰 가면 좋아요 (works with effort, 55+) · 서로 많이 달라요 (very different). This value is the same as before — the score that also includes the symbol table and zodiac is headerBreakdown.average
• saju.axes: six axes (0–100) — attraction · stability · growth · communication · passion · longevity; they change with purpose. saju.pattern: relationship type name and description (null if none)
• saju.iljuAxes (from 2026-10-27): the same values as the six-axis chart on the INTA app result screen — the six axes of the compatibility table for the two people's day-pillar pair as is (attraction · stability · growth · communication · passion · longevity, 0–100, independent of purpose). The average of the six axes is headerBreakdown.sixAxis. It has the same keys as saju.axes, but the calculation is different, so the numbers differ. null if the pair is not in the compatibility table
• saju.elements: calculated from the Five Elements distribution of each person's whole natal chart (six characters if the time is unknown — basis: "six"). bProvidesToA = elements A lacks that B has
• saju.tenGods: B's Ten God as seen from A (aView) and the reverse (bView). highlights: cross Sinsal sentences found in the eight characters (up to 5, empty array if none)
• relations (from 2026-10-16): list of relations between the two natal charts. It looks at Earthly Branch pairs in the same position (year · month · day · hour — the hour pillar only when both people have a birth time), stem combinations and stem clashes between the two Day Masters, the Nayin element of the year pillars, and three-harmony (samhap) and directional (banghap) combinations that only form when the two charts are combined. Each item has positions ([A side, B side] — year · month · day · hour; for samhap and banghap chart = the whole chart), kind (table below), tier, ruleIds (IDs of the supporting KB rules — check the original source in the KB API) and chars (the related characters, in Chinese characters). All keys are language-independent, so they stay the same if you change lang. Build display text from kind yourself. There are no good/bad verdict words. null if the natal chart cannot be built, empty array if there are no relations
• tier: gather coming together (the combination side) · clash friction · heavyClash heavy friction (a relation the classic texts rank as heavier; currently clashes) · listOnly listed only (a relation for which no direction could be found in the classic texts, so it is not scored)
• p2Score (from 2026-10-16): 0–100. round(71.6 + 5 × Σ) clipped to 0–100 — Σ = the sum over relations of gather +1 · clash −1 · heavyClash −2 · listOnly 0. One unit = 5 points, and 71.6 is the neutral point when there are no relations (the real-member average of the previous classic-text axis score, as of 2026-10-16). The scale is the same whether or not there is an hour pillar. The classic texts state only the direction and ranking of relations, not their size — this number is a scale assumption for display, not a score from the classic texts (KB R-SAJU-COMPAT-113). null if relations is null
• classic1995 (to be discontinued): still returned exactly as before. Planned schedule: announcement on 2026-11-16 → kept until 2026-12-31 → null from 2027-01-01. Dates may change by service announcement. For new integrations use relations and p2Score. Symbols from the male/female day-pillar intimacy table of a reference text (1995) (● 대길 (great fortune) 100 · ◎ 중길 (good fortune) 90 · ○ 길 (fortune) 80 · △ 무해무덕 (neutral) 70 · × 흉 (misfortune) 60 · ×× 대흉 (great misfortune) 50). The table is directional, male day pillar × female day pillar, so for same-gender pairs or when gender is not sent, both directions are read (A as male · B as male); score is the average of the two (e.g. 95), and symbol and grade are the grade of that average rounded down to the nearest 10 (e.g. 95 → ◎ 중길). If both directions are the same, that symbol as is. conflictFrame: true when the symbol is favorable but the zodiac-animal relation is unfavorable, or the other way round. The whole object is null if the day pillar cannot be found
• astroSynastry: zodiac compatibility. layers = three-layer comparison of Sun · Moon · Ascendant; purposeBodies = priority planets by purpose (dating: Venus · Mars, marriage: + Saturn, friendship: Mercury · Jupiter …). relation = same_sign · opposite · same_element · element_support · same_modality · element_friction · neutral; text is its meaning (lang). score 0–100. caveats/caveatTexts: notes when the Ascendant or Moon sign is estimated. If the time is unknown, the Ascendant layer is left out
• astroReadings: prewritten reading paragraphs for up to two of the most prominent contacts between the two people's charts (Sun–Moon, Venus–Mars, etc.). Empty array if none. The lang of each paragraph is the language the text is actually in (ko if there is no text in the requested language)
• headerBreakdown: overall score average (0–100) that combines five scores — six-axis average · authority (authority) · eight characters (full8) · classic-text share (classic — p2Score since 2026-10-16, classic1995.score before) · zodiac (natal) — with per-purpose weights (weights). Missing scores have their weight redistributed among the rest. Same value as the headline score (big number) on the INTA app compatibility screen (62 in the example above). Since 2026-10-16, the weight of the classic-text share (classic) for the marriage purpose (marriage_stability) went from 0.25 to 0.05, and the freed 0.20 was split among the other four axes in their previous ratio (sixAxis 0.15 → 0.19 · authority 0.25 → 0.3167 · full8 0.25 → 0.3167 · natal 0.10 → 0.1267). Weights for other purposes are unchanged. null if the day-pillar compatibility table entry cannot be found
• The birth year must be 1900–2100 — otherwise 400 INVALID_BIRTH_YEAR (not charged). If a user types a two-digit year into a date field it goes in as e.g. 0090, so block that on your screen too. If no result is found in the compatibility table, 400 COMPAT_UNAVAILABLE (not charged)
• tti.tier: grade string from the zodiac-animal compatibility of a reference text (1995) (e.g. 대길 · 길 · 중길 · 보통 · 주의 · 흉 — great fortune to misfortune). tti.relation.type = the relation between the two animals' Earthly Branches — one of 충 (clash) · 원진 (wonjin, resentment) · 형 (punishment) · 해 (harm) · 육합 (six harmony) · 반합 (half harmony) · 파 (break) (if several overlap, the first in this order), null if none. detail only for half harmony (e.g. 수국(水局)). tti.relation.relations = all overlapping relations (same order, e.g. Ox · Goat ["충","형"], empty array if none)
• tti contains only the animals, relation and grade. The zodiac-animal compatibility sentences of the reference text are not included (since 2026-10-11).
• categoryNarrative: 2–3 sentences on how the two people are in this relationship (purpose). The sentences are prewritten for every day-pillar combination (1,830 pairs) and each of the 6 relationship kinds, so the same input always gives the same text. In the text, 나 = A and 상대 = B (English You/Your partner, Japanese あなた/相手, Thai คุณ/คู่ของคุณ). Four languages via lang; null if no text is found (charged the same)
• Always included (from 2026-10-10): saju.relationRatings = { key, stars } for five relationship kinds (key e.g. 연애 (dating), 결혼·동거 (marriage / living together), 친구 (friends), 사업 파트너 (business partner), 장기 관계 (long-term) / 1–5 stars) · saju.meetingKeywords = three meeting keywords · saju.authority = authority compatibility verdict (finalScore · grade · gradeTier · pattern · summary · levels (L1–L4) · factors · flags · climateBalance) · tti.conflictFrame = same value as classic1995.conflictFrame
• yearFlow.years[].tier: great · good · neutral · caution. dayFlow.days[].tier: golden · good · neutral · dim · hard (dayFlow.golden/hard are the lists of those dates)

Relation kinds (relations[].kind)

The same kind always has the same tier (the only exception is the two break pairs). New kind values may be added, so skip values you don't know.

Options example (details · flow · MBTI)

An excerpt of real engine output. Request:

{
  "personABirthDate": "1990-05-15", "personABirthTime": "12:00", "personAGender": "male",
  "personBBirthDate": "1992-08-20", "personBBirthTime": "09:00", "personBGender": "female",
  "details": true, "flow": true, "date": "2026-10-10",
  "personAMbti": "ENFP", "personBMbti": "ISTJ"
}

{
  "success": true,
  "data": {
    "tti": { "userTti": "말", "partnerTti": "원숭이", ..., "tier": "흉", "conflictFrame": false },
    "saju": {
      "personA": { "ilju": "경진" }, "personB": { "ilju": "무진" },
      "score": { "total": 56, "grade": "맞춰 가면 좋아요", ... },
      ...,
      "relationRatings": [
        { "key": "연애", "stars": 3 }, { "key": "결혼·동거", "stars": 3 }, { "key": "친구", "stars": 4 },
        { "key": "사업 파트너", "stars": 3 }, { "key": "장기 관계", "stars": 3 }
      ],
      "meetingKeywords": ["괴강", "우직", "일반적 관계"],
      "authority": {
        "finalScore": 51, "grade": "주의", "gradeTier": "caution",
        "pattern": "자형 (자기 갈등 외부화)",
        "summary": "주의 · 자형 (자기 갈등 외부화) · 익숙한 결의 만남. 안락함 위에 자극을 어떻게 만들지가 핵심.",
        "levels": { "L1": { "raw": 0, "norm": 0 }, "L2": { "raw": 5, "norm": 14.3, "type": "동계절 (봄)" },
                    "L3": { "raw": 17, "norm": 56.7 }, "L4": { "raw": -17, "norm": -42.5 } },
        "factors": { "l1": [], "l2Tone": "...", "l3": [ ... ], "l4": ["자형(진진) — 자기 파괴 패턴", ...] },
        "flags": { "cheonHapJiHap": false, "dualChung": false },
        "climateBalance": "동계절 (봄)"
      },
      "conflict": {
        "pattern": "경은 무를 편인으로 인식. 일방향적 관계 성격.",
        "tip": "'괴강'과 '우직'은 서로 다른 결이에요. 같은 사건도 다르게 해석한다는 걸 인정하고, 서로의 관점을 한 번씩 빌려보세요."
      },
      "relationScores": { "stem": { "type": "편인", "category": "neutral", "score": 55 },
                          "branches": [ { "type": "자형", "score": -40 } ] },
      "full8": { "personA": { ... }, "personB": { ... }, "iljuEvaluation": { ... }, ... }
    },
    ...,
    "dictionary": { "a": { "id": "ilju_경진", "name_kr": "경진", "name_hanja": "庚辰", ... }, "b": { ... } },
    "yearFlow": {
      "baseYear": 2026,
      "years": [
        { "year": 2024, "score": 77, "tier": "great", "a": { ... }, "b": { ... },
          "summary": "두 분 모두 흐름이 좋아 같이 시작하기 좋은 해." },
        ...
      ]
    },
    "dayFlow": {
      "baseDate": "2026-10-10",
      "days": [
        { "date": "2026-10-03", "a": -89, "b": -40, "combined": -60, "tier": "hard", "isBaseDate": false },
        ...,
        { "date": "2026-10-10", "a": -9, "b": 27, "combined": 9, "tier": "neutral", "isBaseDate": true },
        ...
      ],
      "golden": [],
      "hard": [ { "date": "2026-10-03", "combined": -60 }, ... ],
      "summary": "3번 같이 가라앉는 날이 있어. 그날은 큰 결정·약속 미루자."
    },
    "mbti": { "id": "mbti_ENFP_ISTJ", "mbti_a": "ENFP", "mbti_b": "ISTJ",
              "socionics_relation": "Duality(이중관계)", "scores": { ..., "total": 64 }, ... }
  }
}

Notes

• Basic data: both people's birth dates are required. Time and gender are optional. The intimacy symbol table is returned even without gender or for the same gender (both directions combined); the Ascendant in zodiac compatibility needs a birth time.
• What you get: zodiac compatibility uses the tropical zodiac. The relationship narrative comes in categoryNarrative and the zodiac paragraphs in astroReadings; if you need a longer custom reading, put the result into a /reading question.
• Changed 2026-10-16 (engineVersion compat-2): relations · p2Score · engineVersion are new, and headerBreakdown.classic became p2Score, so headerBreakdown.average may differ from before (same value as the INTA app compatibility screen). Values of other existing fields are unchanged.
• Compatibility: the fields added in 2026-10 (classic1995 · astroSynastry · astroReadings · headerBreakdown · lang, and on 2026-10-10 saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame) are always added whether or not you send lang. Values of existing fields are unchanged. However, since 2026-10-11 the fields that reproduced sentences from the reference text (1995) — the one-line zodiac-animal compatibility reading and the love and health fortune in the day-pillar dictionary — have been removed from the response.
• Added 2026-10-27: saju.iljuAxes (always, at the end of the saju block) is new. The values and order of existing fields are unchanged, and engineVersion is still compat-2.
• Changed 2026-10-31: Korean particles in compatibility sentences now agree with the final consonant (e.g. 「임와」 → 「임과」, 「병는」 → 「병은」). Keys, order, numbers and text in other languages are unchanged.
• Cost: ₩20 is deducted per call (including the added fields and the details, flow and MBTI options; no extra charge).

Error codes

Besides the common errors (401 · 400 body validation · 402 · 429 · 503, etc.), this API returns:

For request examples see the options example above and the run example.

Personality Type API

Provides an MBTI-based personality test. Supports a free lite version (24 questions) and a premium version (93 questions).

GET /api/v1/partners/v1/personality-type/questions

Gets the personality test questions. Free.

curl "https://api.hrum.ai/api/v1/partners/v1/personality-type/questions?tier=free" \
  -H "X-Partner-Api-Key: your-api-key"

Request parameters

Response example

{
  "success": true,
  "data": {
    "tier": "free",
    "count": 24,
    "questions": [
      {
        "id": "q_001",
        "text": "갑자기 생긴 모임에도 일단 가본다",
        "choices": [
          { "value": 1, "label": "전혀 그렇지 않다" },
          { "value": 2, "label": "그렇지 않다" },
          { "value": 3, "label": "보통이다" },
          { "value": 4, "label": "그렇다" },
          { "value": 5, "label": "매우 그렇다" }
        ]
      }
    ]
  }
}

POST /api/v1/partners/v1/personality-type

Submits personality test answers to analyze the personality type.

curl -X POST https://api.hrum.ai/api/v1/partners/v1/personality-type \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "free",
    "answers": [
      { "questionId": "q_001", "answer": 4 },
      { "questionId": "q_002", "answer": 2 }
    ]
  }'

Request parameters

Response example

{
  "success": true,
  "data": {
    "personalityType": "ENTJ",
    "typeLabel": "지휘관",
    "scores": {
      "extraversion": 72,
      "sensing": 45,
      "thinking": 68,
      "judging": 80
    },
    "tier": "premium",
    "costPoints": 10
  }
}

Pricing

• Free version (free): 24 questions, ₩0 (free)
• Premium (premium): 93 questions, ₩10 per call
• An unknown questionId or an answer outside 1–5 returns 400 and is not charged.
• With premium, if any axis has no answers at all, you get 400 personality_axis_unanswered and are not charged. The response's axes lists the empty axes (E_I · S_N · T_F · J_P).

Error codes

Besides the common errors (401 · 400 body validation · 402 · 429 · 503, etc.), this API returns:

An answer outside 1–5 returns the common 400. None of these are charged.

Interpretation KB API

This API is open only to accounts that have applied for it. Other accounts get 404 kb_saju_explain_not_enabled on all three paths (not charged). To use it, contact support.

Explains the relations (combinations, clashes, etc.) and structures (Ten Gods, hidden stems, etc.) that hold in a Saju natal chart as rule cards and explanatory sentences. It does not use an LLM, so the same input always gives the same result.

POST /api/v1/partners/v1/kb/saju/explain

Request parameters

Request example

curl -X POST https://api.hrum.ai/api/v1/partners/v1/kb/saju/explain \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "year": 1990, "month": 5, "day": 17, "hour": 14, "minute": 30,
      "timezone": "Asia/Seoul", "gender": "female"
    },
    "sections": ["relations"]
  }'

Response example (excerpt)

{
  "success": true,
  "data": {
    "kbVersion": "2026.10.09-3",
    "kbHash": "sha256:24b9a2d9...",
    "channel": "stable",
    "chart": {
      "pillars": {
        "year":  { "stem": "庚", "branch": "午" },
        "month": { "stem": "辛", "branch": "巳" },
        "day":   { "stem": "壬", "branch": "午" },
        "hour":  { "stem": "丁", "branch": "未" }
      },
      "timeUnknown": false
    },
    "sections": [
      {
        "id": "relations",
        "title": "...",
        "steps": [
          {
            "fact": { "type": "stem_pair", "a": "壬", "b": "丁", "posA": "day", "posB": "hour", "relation": "hap" },
            "factText": "일간 壬과 시간 丁은 천간합(天干合) 관계다.",
            "componentId": "saju:stem_pair:丁壬:hap",
            "rules": [
              { "id": "R-SAJU-REL-004", "kind": "definition", "status": "verified", "sourceCount": 2,
                "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다." }
            ],
            "interp": {
              "meaning": { "text": "丁(정)과 壬(임)은 천간합으로 묶이는 짝이고, ...", "reviewed": false },
              "why": { ... },
              "pitfall": { ... }
            }
          }
        ],
        "absent": [
          { "type": "stem_pair", "a": "庚", "b": "辛", "posA": "year", "posB": "month",
            "note": "庚과 辛은 천간합·천간충 어느 것도 아니다." }
        ]
      }
    ],
    "unregistered": [],
    "pendingReview": []
  }
}

• interp holds the explanation fields (meaning meaning · why reasoning · pitfall caution). Each field is {text, reviewed, reviewedBy?, notes?}, and with stable only reviewed fields are returned.
• unregistered: items that hold but have no explanation yet. pendingReview: items that have an explanation but are hidden in stable because they are not reviewed yet.
• Look up the original source of a rule card with GET /kb/rules/{id} below.

GET /api/v1/partners/v1/kb/rules/{id}

Returns one rule card and its original sources. Free.

curl https://api.hrum.ai/api/v1/partners/v1/kb/rules/R-SAJU-REL-004 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "id": "R-SAJU-REL-004",
    "kind": "definition",
    "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다.",
    "status": "verified",
    "schools": [],
    "variantOf": null,
    "sources": [
      { "sourceId": "SRC-SMTH", "location": "『三命通會』 卷二 論十干化氣",
        "quote": "故丁與壬合　丁壬化木", "match": "EXACT", ... }
    ],
    "engineRef": "..."
  }
}

GET /api/v1/partners/v1/kb/release?domain=saju

Returns the currently published edition of the Interpretation KB. Free. If domain is omitted it is saju (e.g. saju · ziwei · astro · dream · tarot).

curl "https://api.hrum.ai/api/v1/partners/v1/kb/release?domain=saju" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "version": "2026.10.09-3",
    "hash": "sha256:24b9a2d9...",
    "publishedAt": "2026-10-09T00:00:00.000Z",
    "channel": "stable",
    "counts": { "rules": 412, "interps": 1236 }
  }
}

The numbers above are examples. If you store results, fetch them again when hash changes.

Error codes

Besides the common errors: