Get Started guide for developers

This is the order to follow when you integrate the HRUM Saju (Four Pillars of Destiny) API for the first time. Sign-up, your first call, billing and error handling are all on this page. The full parameters for each endpoint are in the API docs.

Want to see results before you sign up? Try the Playground without a key, free up to 5 times a month.

Let AI build your app — free ebooks (Korean)

Choose an ebook (Korean)All-in-one fortune app (Korean)Character chat app (Korean)Members-only web app (Korean)

1. Sign up for the console

  1. On the console sign-in screen, choose the Sign up tab and enter your email and a password.
  2. Open the verification email in your inbox, click the verify button, then sign in again.
  3. New accounts get ₩1,000 in free credits (the grant may be held if the sign-up trips our anti-abuse checks).

2. Get an API key

  1. On the console's API keys screen, enter a name for the key (e.g. "Production server") and click Issue.
  2. A new key is shown only once, right after it is issued. Copy it right away and store it somewhere safe, such as an environment variable on your server. If you lose it, issue a new one.
  3. Use the key only on your server. If you put it in browser or app code, anyone can pull it out and use it.

Set per-second and daily request limits under Request limits on the same screen. That protects your balance if a key leaks or your code gets stuck in a loop.

3. First call — Manseryeok

Every request goes to a path under https://api.hrum.ai/api/v1/partners/v1/, with the key in the X-Partner-Api-Key header. Below is a call to Manseryeok (the Korean Four Pillars calendar), which computes the natal chart from a date and time of birth.

curl

export HRUM_API_KEY="your-api-key"

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

Python (requests)

import os
import requests

res = requests.post(
    "https://api.hrum.ai/api/v1/partners/v1/manseryeok",
    headers={"X-Partner-Api-Key": os.environ["HRUM_API_KEY"]},
    json={"year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
          "timezone": "Asia/Seoul", "gender": "male"},
    timeout=30,
)
body = res.json()
if not body.get("success"):
    raise RuntimeError(f'{body.get("statusCode")} {body.get("code")}')
print(body["data"]["wonkuk"]["day"])

The default User-Agent of Python's standard library urllib is blocked by a security rule and gets a 403. Use requests, or if you use urllib, set a User-Agent: <app-name>/<version> header yourself.

JavaScript (Node 18 or later, on the server)

const res = await fetch('https://api.hrum.ai/api/v1/partners/v1/manseryeok', {
  method: 'POST',
  headers: {
    'X-Partner-Api-Key': process.env.HRUM_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ year: 1990, month: 5, day: 15, hour: 12, minute: 0, timezone: 'Asia/Seoul', gender: 'male' }),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.statusCode} ${body.code ?? ''}`);
console.log(body.data.wonkuk.day);

4. Read the response

A successful call returns {"success": true, "data": { … }}. For Manseryeok, data holds the four pillars (year, month, day, hour) of the natal chart (wonkuk), the Five Elements balance (ohaengBalance), Yongsin (favorable element, yongshin), Gyeokguk (chart structure), 10-year luck cycles (Daeun), annual luck (Seun) and more. See the Manseryeok API docs for the full field list.

Calculation APIs like Manseryeok always return the same result for the same input. Store the result in your database once and reuse it — that costs nothing.

5. Billing and credits

Unit prices for each product are on the pricing page. Main calculation API prices (from the current pricing):

6. Error handling

Error bodies look like {"success": false, "statusCode": 400, "code": "…", "message": "…", "timestamp": "…"}. Branch on statusCode and code; don't rely on the wording of message.

CodeMeaningWhat to do
400Invalid request parametersFix the request. Don't retry the same request.
401API key missing or invalidCheck the header name (X-Partner-Api-Key) and the key value.
402Not enough credits. code is INSUFFICIENT_BALANCE, or absent on APIs without a balance pre-check (such as Manseryeok)Top up, then call again.
403Blocked by a security rule (the body is HTML, not JSON; error 1010) — an HTTP client whose default User-Agent is blocked (Python urllib and the like). Not an API key problemSet a User-Agent: <app-name>/<version> header. Changing the key won't help.
404A feature not enabled for your account (*_not_enabled) or a resource that doesn't existNot billed. Check the path and whether the feature is enabled.
422Input that can't be processed (e.g. PROMPT_TOO_LONG)Shorten or fix the input.
429Rate limit exceededWait as long as the Retry-After header says, or briefly (up to 1 minute) if it's missing, then retry.
500 · 503 · 504Server error · temporarily unavailable · upstream timeoutRetry a few times with growing gaps (e.g. 1s → 2s → 4s).

To protect the service, every API key always has a cap of 300 requests per minute. See the Error codes and Rate Limit docs for details. Check the status page for outages.

Next steps

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