# Four Pillars API

> Deterministic Korean saju (four pillars / 사주팔자) and manse-calendar calculation API. Send a birth
> time, timezone and longitude; get the year/month/day/hour pillars, 대운 (luck periods), optional
> ten gods and hidden stems, boundary-uncertainty candidates, and the full calculation basis and
> provenance. Use it instead of computing pillars with a language model: solar-term instants,
> Korean standard-time and DST history, apparent solar time and KASI lunar dates are all handled.

- Base URL: https://api.perpetual.smartlink.ai.kr (the root `GET /` returns a JSON index of links)
- Contract (OpenAPI 3.1, source of truth): https://perpetual.smartlink.ai.kr/openapi.json
- Full agent guide (fields, errors, worked examples): https://perpetual.smartlink.ai.kr/llms-full.txt
- Human pages: https://perpetual.smartlink.ai.kr/ (Korean), https://perpetual.smartlink.ai.kr/en/ (English)
- Auth: `X-API-Key` header (keys issued individually). Pay-per-call via x402 is in preparation.
- Supported: birth dates 1900-01-01 to 2100-12-31 (Gregorian, after lunar conversion), timezone `Asia/Seoul`, longitude 124–132°E.
- Errors: JSON `{code, message, request_id, details}`.

## Endpoints

- `POST /v1/charts` — pillars, 대운, derived relations, uncertainty, basis, provenance.
  Required: `birth.calendar` (`gregorian` | `korean_lunar`), `birth.local_datetime` (`YYYY-MM-DDTHH:mm:ss`, no offset),
  `birth.timezone`, `birth.longitude`. For a lunar leap month set `birth.lunar_leap_month: true`.
  대운 needs `daewoon.direction` (`forward` | `reverse` | `by_year_stem_and_sex` with `sex_for_rule`).
- `GET /v1/convert?calendar=gregorian|korean_lunar&date=YYYY-MM-DD[&lunar_leap_month=true]` — Gregorian ↔ Korean lunar
  date conversion (KASI calendar) and the date's day cycle `calendar_day_ganzhi`.
- `GET /v1/ganzhi?date=YYYY-MM-DD` — the date's day cycle (일진), the year/month pillars at the date's first instant
  (`at_start`) and each 절 inside the date (`transitions`, with local time and the new pillars). No hour pillar.
- `GET /v1/policies` — approved policies, defaults, allowed options, datasets.
- `GET /v1/solar-terms?year=YYYY` — the 24 solar-term instants of a year.
- `GET /v1/lunar-months?lunar_year=YYYY` — months of a lunar year, including leap months.

## Example

```
curl -X POST https://api.perpetual.smartlink.ai.kr/v1/charts \
  -H "X-API-Key: $FOUR_PILLARS_KEY" -H "Content-Type: application/json" \
  -d '{"birth":{"calendar":"gregorian","local_datetime":"1990-03-15T09:30:00",
       "timezone":"Asia/Seoul","longitude":126.978}}'
```

Pillars in the response: year 庚午, month 己卯, day 己卯, hour 戊辰 (`uncertainty.boundary_status` = `stable`).

## Notes for agents

- Results are deterministic for a given `provenance.dataset_id` and policy; cite `provenance` when explaining a chart.
- When `uncertainty.boundary_status` is not `stable`, present every entry in `uncertainty.candidates`
  instead of picking one.
- `calendar_day_ganzhi` is the civil date's cycle. It can differ from a person's day pillar in `/v1/charts`
  (apparent solar time, midnight rules) — use `/v1/charts` for a natal chart.
- Dates in GET query strings can appear in gateway logs; send birth data to `POST /v1/charts`.
- If the user does not know the exact birth time, send `birth.uncertainty_seconds` (up to 3600) rather than guessing a time.
- Birth data is not stored; responses carry `Cache-Control: no-store`.