← Saju Pillars
API
Tokens

Drive Saju Pillars from your own code

Both metered steps - the reading and the compatibility read - are available over HTTP. A natural use is a horoscope or K-culture page that already knows a visitor's chart: your code sends the computed characters and shows the cited reading.

The split first: the page does the calendar; the model writes the reading; the page checks it. Pillars, ten gods, elements, interactions and this year's pillar come from sajukit.js, which runs in node as well as in the browser. Its reconcile function then checks every cited id, the day master, the dominant element, whether this year's clashes were mentioned and whether the wording stays clear of fatalism and directives. The model never receives a birth date, time or place.

Base URL and the envelope

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response uses one envelope:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "...", "status": 402, "details": { ... } } }

The token is minted for this app (the guest call takes {"slug":"saju-pillars"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object, sent bare: never wrap it as {"input": {…}}.

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or a required field is missing.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: both tasks are metered and need a personal token.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field comes first

Every run sends task, which routes the one system prompt to one of two contracts:

taskWhat it returnsVerdict field
readingOne chart, one theme: focus, day_master, dominant, a title, a summary, an accuracy note; 2–4 core and 2–4 focus_read lines; a year_ahead line; a balance {element, text, cite}; 2–4 tips; 1–3 caveats.outlook: bright, mixed, careful
matchTwo charts: day_masters [A, B], a title, a summary, an accuracy note; 2–5 dynamics, 1–4 strengths, 0–4 frictions (never empty when a cross fact is a clash); 2–4 tips; 1–3 caveats.rapport: natural, workable, stretch

A line is always {text, cite}: one or two plain sentences, and the chart ids they rest on - Y1 Y2 M1 M2 D1 D2 H1 H2 (stem and branch of each pillar), DM, ST, E-wood…E-water, interactions X1…, this year's A1 A2 AX1…; in a match, person ids carry A: or B: and cross facts are C1….

The declared input schema carries scalars only, so object-valued fields travel JSON-encoded as strings (SajuKit.toWire does this). task and chart are required.

Input fields

FieldTypeNotes
taskstringreading or match.
chartstring (JSON)Person A: {label, pillars{hour?,day,month,year}, hour_known, day_master, elements, strength, interactions[], flags[]} from SajuKit.brief. No birth date, time or place.
focusstringreading only: overall, love, money, work, health, year.
annualstring (JSON)reading only: {year, pillar, animal, stem, branch, hits[]} - the year's pillar and how it meets the chart.
partnerstring (JSON)match only: person B, same shape as chart.
crossstring (JSON)match only: [{id, kind, text}] from SajuKit.cross - day masters, stem and branch combinations and clashes, elements one fills for the other.
readingstring (JSON)match only, optional: {day_master, summary, balance} from an earlier reading.
questionstringOptional; over 1,200 characters keeps the start and the end around a marker.
retry_notestringOnly on a reformat retry.

The reply

The job's output.output is a string holding one JSON object. Parse it with SajuKit.parseReply, then normalize, then check it with reconcile(reply, {a, b, focus}): it flags a cited id that is not in the chart, an uncited line, a wrong day master, a dominant element the count does not support, the hour pillar cited when the birth time is unknown, a missing caveat about an unknown time, a clash with this year left unmentioned, a match with clashes but no frictions, and fatalistic or directive wording.

Worked examples

Replies produced against the app's prompt for three made-up people (long lists shortened; the full replies ship in example-result.js). The page replays each of them free from its sample buttons. Inputs are shown with three of the four pillars folded.

task: reading - Hana, a work read (sample person) (bright)

Input:

{
 "task": "reading",
 "chart": "{\"label\":\"Hana\",\"pillars\":{\"day\":{\"pillar\":\"辛酉\",\"roman\":\"Sin-yu\",\"stem\":{\"id\":\"D1\",\"ch\":\"辛\",\"el\":\"yin metal\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"酉\",\"el\":\"metal\",\"animal\":\"Rooster\",\"hidden_main\":\"辛\",\"god\":\"Companion (비견)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"辛\",\"el\":\"yin metal\"},\"elements\":{\"counts\":{\"wood\":2,\"fire\":1,\"earth\":1,\"metal\":3,\"water\":1},\"total\":8,\"dominant\":[\"metal\"],\"missing\":[],\"weak\":[\"fire\",\"earth\",\"water\"],\"yinyang\":{\"yang\":0,\"yin\":8}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.5,\"balance_el\":\"fire\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"trine\",\"text\":\"day branch 酉 and hour branch 巳: three-harmony (metal) pair\"},{\"id\":\"X2\",\"kind\":\"trine\",\"text\":\"month branch 酉 and hour branch 巳: three-harmony (metal) pair\"},\"...\"],\"flags\":[]}",
 "focus": "work",
 "annual": "{\"year\":2026,\"pillar\":\"丙午\",\"roman\":\"Byeong-o\",\"animal\":\"Horse\",\"stem\":{\"id\":\"A1\",\"ch\":\"丙\",\"el\":\"fire\",\"god\":\"Direct Officer\"},\"branch\":{\"id\":\"A2\",\"ch\":\"午\",\"el\":\"fire\",\"god\":\"Seven Killings\"},\"hits\":[{\"id\":\"AX1\",\"kind\":\"combine\",\"text\":\"the year's 丙 and your day stem 辛: stem combination (water)\"}]}",
 "question": "I am thinking about leading a team for the first time. What does my chart say about that?"
}

Reply:

{
 "task": "reading",
 "focus": "work",
 "day_master": "辛",
 "dominant": "metal",
 "outlook": "bright",
 "title": "A Balanced 辛 Metal Chart Meets a Supportive Officer Year",
 "summary": "Your day master 辛 (yin metal) sits in a metal-heavy chart whose four branches lock into one full three-harmony alliance, with Direct Officer energy already present in your hour pillar. 2026 brings more of that same officer theme, and its one hit on your chart is a combination rather than a clash, pointing to a generally supportive season for taking on more responsibility.",
 "accuracy": "Your hour pillar is known and this chart carries no flags, so this reading uses the complete eight-character chart with nothing approximated.",
 "core": [
  {
   "text": "Your day master is 辛 (yin metal) - the metal of a finished ornament or blade rather than raw ore - so it tends to show up as precision, polish and a quiet kind of strength rather than open force.",
   "cite": [
    "DM"
   ]
  },
  {
   "text": "Metal is this chart's dominant element at 3 of 8 characters, with wood at 2 and fire, earth and water each at just 1. Even so, your strength lean comes out 'balanced' (ratio 0.5), meaning your day master has enough backing from peers and resources to hold its own.",
   "cite": [
    "E-metal",
    "E-wood",
    "E-fire",
    "E-earth",
    "E-water",
    "ST"
   ]
  },
  "..."
 ],
 "focus_read": [
  {
   "text": "Your hour branch 巳 carries Direct Officer (정관 - the ten god for structure, title and defined roles), so some pull toward formal responsibility is already part of this chart, not something you'd be manufacturing by leading a team.",
   "cite": [
    "H2"
   ]
  },
  {
   "text": "At the same time, your day branch 酉 and month branch 酉 are both Companion (비견 - peers who share your element), folded into that same metal three-harmony. This reads as a chart built more on alliances of equals than on ready-made hierarchy, so a first-time lead role may land better as earning trust among peers than as authority assumed from a title.",
   "cite": [
    "D2",
    "M2",
    "X8"
   ]
  },
  "..."
 ],
 "year_ahead": {
  "text": "2026's pillar is 丙午 (Byeong-o): Direct Officer on the stem and Seven Killings (칠살 - a sharper, more pressured cousin of the Officer) on the branch, leaning further into the structure-and-responsibility theme already in your hour branch. The year's one hit is 丙 forming a stem combination (two stems that blend into a third element, here water) with your own day stem 辛, rather than a clash - a theme to watch is that combinations can also pull your own priorities toward what a new role demands, so it's worth checking in with yourself as the year goes on.",
  "cite": [
   "A1",
   "A2",
   "AX1"
  ]
 },
 "balance": {
  "element": "fire",
  "text": "Fire is what this chart leans on for steadiness, and with only 1 of 8 characters in fire it's a thin, quiet thread - though 2026 itself is a fire-heavy pillar, which helps. Everyday ways to bring more in: reds and oranges around you, time outdoors in daylight, warmer food, and activities that move your energy outward rather than keeping it internal.",
  "cite": [
   "ST",
   "E-fire",
   "A1",
   "A2"
  ]
 },
 "tips": [
  "Before stepping into the lead, have direct one-on-one conversations with the peers you'd be leading - your chart's metal alliance suggests trust gets built sideways, not assumed from a title.",
  "Add small, regular doses of fire to your routine - morning light, a warm meal, time outdoors - since it's the chart's thin, steadying element.",
  "..."
 ],
 "caveats": [
  "Saju is a cultural tradition for reflection and conversation, not a fixed prediction - treat these as 'tends to' and 'may' themes to consider, not certainties about how a first-time team-lead role plays out.",
  "This reading covers the work focus only, grounded in your chart and 2026's pillar - it isn't a full forecast of the year or a verdict on whether to take the role."
 ]
}

task: match - Hana, a work read (sample person) (workable)

Input:

{
 "task": "match",
 "chart": "{\"label\":\"Hana\",\"pillars\":{\"day\":{\"pillar\":\"辛酉\",\"roman\":\"Sin-yu\",\"stem\":{\"id\":\"D1\",\"ch\":\"辛\",\"el\":\"yin metal\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"酉\",\"el\":\"metal\",\"animal\":\"Rooster\",\"hidden_main\":\"辛\",\"god\":\"Companion (비견)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"辛\",\"el\":\"yin metal\"},\"elements\":{\"counts\":{\"wood\":2,\"fire\":1,\"earth\":1,\"metal\":3,\"water\":1},\"total\":8,\"dominant\":[\"metal\"],\"missing\":[],\"weak\":[\"fire\",\"earth\",\"water\"],\"yinyang\":{\"yang\":0,\"yin\":8}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.5,\"balance_el\":\"fire\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"trine\",\"text\":\"day branch 酉 and hour branch 巳: three-harmony (metal) pair\"},{\"id\":\"X2\",\"kind\":\"trine\",\"text\":\"month branch 酉 and hour branch 巳: three-harmony (metal) pair\"},\"...\"],\"flags\":[]}",
 "partner": "{\"label\":\"Dae\",\"pillars\":{\"day\":{\"pillar\":\"乙巳\",\"roman\":\"Eul-sa\",\"stem\":{\"id\":\"D1\",\"ch\":\"乙\",\"el\":\"yin wood\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"巳\",\"el\":\"fire\",\"animal\":\"Snake\",\"hidden_main\":\"丙\",\"god\":\"Hurting Officer (상관)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"乙\",\"el\":\"yin wood\"},\"elements\":{\"counts\":{\"wood\":2,\"fire\":1,\"earth\":2,\"metal\":1,\"water\":2},\"total\":8,\"dominant\":[\"wood\",\"earth\",\"water\"],\"missing\":[],\"weak\":[\"fire\",\"metal\"],\"yinyang\":{\"yang\":2,\"yin\":6}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.38,\"balance_el\":\"fire\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"trine\",\"text\":\"day branch 巳 and hour branch 酉: three-harmony (metal) pair\"},{\"id\":\"X2\",\"kind\":\"trine\",\"text\":\"month branch 丑 and hour branch 酉: three-harmony (metal) pair\"},\"...\"],\"flags\":[]}",
 "cross": "[{\"id\":\"C1\",\"kind\":\"dm\",\"text\":\"Day masters: A 辛 (yin metal) and B 乙 (yin wood): A checks B.\"},{\"id\":\"C2\",\"kind\":\"dm-clash\",\"text\":\"Day stems 辛 and 乙 form a stem clash.\"},{\"id\":\"C3\",\"kind\":\"day-trine\",\"text\":\"Day branches (the partner palace) 酉 and 巳: three-harmony (metal) pair.\"}]",
 "question": "I am thinking about leading a team for the first time. What does my chart say about that?"
}

Reply:

{
 "task": "match",
 "day_masters": [
  "辛",
  "乙"
 ],
 "rapport": "workable",
 "title": "Metal Day Master Meets Wood: A Workable Pairing With One Clash to Navigate",
 "summary": "Hana's yin metal 辛 day master and Dae's yin wood 乙 day master sit in a controlling relationship, and their day stems directly clash - yet their day branches (酉 and 巳), the \"partner palace\", form a three-harmony (삼합) pair that also completes each person's own full 巳酉丑 trine. One real clash alongside one real harmony makes this a workable match: friction worth naming, and a natural rhythm to build on.",
 "accuracy": "Both charts are complete - hour pillars are known for Hana and Dae and neither carries any flags, so this reading draws on the full eight characters on each side. Compatibility reading works with patterns across two charts, not a measurement of fit - treat it as a starting point for conversation, not a score.",
 "dynamics": [
  {
   "text": "Hana's day master 辛 (yin metal - think a blade or fine jewelry) and Dae's day master 乙 (yin wood - think a climbing vine) sit in a checking relationship: metal shapes wood the way a tool shapes a plant. Read plainly, that tends to mean Hana's side brings structure or judgment to the pair, and Dae's side brings flexibility and reach - a difference in approach more than a conflict on its own.",
   "cite": [
    "C1",
    "A:DM",
    "B:DM"
   ]
  },
  {
   "text": "The two day masters also form a stem clash (辛-乙), a direct push-pull between the top characters of each chart. Hana's own chart already carries this exact clash twice over, between her day stem and both her month and year stems, so this kind of friction is a familiar pattern for her to name directly rather than let sit.",
   "cite": [
    "C2",
    "A:D1",
    "A:X4",
    "A:X6",
    "B:D1"
   ]
  },
  "..."
 ],
 "strengths": [
  {
   "text": "The day-branch three-harmony (酉 and 巳) gives this pair a natural, companionable rhythm - the kind of everyday-life ease that doesn't need to be built, just used.",
   "cite": [
    "C3",
    "A:D2",
    "B:D2"
   ]
  },
  {
   "text": "Hana's strong metal (3 characters, her chart's dominant element) sits exactly where Dae's chart runs thinnest (metal, 1 character); Dae's earth and water, each counted twice, land where Hana's chart is weak on both. On paper the two charts round each other out more than they overlap.",
   "cite": [
    "A:E-metal",
    "B:E-metal",
    "B:E-earth",
    "B:E-water",
    "A:E-earth",
    "A:E-water"
   ]
  },
  "..."
 ],
 "frictions": [
  {
   "text": "The day stem clash (辛 and 乙) is the headline friction here - two different working styles meeting head-on, and one Hana already has practice naming inside her own chart. Letting disagreements go quiet rather than naming them plainly is the risk to watch.",
   "cite": [
    "C2",
    "A:X4",
    "A:X6"
   ]
  },
  {
   "text": "The checking relationship between the day masters (metal shaping wood) can tip toward one side managing or correcting the other rather than the two meeting as equals - worth noticing if it starts to feel one-directional.",
   "cite": [
    "C1"
   ]
  }
 ],
 "tips": [
  "When a disagreement shows up, name the specific issue in plain words rather than letting it cool off on its own - this pairing's clash responds better to directness than to waiting it out.",
  "Lean on your natural day-branch rhythm for shared routines - meals, schedules, small rituals - where the three-harmony between you already has you moving in sync.",
  "..."
 ],
 "caveats": [
  "This is a cultural tradition for reflection and conversation, not a verdict on the relationship or a prediction of how it will go - treat the clash and the harmony here as themes to talk through, not a score.",
  "This reading treats Hana and Dae the same regardless of relationship type - romantic, friends, family or colleagues - since the question didn't specify one; the leadership note above is about Hana's own chart, not a statement about Dae."
 ]
}

task: reading - Mina and Jun, love (sample people) (mixed)

Input:

{
 "task": "reading",
 "chart": "{\"label\":\"Mina\",\"pillars\":{\"day\":{\"pillar\":\"庚辰\",\"roman\":\"Gyeong-jin\",\"stem\":{\"id\":\"D1\",\"ch\":\"庚\",\"el\":\"yang metal\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"辰\",\"el\":\"earth\",\"animal\":\"Dragon\",\"hidden_main\":\"戊\",\"god\":\"Indirect Resource (편인)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"庚\",\"el\":\"yang metal\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":3,\"earth\":1,\"metal\":3,\"water\":1},\"total\":8,\"dominant\":[\"fire\",\"metal\"],\"missing\":[\"wood\"],\"weak\":[\"earth\",\"water\"],\"yinyang\":{\"yang\":6,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.38,\"balance_el\":\"wood\"},\"interactions\":[],\"flags\":[]}",
 "focus": "love",
 "annual": "{\"year\":2026,\"pillar\":\"丙午\",\"roman\":\"Byeong-o\",\"animal\":\"Horse\",\"stem\":{\"id\":\"A1\",\"ch\":\"丙\",\"el\":\"fire\",\"god\":\"Seven Killings\"},\"branch\":{\"id\":\"A2\",\"ch\":\"午\",\"el\":\"fire\",\"god\":\"Direct Officer\"},\"hits\":[{\"id\":\"AX1\",\"kind\":\"clash\",\"text\":\"the year's 丙 and your hour stem 壬: stem clash\"},{\"id\":\"AX2\",\"kind\":\"combine\",\"text\":\"the year's 丙 and your month stem 辛: stem combination (water)\"}]}"
}

Reply:

{
 "task": "reading",
 "focus": "love",
 "day_master": "庚",
 "dominant": "metal",
 "outlook": "mixed",
 "title": "Metal Day Master, Fire-Heavy Chart: Love Grows Through Steadiness, Not Chasing",
 "summary": "Your day master is 庚 (yang metal), sitting in a chart where fire and metal tie for the lead and wood is nowhere to be found. For love, that shows up as a partner palace built for depth over drama, and no natural \"pull\" energy, so connection tends to need an active hand rather than a chase. This year adds fire on top of fire, with one bit of friction and one bit of ease arriving together.",
 "accuracy": "The full eight characters are known - hour pillar included - and no accuracy flags were raised, so this chart reads as complete with nothing to caveat about timing.",
 "core": [
  {
   "text": "Your day master (일간, the character that stands for you) is 庚, yang metal - like forged metal or raw ore that wants shape and an edge. It sits on 辰 (Dragon, earth) in the day branch, drawing Indirect Resource (편인, an irregular, mentor-like kind of support) rather than a warm, expected kind of help.",
   "cite": [
    "DM",
    "D1",
    "D2"
   ]
  },
  {
   "text": "Fire and metal are tied as your dominant elements (3 of 8 each), wood is missing entirely, and earth and water are thin at 1 each, in a chart that leans heavily yang. Your strength lean reads as \"balanced\" (ratio 0.38), so no single element overwhelms you, but there's little here to cool the fire-metal tension.",
   "cite": [
    "E-wood",
    "E-fire",
    "E-earth",
    "E-metal",
    "E-water",
    "ST"
   ]
  },
  "..."
 ],
 "focus_read": [
  {
   "text": "The day branch, 辰 (Dragon) with hidden stem 戊, is your partner palace, and it carries Indirect Resource (편인). That tends to read as being drawn to people who feel like a teacher, a guide, or a quiet refuge - connection built on depth and learning together more than on a dramatic spark.",
   "cite": [
    "D2"
   ]
  },
  {
   "text": "Wealth gods (the \"pulled toward\" energy in attraction) are entirely absent here, matching wood as your one missing element - the nearest cousin is Rob Wealth (겁재) in the month, which is peer energy, not true pull. Practically, this chart doesn't naturally chase; attraction may need to be chosen and initiated rather than waited for.",
   "cite": [
    "E-wood",
    "M1"
   ]
  },
  "..."
 ],
 "year_ahead": {
  "text": "2026 is 丙午, a fire-on-fire year whose stem 丙 (Seven Killings this year) forms a stem clash (충, two characters pulling opposite ways) with your hour stem 壬 (Eating God, your easy self-expression) - a pull between outside pressure to perform and wanting to do things your own way - while also combining (합, two characters pulling together into something new) with your month stem 辛 (Rob Wealth) to form water, gently loosening the chart's usual self-reliance. Net read: a mixed year, with that friction and this ease arriving side by side rather than one clean theme.",
  "cite": [
   "A1",
   "A2",
   "AX1",
   "AX2",
   "H1",
   "M1"
  ]
 },
 "balance": {
  "element": "wood",
  "text": "Wood is both the element missing from your chart and the one your strength reading points to for steadiness. Small, everyday ways to invite it in: greens and deep teals around you, time near plants, parks or trees, mornings that start with gentle movement or stretching, and work or hobbies about growing and teaching things rather than finishing and cutting them.",
  "cite": [
   "E-wood",
   "ST"
  ]
 },
 "tips": [
  "Let plants, parks, or anything green into time spent with people you're close to - a small, literal nod to the missing wood element.",
  "Since your partner palace leans mentor-like and depth-first, don't wait for fireworks to feel like proof - notice whether you're growing alongside someone instead.",
  "..."
 ],
 "caveats": [
  "This is a tradition for reflection and conversation, not a forecast - read everything here as \"tends to\" or \"a theme to watch,\" never a guarantee about any person or outcome.",
  "These are themes about energy and style, not a verdict on any specific relationship - the people involved are the real read, not the chart."
 ]
}

task: match - Mina and Jun, love (sample people) (natural)

Input:

{
 "task": "match",
 "chart": "{\"label\":\"Mina\",\"pillars\":{\"day\":{\"pillar\":\"庚辰\",\"roman\":\"Gyeong-jin\",\"stem\":{\"id\":\"D1\",\"ch\":\"庚\",\"el\":\"yang metal\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"辰\",\"el\":\"earth\",\"animal\":\"Dragon\",\"hidden_main\":\"戊\",\"god\":\"Indirect Resource (편인)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"庚\",\"el\":\"yang metal\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":3,\"earth\":1,\"metal\":3,\"water\":1},\"total\":8,\"dominant\":[\"fire\",\"metal\"],\"missing\":[\"wood\"],\"weak\":[\"earth\",\"water\"],\"yinyang\":{\"yang\":6,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.38,\"balance_el\":\"wood\"},\"interactions\":[],\"flags\":[]}",
 "partner": "{\"label\":\"Jun\",\"pillars\":{\"day\":{\"pillar\":\"辛酉\",\"roman\":\"Sin-yu\",\"stem\":{\"id\":\"D1\",\"ch\":\"辛\",\"el\":\"yin metal\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"酉\",\"el\":\"metal\",\"animal\":\"Rooster\",\"hidden_main\":\"辛\",\"god\":\"Companion (비견)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"辛\",\"el\":\"yin metal\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":0,\"earth\":4,\"metal\":2,\"water\":2},\"total\":8,\"dominant\":[\"earth\"],\"missing\":[\"wood\",\"fire\"],\"weak\":[],\"yinyang\":{\"yang\":6,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"strong\",\"ratio\":0.75,\"balance_el\":\"water\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"combine\",\"text\":\"day branch 酉 and hour branch 辰: six-harmony combination\"},{\"id\":\"X2\",\"kind\":\"clash\",\"text\":\"month branch 戌 and hour branch 辰: clash\"},\"...\"],\"flags\":[\"hour-edge\"]}",
 "cross": "[{\"id\":\"C1\",\"kind\":\"dm\",\"text\":\"Day masters: A 庚 (yang metal) and B 辛 (yin metal): same element.\"},{\"id\":\"C2\",\"kind\":\"day-combine\",\"text\":\"Day branches (the partner palace) 辰 and 酉: six-harmony combination.\"},{\"id\":\"C3\",\"kind\":\"fills\",\"text\":\"A brings fire (3), which B's chart lacks.\"}]"
}

Reply:

{
 "task": "match",
 "day_masters": [
  "庚",
  "辛"
 ],
 "rapport": "natural",
 "title": "Two Metal Day Masters, One Natural Six-Harmony Between You",
 "summary": "Mina (庚, yang metal) and Jun (辛, yin metal) share the same day-master element, and their day branches - 辰 and 酉, the \"partner palace\" that colours one-on-one bonds - form a six-harmony (육합), a traditional sign of natural pull. Mina's chart also carries three fire characters that Jun's earth-heavy, fire-missing chart doesn't generate on its own, so there's a real two-way fill rather than one side doing all the giving. Overall this reads as a comfortable, complementary pairing worth building on through everyday habits.",
 "accuracy": "Both birth times are known. Mina's chart carries no flags, so it reads as complete. Jun's hour pillar (壬辰) is marked hour-edge, meaning a slightly different recorded birth time could shift it, so treat anything resting on Jun's hour as a touch more tentative than the rest.",
 "dynamics": [
  {
   "text": "Mina's day master 庚 (yang metal) and Jun's day master 辛 (yin metal) are the same element in opposite polarity - like two blades from the same craft, one bolder and one more refined. That kinship tends to read as easy mutual recognition, with a little room for quiet rivalry in who leads.",
   "cite": [
    "A:DM",
    "B:DM",
    "C1"
   ]
  },
  {
   "text": "Mina's day branch 辰 and Jun's day branch 酉 - the palace tied to how each of you shows up in a close bond - form a six-harmony, a classic sign of ease in the one-on-one dynamic rather than in family or work roles.",
   "cite": [
    "A:D2",
    "B:D2",
    "C2"
   ]
  },
  "..."
 ],
 "strengths": [
  {
   "text": "The six-harmony between your day branches points to a comfortable, low-friction way of relating one-on-one - the part of the chart most tied to daily partnership works smoothly between you.",
   "cite": [
    "C2",
    "A:D2",
    "B:D2"
   ]
  },
  {
   "text": "Sharing the same day-master element gives a baseline of mutual understanding - you're likely to recognize each other's direct, get-to-the-point style rather than needing to translate it.",
   "cite": [
    "C1",
    "A:DM",
    "B:DM"
   ]
  },
  "..."
 ],
 "frictions": [
  {
   "text": "Jun's own chart repeats earth branches that clash twice internally - hour against month, and year against month - a sign Jun may privately cycle through restlessness or push-pull moods that have nothing to do with the relationship itself; patience when Jun seems distracted or hard to read can help.",
   "cite": [
    "B:X2",
    "B:X4"
   ]
  }
 ],
 "tips": [
  "Lean into the natural six-harmony of your day branches with a standing one-on-one ritual - a weekly walk or meal just for the two of you reinforces that built-in ease.",
  "Let Mina's fire energy show up in small everyday ways for Jun - cooking something warm together, a sunlit outing - since it's a theme Jun's own chart doesn't produce.",
  "..."
 ],
 "caveats": [
  "This reading is a cultural tradition meant to start a conversation, not a verdict on whether you two should or shouldn't be together.",
  "Jun's hour pillar sits near the hour-edge, so a slightly different registered birth time could change some of the specifics drawn from it."
 ]
}

task: reading - Theo, a late-night birth (sample person) (careful)

Input:

{
 "task": "reading",
 "chart": "{\"label\":\"Theo\",\"pillars\":{\"day\":{\"pillar\":\"戊子\",\"roman\":\"Mu-ja\",\"stem\":{\"id\":\"D1\",\"ch\":\"戊\",\"el\":\"yang earth\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"子\",\"el\":\"water\",\"animal\":\"Rat\",\"hidden_main\":\"癸\",\"god\":\"Direct Wealth (정재)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"戊\",\"el\":\"yang earth\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":1,\"earth\":3,\"metal\":1,\"water\":3},\"total\":8,\"dominant\":[\"earth\",\"water\"],\"missing\":[\"wood\"],\"weak\":[\"fire\",\"metal\"],\"yinyang\":{\"yang\":6,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.5,\"balance_el\":\"wood\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"combine\",\"text\":\"month branch 丑 and hour branch 子: six-harmony combination\"},{\"id\":\"X2\",\"kind\":\"clash\",\"text\":\"year branch 午 and hour branch 子: clash\"},\"...\"],\"flags\":[\"rat-hour\"]}",
 "focus": "health",
 "annual": "{\"year\":2026,\"pillar\":\"丙午\",\"roman\":\"Byeong-o\",\"animal\":\"Horse\",\"stem\":{\"id\":\"A1\",\"ch\":\"丙\",\"el\":\"fire\",\"god\":\"Indirect Resource\"},\"branch\":{\"id\":\"A2\",\"ch\":\"午\",\"el\":\"fire\",\"god\":\"Direct Resource\"},\"hits\":[{\"id\":\"AX1\",\"kind\":\"clash\",\"text\":\"the year's 午 and your hour branch 子: clash\"},{\"id\":\"AX2\",\"kind\":\"clash\",\"text\":\"the year's 丙 and your hour stem 壬: stem clash\"},{\"id\":\"AX3\",\"kind\":\"clash\",\"text\":\"the year's 午 and your day branch 子: clash\"}]}",
 "question": "I have been sleeping badly. Anything in the chart about rest?"
}

Reply:

{
 "task": "reading",
 "focus": "health",
 "day_master": "戊",
 "dominant": "water",
 "outlook": "careful",
 "title": "A Steady Earth, Deep Water Chart Meets a Stirring Fire Year",
 "summary": "Theo's day master is 戊, Yang Earth - steady and absorbing, with strength landing exactly balanced. The chart ties earth and water for dominant, is missing wood, and carries two Rat (子) branches that are both clashed by the Horse (午) within the chart itself. 2026's Fire Horse year repeats that same clash pattern, a theme of rest and routine meeting extra stir this year.",
 "accuracy": "Theo's birth hour is known, so all four pillars (including the hour pillar 壬子) are used here. One flag applies - 'rat-hour': born in the Rat hour (子時, roughly 11pm-1am), different calendar schools can count the day as starting at a different point, which could in principle shift the day pillar, so anything resting specifically on the day pillar is worth holding a little loosely.",
 "core": [
  {
   "text": "Your day master (戊, Yang Earth) - the character that stands for you - reads like a mountain or wide field: steady, absorbing rather than reactive. Strength here lands exactly balanced (ratio 0.5), so it's an even earth, not overloaded or depleted.",
   "cite": [
    "DM",
    "ST"
   ]
  },
  {
   "text": "Earth (3: your day master 戊, month stem 己, month branch 丑) and water (3: hour branch 子 and day branch 子, each hiding 癸) are tied for dominant, while wood is missing and fire and metal are thin (1 each) - a steady frame with little to channel the water or add drive.",
   "cite": [
    "E-earth",
    "E-water",
    "E-wood",
    "E-fire",
    "E-metal",
    "D1",
    "M1",
    "M2",
    "H2",
    "D2"
   ]
  },
  "..."
 ],
 "focus_read": [
  {
   "text": "Read only as energy themes, not diagnosis: three water characters (子 at the hour and day branches, each hiding 癸) sit against three earth characters (戊 at the day stem, 己 at the month stem, 丑 at the month branch) - a frame that leans toward quiet, contained energy rather than restlessness.",
   "cite": [
    "E-water",
    "E-earth",
    "H2",
    "D2",
    "D1",
    "M1",
    "M2"
   ]
  },
  {
   "text": "Wood is missing (0) and fire and metal are both thin (1 each), so as a theme there's little here to channel the water into motion or warm things up - worth watching so stillness doesn't tip into low energy.",
   "cite": [
    "E-wood",
    "E-fire",
    "E-metal"
   ]
  },
  "..."
 ],
 "year_ahead": {
  "text": "2026 is 丙午 (Byeong-o), a Fire year reading as Indirect and Direct Resource for this day master - support and learning themes. But its Horse (午) clashes your hour branch 子 (AX1) and day branch 子 (AX3), and even its 丙 stem clashes your hour stem 壬 (AX2) - three clashes landing on the day and hour pillars, a theme of quiet, steady things (including rest) feeling stirred this year, best met gently rather than fought.",
  "cite": [
   "A1",
   "A2",
   "AX1",
   "AX2",
   "AX3"
  ]
 },
 "balance": {
  "element": "wood",
  "text": "Wood is this chart's steadying element, and also its missing one - think green spaces, plants, mornings, stretching, the colour green, or habits around growth and planning. Small wood-themed additions, like a daily walk among trees or tending a plant, are an easy way to round out the earth-water frame.",
  "cite": [
   "ST",
   "E-wood"
  ]
 },
 "tips": [
  "Keep a simple wind-down routine before bed - dim lights, no screens - to steady the water energy this year's clashes are stirring.",
  "Add a short daily walk, stretch, or time around plants - small wood habits this chart has little of on its own.",
  "..."
 ],
 "caveats": [
  "Saju is a tradition for reflection and conversation - a lens for noticing patterns, not a fixed prediction or a medical opinion.",
  "Ongoing sleep trouble is worth raising with a doctor; this reading only points to energy themes, not causes or treatment."
 ]
}

task: match - Theo, a late-night birth (sample person) (stretch)

Input:

{
 "task": "match",
 "chart": "{\"label\":\"Theo\",\"pillars\":{\"day\":{\"pillar\":\"戊子\",\"roman\":\"Mu-ja\",\"stem\":{\"id\":\"D1\",\"ch\":\"戊\",\"el\":\"yang earth\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"子\",\"el\":\"water\",\"animal\":\"Rat\",\"hidden_main\":\"癸\",\"god\":\"Direct Wealth (정재)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":true,\"day_master\":{\"id\":\"DM\",\"ch\":\"戊\",\"el\":\"yang earth\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":1,\"earth\":3,\"metal\":1,\"water\":3},\"total\":8,\"dominant\":[\"earth\",\"water\"],\"missing\":[\"wood\"],\"weak\":[\"fire\",\"metal\"],\"yinyang\":{\"yang\":6,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"balanced\",\"ratio\":0.5,\"balance_el\":\"wood\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"combine\",\"text\":\"month branch 丑 and hour branch 子: six-harmony combination\"},{\"id\":\"X2\",\"kind\":\"clash\",\"text\":\"year branch 午 and hour branch 子: clash\"},\"...\"],\"flags\":[\"rat-hour\"]}",
 "partner": "{\"label\":\"Ana\",\"pillars\":{\"day\":{\"pillar\":\"丙午\",\"roman\":\"Byeong-o\",\"stem\":{\"id\":\"D1\",\"ch\":\"丙\",\"el\":\"yang fire\",\"god\":\"Day Master (일간)\"},\"branch\":{\"id\":\"D2\",\"ch\":\"午\",\"el\":\"fire\",\"animal\":\"Horse\",\"hidden_main\":\"丁\",\"god\":\"Rob Wealth (겁재)\"}},\"...\":\"hour, month and year in the same shape\"},\"hour_known\":false,\"day_master\":{\"id\":\"DM\",\"ch\":\"丙\",\"el\":\"yang fire\"},\"elements\":{\"counts\":{\"wood\":0,\"fire\":3,\"earth\":1,\"metal\":1,\"water\":1},\"total\":6,\"dominant\":[\"fire\"],\"missing\":[\"wood\"],\"weak\":[\"earth\",\"metal\",\"water\"],\"yinyang\":{\"yang\":4,\"yin\":2}},\"strength\":{\"id\":\"ST\",\"lean\":\"weak\",\"ratio\":0.33,\"balance_el\":\"wood\"},\"interactions\":[{\"id\":\"X1\",\"kind\":\"combine\",\"text\":\"month branch 未 and day branch 午: six-harmony combination\"},{\"id\":\"X2\",\"kind\":\"clash\",\"text\":\"year stem 壬 and day stem 丙: stem clash\"},\"...\"],\"flags\":[\"no-hour\"]}",
 "cross": "[{\"id\":\"C1\",\"kind\":\"dm\",\"text\":\"Day masters: A 戊 (yang earth) and B 丙 (yang fire): B feeds A.\"},{\"id\":\"C2\",\"kind\":\"day-clash\",\"text\":\"Day branches (the partner palace) 子 and 午: clash.\"},{\"id\":\"C3\",\"kind\":\"month-clash\",\"text\":\"Month branches 丑 and 未 clash (different daily rhythms and settings).\"}]",
 "question": "I have been sleeping badly. Anything in the chart about rest?"
}

Reply:

{
 "task": "match",
 "day_masters": [
  "戊",
  "丙"
 ],
 "rapport": "stretch",
 "title": "Fire feeds earth, but two branch clashes make this a real stretch",
 "summary": "Theo's day master (戊, yang earth - the character that stands for him) and Ana's day master (丙, yang fire) sit in a feeding line, with Ana's fire warming Theo's earth. But their day branches (子 Rat and 午 Horse) clash head-on, and their month branches (丑 Ox, 未 Goat) clash too - two separate friction points, which puts this pairing in stretch territory rather than an easy, natural fit. Both charts are also missing wood entirely, giving you a shared direction to grow into together.",
 "accuracy": "Ana's chart has no birth time, so there is no hour pillar for her - this reading uses only her day, month and year pillars. Theo's hour falls in the rat-hour window, where different schools of saju can treat the day pillar differently, so take fine details as approximate rather than exact. Outside those two limits, both charts read as otherwise complete.",
 "dynamics": [
  {
   "text": "Theo's day master (戊, yang earth - the character that stands for him) and Ana's day master (丙, yang fire) meet in a feeding line: fire generates earth, so Ana's energy naturally warms and supports Theo's base instead of the two competing for the same ground.",
   "cite": [
    "C1",
    "A:DM",
    "B:DM"
   ]
  },
  {
   "text": "The two charts lean differently in their five elements: Theo's is balanced across earth and water (3 of 8 each), while Ana's leans hard into fire (3 of 6, with a 'weak' day master that wants outside support) - so Theo tends to bring steadiness where Ana runs hotter and lighter.",
   "cite": [
    "A:ST",
    "A:E-earth",
    "A:E-water",
    "B:ST",
    "B:E-fire"
   ]
  },
  "..."
 ],
 "strengths": [
  {
   "text": "Ana's fire feeding Theo's earth is a generative pairing in the five-element cycle - the kind of match where one person's energy builds the other's, rather than two day masters drawing on the same resource.",
   "cite": [
    "C1",
    "A:DM",
    "B:DM"
   ]
  },
  {
   "text": "You already share a direction: both charts point to wood as the element that would steady them, so any wood-flavored habit you take up together - plants, time outdoors, a creative project - works double duty.",
   "cite": [
    "A:ST",
    "B:ST",
    "A:E-wood",
    "B:E-wood"
   ]
  }
 ],
 "frictions": [
  {
   "text": "Your day branches clash (clash, 충 - two branches pulling opposite ways): Theo's 子 (Rat, water) against Ana's 午 (Horse, fire). The day branch is read as the partner palace, so this friction sits right at the core of how you meet day to day.",
   "cite": [
    "C2",
    "A:D2",
    "B:D2"
   ]
  },
  {
   "text": "Your month branches clash too - Theo's 丑 (Ox) against Ana's 未 (Goat). Month branches read as daily rhythm and setting, so different schedules, routines or work environments may need active syncing rather than assuming they line up on their own.",
   "cite": [
    "C3",
    "A:M2",
    "B:M2"
   ]
  },
  "..."
 ],
 "tips": [
  "Lean into the feeding dynamic - let Ana bring warmth and initiative and Theo bring steadiness, rather than competing for the same role.",
  "Since wood is missing for both of you, try something wood-flavored together: a standing walk, tending plants, or a low-pressure creative hobby.",
  "..."
 ],
 "caveats": [
  "This reading is a conversation starter about tendencies and rapport, not a verdict on whether you two should or shouldn't be together.",
  "Ana's chart has no hour pillar (no birth time given) and Theo's hour sits in the rat-hour window where schools differ on the day pillar - treat the specifics here as approximate, not exact."
 ]
}

Build the input yourself

Load the script in node (global.window = {}; require("./sajukit.js")), then:

const K = SajuKit;
const a = K.chart({ name: "Mina", date: "1990-05-15", time: "12:00", place: "Seoul" }, 2026);   // or a Date for "now"
// custom place: { date, time, place: "Custom", tz: -5, lon: -73.9, dst: true }; unknown time: time_unknown: true
const { input } = K.buildInput("reading", { a, focus: "love", question: "" });
const wire = K.toWire(input);                      // POST this to /estimate and /run
// later: const reply = K.normalize(K.parseReply(job.output.output));
// K.reconcile(reply, { a, focus: "love" }) -> [{level, code, text}]
// match: const b = K.chart({...}, 2026); K.buildInput("match", { a, b, reading: reply })

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://saju-pillars.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"saju-pillars"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "reading", "focus": "work", "chart": "{...}", "annual": "{...}"}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses saju-pillars:<task>:<inputHash>:a<attempt>, and its one reformat retry (with retry_note added) is attempt 2, a new key and a second run. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="saju-pillars:reading:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'

Step 6 — POST /run-stream

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: saju-pillars:reading:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json