NaturaOS User Guide

NaturaOS is a humble digitization effort, inheriting the Vietnamese lunar calendar algorithm from Dr. Ho Ngoc Duc and learning from pioneering scholars (Phan Boi Chau, Nguyen Hien Le, Dr. Nguyen Van Tho). To stay objective and strictly copyright-compliant, the system's text is independently translated and cross-referenced from the classical Chinese originals alongside international scholarship (Wilhelm, Legge). We provide 100% deterministic JSON data for lookup and computation — no superstition, no fortune-telling.

① Get an API Key

Every request to the engine (except discovery and documentation endpoints) requires an API key. A key is tied to your organization.

② Try a Call

Pass the key via the Authorization: Bearer <key> header or X-API-Key: <key>:

curl -H "Authorization: Bearer <api-key>" \
  https://naturaos.mza.vn/api/v1/calendar/day?date=2026-09-05

Standard sample response (envelope):

{
  "ok": true,
  "data": {
    "solar": { "year": 2026, "month": 9, "day": 5 },
    "lunar": { "year": 2026, "month": 7, "day": 24, "leap": false },
    "jd": 2461289
  },
  "meta": {
    "engine": "calendar@0.1.1",
    "conventions": { "calendarEngine": "ho_ngoc_duc" },
    "disclaimer": "...",
    "motto": "Man conforms to Earth • Earth conforms to Heaven • Heaven conforms to the Tao • The Tao conforms to Nature"
  }
}

Every successful response carries meta.disclaimer and meta.motto: the result is material for your own contemplation and verification, not a verdict.

③ Plug Into Your Tools

Each tool accepts a credential its own way. Here is the configuration table for each application:

Tool	Integration Type	How to Configure
Claude Code	MCP CLI	`claude mcp add naturaos https://naturaos.mza.vn/mcp --header "Authorization: Bearer <api-key>"`
Gemini CLI / Desktop	MCP Header	Add an MCP server at `https://naturaos.mza.vn/mcp` with a Bearer token header.
ChatGPT	OAuth 2.0	Does not accept a header — sign in via OAuth when connecting, just enter the URL: `https://naturaos.mza.vn/mcp`
n8n / Scripts	REST API	Call REST directly with the `Authorization: Bearer` or `X-API-Key` header.

④ Operation List

The list of available operations, generated live from the engine's registry:

Operation Name	Description	REST Endpoint	MCP Tool Name	Cost
calendar.dayInfo	Almanac day view: lunar date, day/month/year can chi, solar term, auspicious hours.	/api/v1/calendar/day	calendar_dayInfo	1
calendar.convertSolarToLunar	Convert a solar date to the Vietnamese lunar date.	/api/v1/calendar/lunar-date	calendar_convertSolarToLunar	1
ganzhi.calendarPillars	Year/month/day/hour can chi on the calendar basis (year turns at Tết) — not a bazi chart.	/api/v1/ganzhi/calendar-pillars	ganzhi_calendarPillars	1
wuxing.relations	Five-element generating/controlling relations for one element, or between two.	/api/v1/wuxing/relations	wuxing_relations	1
iching.cast	Cast an I Ching hexagram by the Upper–Lower–Moving numbers or by time.	/api/v1/iching/cast	iching_cast	1
iching.hexagram	Look up an I Ching hexagram: trigrams, lines, relations, scripture and commentary.	/api/v1/iching/hexagram	iching_hexagram	3

See full parameters, copy-and-run examples (curl, JavaScript), and real responses for each op at /docs.

⑤ Rate Limits

Rate limits are counted by each operation's cost, not purely by request count:

Free plan: 200 requests / day, resetting at 00:00 (Asia/Ho_Chi_Minh).
Pro plan: 5000 requests / month.
Check your remaining quota anytime via the endpoint: /api/v1/usage (entirely free, does not consume quota).

⑥ Lost Key / Revoke Key

If you suspect your key was leaked, go to the Dashboard to revoke it immediately.

Note: Due to the distributed cache mechanism (isolate cache) used to optimize D1 read performance, a revoked key may remain valid for up to 60 seconds before being fully rejected across all regions.

⑦ Error Code Table

When a request fails, the engine returns the corresponding HTTP status code along with an envelope containing a stable error code:

Error Code	Meaning	Resolution
UNAUTHORIZED	Missing or invalid API key	Check the header sent. A newly created key can take up to 60 seconds to sync across the network.
QUOTA_EXCEEDED	Out of requests for the period	Wait until the reset time, or call fewer high-cost operations.
RATE_LIMITED	Calling too frequently within a minute	Exceeded the burst limit. Pause and retry after 1 minute.
PLAN_REQUIRED	Requires an upgraded plan	Op belongs to a paid plan. All public ops are currently on the free plan; if you encounter this code, please contact support.
BAD_INPUT	Invalid input parameter	See the `message` field in the JSON for details on fixing the parameter.
METER_UNAVAILABLE	Usage could not be metered	The metering system is temporarily interrupted. The API refuses rather than serve without counting usage. Retry in a few seconds.