Saju API Quickstart — from zero to your first Four Pillars in 5 minutes.

1Get a free API key

Keys are self-serve. Send your email to the key endpoint and you get a free-tier key instantly (100 requests/day, no card). The key is shown once — store it safely.

curl -X POST https://saju-api.pages.dev/api/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@yourcompany.io" }'

const res = await fetch("https://saju-api.pages.dev/api/v1/keys/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "dev@yourcompany.io" }),
});
const { api_key } = await res.json();
console.log(api_key); // sajuapi_free_...  store this, it is shown once

import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/keys/create",
    json={"email": "dev@yourcompany.io"},
)
api_key = res.json()["api_key"]
print(api_key)  # sajuapi_free_...  store this, it is shown once

2Calculate the Four Pillars

Post a solar birthdate to /api/v1/calculate. Use hour: -1 when the birth time is unknown. lang is optional (defaults to ko).

curl -X POST https://saju-api.pages.dev/api/v1/calculate \
  -H "X-API-Key: sajuapi_free_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year":  1990,
    "month": 5,
    "day":   15,
    "hour":  14,
    "gender":"M",
    "lang":  "en"
  }'

const res = await fetch("https://saju-api.pages.dev/api/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": "sajuapi_free_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    year: 1990, month: 5, day: 15, hour: 14, gender: "M", lang: "en",
  }),
});
const data = await res.json();
console.log(data.day_master); // { stem, element, polarity }
console.log(data.elements);   // { wood, fire, earth, metal, water }

import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/calculate",
    headers={"X-API-Key": "sajuapi_free_YOUR_KEY"},
    json={"year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en"},
)
data = res.json()
print(data["day_master"])  # {'stem': ..., 'element': 'metal', 'polarity': 'yang'}
print(data["elements"])    # {'wood': 0, 'fire': 2, 'earth': 2, 'metal': 3, 'water': 1}

Example response

{
  "input":   { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en" },
  "pillars": {
    "year":  { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "month": { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "day":   { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "hour":  { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." }
  },
  "elements":   { "wood": 0, "fire": 2, "earth": 2, "metal": 3, "water": 1 },
  "day_master": { "stem": "...", "element": "metal", "polarity": "yang" },
  "zodiac":     "horse",
  "tier":       "free",
  "remaining":  99
}

3Explore the other endpoints

Four endpoints cover most use cases. All birthdate endpoints share the same request body (year, month, day, hour, gender, lang).

Compatibility example

curl -X POST https://saju-api.pages.dev/api/v1/compatibility \
  -H "X-API-Key: sajuapi_free_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_a": { "year": 1990, "month": 5,  "day": 15, "hour": 14, "gender": "M" },
    "person_b": { "year": 1992, "month": 11, "day": 3,  "hour": 9,  "gender": "F" },
    "lang": "en"
  }'

Daily fortune example

curl "https://saju-api.pages.dev/api/v1/daily?day_master=wood_yang&date=2026-06-14&lang=en" \
  -H "X-API-Key: sajuapi_free_YOUR_KEY"

The daily response sets Cache-Control so a CDN or your own cache can serve it cheaply per (day-master, date) — ideal for push notifications and widgets.

4Languages & output

Pass lang on any request to localize human-readable summaries. Stems and branches always come back with both Hanja and romanized forms, so you can render in any script.

• Supported: ko, en, ja, zh, es, pt-br, vi, id, hi, th.
• Every pillar returns stem, branch, stem_hanja, and branch_hanja.
• Element distribution uses English keys (wood / fire / earth / metal / water) for easy charting.

5Errors & limits

Errors return a JSON body with an error code and an optional reason. Handle these in your client:

Check your remaining quota any time with GET /api/v1/usage (send your key in the X-API-Key header). Every successful API response also includes a remaining field.

Reference & tools

Full request/response schemas and a ready-to-import collection:

• OpenAPI 3.1 specification — import into Swagger UI, Stoplight, or your codegen tool.
• Postman collection (JSON) — import into Postman to try every endpoint.