{"openapi":"3.0.3","info":{"title":"Naturaos API","version":"0.1.0","description":"Headless Eastern-metaphysics engine — âm lịch (Hồ Ngọc Đức), can chi, kinh dịch, ngũ hành. Every endpoint returns the uniform `{ ok, data, meta }` envelope."},"servers":[{"url":"/"}],"tags":[{"name":"calendar","description":"Âm lịch — lunar calendar & almanac"},{"name":"ganzhi","description":"Can chi — stems & branches on the CALENDAR basis (year at Tết, month at lunar day 1). Not bát tự / tứ trụ, which uses Lập xuân and the solar term."},{"name":"iching","description":"Kinh dịch — hexagram lookup & casting"},{"name":"account","description":"Your own allowance — not an engine operation"}],"paths":{"/api/v1/calendar/day":{"get":{"tags":["calendar"],"description":"Full almanac day view (xem ngày): lunar date, ngày/tháng/năm can chi, giờ đầu ngày, tiết khí, giờ hoàng đạo. ⚠️ Two conventions coexist here on purpose: canChi follows the LUNAR calendar (year at Tết, month at lunar day 1), while almanac.dayOfficer/dutyGod follow the SOLAR TERM (trực/kiến-trừ is term-based). Both are declared in meta.conventions. canChi is therefore NOT a bát tự chart — see ganzhi.calendarPillars for the same caveat. Nhập ngày: 'date' (YYYY-MM-DD) HOẶC day+month+year (không cả hai).","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"calendar_dayInfo_get","parameters":[{"name":"day","in":"query","required":false,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'.","schema":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'."}},{"name":"month","in":"query","required":false,"description":"Tháng dương (1-12). Đi kèm day+year (cách B).","schema":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm day+year (cách B)."}},{"name":"year","in":"query","required":false,"description":"Năm dương (1-9999). Đi kèm day+month (cách B).","schema":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương (1-9999). Đi kèm day+month (cách B)."}},{"name":"date","in":"query","required":false,"description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400)."}},{"name":"tz","in":"query","required":false,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","schema":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"solar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"weekday":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["day","month","year","weekday"],"additionalProperties":false},"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"canChi":{"type":"object","properties":{"day":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"month":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"year":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false}},"required":["day","month","year"],"additionalProperties":false},"firstHour":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"solarTerm":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"auspiciousHours":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"range":{"type":"string"},"startHour":{"type":"number"},"endHour":{"type":"number"}},"required":["code","label","range","startHour","endHour"],"additionalProperties":false}},"almanac":{"type":"object","properties":{"nayin":{"type":"object","properties":{"code":{"type":"string"},"element":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","element","label"],"additionalProperties":false},"dayOfficer":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"dutyGod":{"type":"object","properties":{"code":{"type":"string"},"type":{"type":"string","enum":["hoang","hac"]},"auspicious":{"type":"boolean"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","type","auspicious","label"],"additionalProperties":false}},"required":["nayin","dayOfficer","dutyGod"],"additionalProperties":false},"jd":{"type":"number"}},"required":["solar","lunar","canChi","firstHour","solarTerm","auspiciousHours","almanac","jd"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["calendar"],"description":"Full almanac day view (xem ngày): lunar date, ngày/tháng/năm can chi, giờ đầu ngày, tiết khí, giờ hoàng đạo. ⚠️ Two conventions coexist here on purpose: canChi follows the LUNAR calendar (year at Tết, month at lunar day 1), while almanac.dayOfficer/dutyGod follow the SOLAR TERM (trực/kiến-trừ is term-based). Both are declared in meta.conventions. canChi is therefore NOT a bát tự chart — see ganzhi.calendarPillars for the same caveat. Nhập ngày: 'date' (YYYY-MM-DD) HOẶC day+month+year (không cả hai).","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"calendar_dayInfo_post","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'."},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm day+year (cách B)."},"year":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương (1-9999). Đi kèm day+month (cách B)."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400)."},"tz":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"solar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"weekday":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["day","month","year","weekday"],"additionalProperties":false},"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"canChi":{"type":"object","properties":{"day":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"month":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"year":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false}},"required":["day","month","year"],"additionalProperties":false},"firstHour":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"solarTerm":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"auspiciousHours":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"range":{"type":"string"},"startHour":{"type":"number"},"endHour":{"type":"number"}},"required":["code","label","range","startHour","endHour"],"additionalProperties":false}},"almanac":{"type":"object","properties":{"nayin":{"type":"object","properties":{"code":{"type":"string"},"element":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","element","label"],"additionalProperties":false},"dayOfficer":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"dutyGod":{"type":"object","properties":{"code":{"type":"string"},"type":{"type":"string","enum":["hoang","hac"]},"auspicious":{"type":"boolean"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","type","auspicious","label"],"additionalProperties":false}},"required":["nayin","dayOfficer","dutyGod"],"additionalProperties":false},"jd":{"type":"number"}},"required":["solar","lunar","canChi","firstHour","solarTerm","auspiciousHours","almanac","jd"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/calendar/lunar-date":{"get":{"tags":["calendar"],"description":"Convert a solar (Gregorian) date to the Vietnamese lunar date (âm lịch). Nhập: 'date' (YYYY-MM-DD) HOẶC day+month+year (không cả hai).","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"calendar_convertSolarToLunar_get","parameters":[{"name":"day","in":"query","required":false,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'.","schema":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'."}},{"name":"month","in":"query","required":false,"description":"Tháng dương (1-12). Đi kèm day+year (cách B).","schema":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm day+year (cách B)."}},{"name":"year","in":"query","required":false,"description":"Năm dương (1-9999). Đi kèm day+month (cách B).","schema":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương (1-9999). Đi kèm day+month (cách B)."}},{"name":"date","in":"query","required":false,"description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400).","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400)."}},{"name":"tz","in":"query","required":false,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","schema":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"solar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":false},"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"jd":{"type":"number"}},"required":["solar","lunar","jd"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["calendar"],"description":"Convert a solar (Gregorian) date to the Vietnamese lunar date (âm lịch). Nhập: 'date' (YYYY-MM-DD) HOẶC day+month+year (không cả hai).","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"calendar_convertSolarToLunar_post","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). CÁCH B — cần đủ cả day+month+year; hoặc bỏ cả bộ và dùng 'date'."},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm day+year (cách B)."},"year":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương (1-9999). Đi kèm day+month (cách B)."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Ngày dương lịch dạng ISO 'YYYY-MM-DD' (vd 2026-07-01). CÁCH A để nhập ngày — dùng field này HOẶC bộ số day+month+year, KHÔNG dùng cả hai (gửi cả hai → lỗi 400)."},"tz":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"solar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":false},"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"jd":{"type":"number"}},"required":["solar","lunar","jd"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/ganzhi/calendar-pillars":{"get":{"tags":["ganzhi"],"description":"Can chi (stems & branches) for a datetime on the CALENDAR basis: the year turns at Tết, the month at lunar day 1. This is the can chi a lịch vạn niên prints — for xem ngày / chọn ngày. ⚠️ NOT a bát tự / tứ trụ chart: bazi turns the year at Lập xuân and the month at the solar term, so between those boundaries the two disagree. Do not cast a bazi with this op. Every convention that decides the answer — including the zi-hour boundary — is declared in meta.conventions. Nhập: 'datetime' (YYYY-MM-DD HH:mm) HOẶC year+month+day+hour (không cả hai).","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"ganzhi_calendarPillars_get","parameters":[{"name":"year","in":"query","required":false,"description":"Năm dương. CÁCH B — cần đủ year+month+day+hour; hoặc bỏ cả bộ và dùng 'datetime'.","schema":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương. CÁCH B — cần đủ year+month+day+hour; hoặc bỏ cả bộ và dùng 'datetime'."}},{"name":"month","in":"query","required":false,"description":"Tháng dương (1-12). Đi kèm year+day+hour (cách B).","schema":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm year+day+hour (cách B)."}},{"name":"day","in":"query","required":false,"description":"Ngày dương (1-31). Đi kèm year+month+hour (cách B).","schema":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). Đi kèm year+month+hour (cách B)."}},{"name":"hour","in":"query","required":false,"description":"Giờ (0-23) — quyết định trụ giờ. Đi kèm year+month+day (cách B).","schema":{"type":"integer","minimum":0,"maximum":23,"description":"Giờ (0-23) — quyết định trụ giờ. Đi kèm year+month+day (cách B)."}},{"name":"datetime","in":"query","required":false,"description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(:\\d{2})?$","description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai."}},{"name":"tz","in":"query","required":false,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","schema":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"pillars":{"type":"object","properties":{"year":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"month":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"day":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"hour":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false}},"required":["year","month","day","hour"],"additionalProperties":false}},"required":["lunar","pillars"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["ganzhi"],"description":"Can chi (stems & branches) for a datetime on the CALENDAR basis: the year turns at Tết, the month at lunar day 1. This is the can chi a lịch vạn niên prints — for xem ngày / chọn ngày. ⚠️ NOT a bát tự / tứ trụ chart: bazi turns the year at Lập xuân and the month at the solar term, so between those boundaries the two disagree. Do not cast a bazi with this op. Every convention that decides the answer — including the zi-hour boundary — is declared in meta.conventions. Nhập: 'datetime' (YYYY-MM-DD HH:mm) HOẶC year+month+day+hour (không cả hai).","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"ganzhi_calendarPillars_post","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1,"maximum":9999,"description":"Năm dương. CÁCH B — cần đủ year+month+day+hour; hoặc bỏ cả bộ và dùng 'datetime'."},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Tháng dương (1-12). Đi kèm year+day+hour (cách B)."},"day":{"type":"integer","minimum":1,"maximum":31,"description":"Ngày dương (1-31). Đi kèm year+month+hour (cách B)."},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Giờ (0-23) — quyết định trụ giờ. Đi kèm year+month+day (cách B)."},"datetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(:\\d{2})?$","description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai."},"tz":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"lunar":{"type":"object","properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"},"leap":{"type":"boolean"}},"required":["day","month","year","leap"],"additionalProperties":false},"pillars":{"type":"object","properties":{"year":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"month":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"day":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false},"hour":{"type":"object","properties":{"code":{"type":"string"},"stem":{"type":"string"},"branch":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","stem","branch","label"],"additionalProperties":false}},"required":["year","month","day","hour"],"additionalProperties":false}},"required":["lunar","pillars"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/wuxing/relations":{"get":{"tags":["wuxing"],"description":"Ngũ hành sinh/khắc lookup. Given one element, returns its full row of the two cycles — what it generates (我生), is generated by (生我), controls (我克), is controlled by (克我). Given a second element via 'target', also names their directed relation. Universal relations — no school variance, no calendar, no time input. Element codes match the element/nayin fields other ops emit: wood, fire, earth, metal, water.","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"wuxing_relations_get","parameters":[{"name":"element","in":"query","required":true,"description":"Hành, theo mã máy: wood=Mộc, fire=Hỏa, earth=Thổ, metal=Kim, water=Thủy — cùng bộ mã mà calendar.dayInfo và ganzhi.calendarPillars phát ở các trường element/nayin.","schema":{"type":"string","enum":["wood","fire","earth","metal","water"],"description":"Hành, theo mã máy: wood=Mộc, fire=Hỏa, earth=Thổ, metal=Kim, water=Thủy — cùng bộ mã mà calendar.dayInfo và ganzhi.calendarPillars phát ở các trường element/nayin."}},{"name":"target","in":"query","required":false,"description":"Hành thứ hai (tuỳ chọn). Có nó thì response thêm khối 'withTarget': quan hệ CÓ HƯỚNG từ 'element' nhìn sang 'target' (ta sinh / sinh ta / ta khắc / khắc ta / đồng hành).","schema":{"type":"string","enum":["wood","fire","earth","metal","water"],"description":"Hành thứ hai (tuỳ chọn). Có nó thì response thêm khối 'withTarget': quan hệ CÓ HƯỚNG từ 'element' nhìn sang 'target' (ta sinh / sinh ta / ta khắc / khắc ta / đồng hành)."}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"element":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"cycle":{"type":"object","properties":{"generates":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành mà nó sinh (我生)"},"generatedBy":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành sinh ra nó (生我)"},"controls":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành mà nó khắc (我克)"},"controlledBy":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành khắc nó (克我)"}},"required":["generates","generatedBy","controls","controlledBy"],"additionalProperties":false},"withTarget":{"type":"object","properties":{"target":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"relation":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Quan hệ của 'element' nhìn sang 'target': same · generates · generatedBy · controls · controlledBy"}},"required":["target","relation"],"additionalProperties":false}},"required":["element","cycle"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["wuxing"],"description":"Ngũ hành sinh/khắc lookup. Given one element, returns its full row of the two cycles — what it generates (我生), is generated by (生我), controls (我克), is controlled by (克我). Given a second element via 'target', also names their directed relation. Universal relations — no school variance, no calendar, no time input. Element codes match the element/nayin fields other ops emit: wood, fire, earth, metal, water.","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"wuxing_relations_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"element":{"type":"string","enum":["wood","fire","earth","metal","water"],"description":"Hành, theo mã máy: wood=Mộc, fire=Hỏa, earth=Thổ, metal=Kim, water=Thủy — cùng bộ mã mà calendar.dayInfo và ganzhi.calendarPillars phát ở các trường element/nayin."},"target":{"type":"string","enum":["wood","fire","earth","metal","water"],"description":"Hành thứ hai (tuỳ chọn). Có nó thì response thêm khối 'withTarget': quan hệ CÓ HƯỚNG từ 'element' nhìn sang 'target' (ta sinh / sinh ta / ta khắc / khắc ta / đồng hành)."},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"required":["element"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"element":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"cycle":{"type":"object","properties":{"generates":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành mà nó sinh (我生)"},"generatedBy":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành sinh ra nó (生我)"},"controls":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành mà nó khắc (我克)"},"controlledBy":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Hành khắc nó (克我)"}},"required":["generates","generatedBy","controls","controlledBy"],"additionalProperties":false},"withTarget":{"type":"object","properties":{"target":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"relation":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false,"description":"Quan hệ của 'element' nhìn sang 'target': same · generates · generatedBy · controls · controlledBy"}},"required":["target","relation"],"additionalProperties":false}},"required":["element","cycle"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/iching/cast":{"get":{"tags":["iching"],"description":"Cast a kinh dịch hexagram by the Thượng–Hạ–Động number or time method. method=numbers → upper/lower/moving; method=time → datetime HOẶC year+month+day+hour. Muốn đọc thêm về quẻ vừa gieo (kinh văn đủ, luận quẻ): gọi tiếp iching.hexagram với query=<kingWen> và include=canonicalText,interpretation — op này chủ ý giữ mỏng.","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"iching_cast_get","parameters":[{"name":"method","in":"query","required":true,"description":"Cách gieo quẻ. 'numbers' = theo số Thượng-Hạ-Động → điền upper/lower/moving. 'time' = theo thời điểm → điền datetime HOẶC year+month+day+hour.","schema":{"type":"string","enum":["numbers","time"],"description":"Cách gieo quẻ. 'numbers' = theo số Thượng-Hạ-Động → điền upper/lower/moving. 'time' = theo thời điểm → điền datetime HOẶC year+month+day+hour."}},{"name":"upper","in":"query","required":false,"description":"[method=numbers · BẮT BUỘC] Thượng số → quẻ thượng (ngoại quái); lấy mod 8 (chia hết → 8).","schema":{"type":"integer","description":"[method=numbers · BẮT BUỘC] Thượng số → quẻ thượng (ngoại quái); lấy mod 8 (chia hết → 8)."}},{"name":"lower","in":"query","required":false,"description":"[method=numbers · BẮT BUỘC] Hạ số → quẻ hạ (nội quái); lấy mod 8.","schema":{"type":"integer","description":"[method=numbers · BẮT BUỘC] Hạ số → quẻ hạ (nội quái); lấy mod 8."}},{"name":"moving","in":"query","required":false,"description":"[method=numbers · tùy chọn] Số động → hào động; lấy mod 6. Bỏ trống → tự tính (upper+lower) mod 6.","schema":{"type":"integer","description":"[method=numbers · tùy chọn] Số động → hào động; lấy mod 6. Bỏ trống → tự tính (upper+lower) mod 6."}},{"name":"year","in":"query","required":false,"description":"[method=time] Năm dương. Cần đủ year+month+day+hour, hoặc dùng 'datetime'.","schema":{"type":"integer","minimum":1,"maximum":9999,"description":"[method=time] Năm dương. Cần đủ year+month+day+hour, hoặc dùng 'datetime'."}},{"name":"month","in":"query","required":false,"description":"[method=time] Tháng (1-12). Đi kèm year+day+hour.","schema":{"type":"integer","minimum":1,"maximum":12,"description":"[method=time] Tháng (1-12). Đi kèm year+day+hour."}},{"name":"day","in":"query","required":false,"description":"[method=time] Ngày (1-31). Đi kèm year+month+hour.","schema":{"type":"integer","minimum":1,"maximum":31,"description":"[method=time] Ngày (1-31). Đi kèm year+month+hour."}},{"name":"hour","in":"query","required":false,"description":"[method=time] Giờ (0-23). Đi kèm year+month+day.","schema":{"type":"integer","minimum":0,"maximum":23,"description":"[method=time] Giờ (0-23). Đi kèm year+month+day."}},{"name":"datetime","in":"query","required":false,"description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(:\\d{2})?$","description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai."}},{"name":"tz","in":"query","required":false,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","schema":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"primary":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"mutual":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"changed":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"movingLine":{"type":"object","properties":{"position":{"type":"number","description":"1..6, 1 = hào dưới cùng (Hào 1)."},"primary":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"mutual":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"changed":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["position","primary","mutual","changed"],"additionalProperties":false,"description":"Hào từ (爻辭) của hào động, đọc ở cả ba quẻ — bản quái, hỗ quái, biến quái."},"numbers":{"type":"object","properties":{"upper":{"type":"number"},"lower":{"type":"number"},"moving":{"type":"number"}},"required":["upper","lower","moving"],"additionalProperties":false}},"required":["primary","mutual","changed","movingLine","numbers"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["iching"],"description":"Cast a kinh dịch hexagram by the Thượng–Hạ–Động number or time method. method=numbers → upper/lower/moving; method=time → datetime HOẶC year+month+day+hour. Muốn đọc thêm về quẻ vừa gieo (kinh văn đủ, luận quẻ): gọi tiếp iching.hexagram với query=<kingWen> và include=canonicalText,interpretation — op này chủ ý giữ mỏng.","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"iching_cast_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["numbers","time"],"description":"Cách gieo quẻ. 'numbers' = theo số Thượng-Hạ-Động → điền upper/lower/moving. 'time' = theo thời điểm → điền datetime HOẶC year+month+day+hour."},"upper":{"type":"integer","description":"[method=numbers · BẮT BUỘC] Thượng số → quẻ thượng (ngoại quái); lấy mod 8 (chia hết → 8)."},"lower":{"type":"integer","description":"[method=numbers · BẮT BUỘC] Hạ số → quẻ hạ (nội quái); lấy mod 8."},"moving":{"type":"integer","description":"[method=numbers · tùy chọn] Số động → hào động; lấy mod 6. Bỏ trống → tự tính (upper+lower) mod 6."},"year":{"type":"integer","minimum":1,"maximum":9999,"description":"[method=time] Năm dương. Cần đủ year+month+day+hour, hoặc dùng 'datetime'."},"month":{"type":"integer","minimum":1,"maximum":12,"description":"[method=time] Tháng (1-12). Đi kèm year+day+hour."},"day":{"type":"integer","minimum":1,"maximum":31,"description":"[method=time] Ngày (1-31). Đi kèm year+month+hour."},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"[method=time] Giờ (0-23). Đi kèm year+month+day."},"datetime":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(:\\d{2})?$","description":"Ngày giờ dương lịch ISO 'YYYY-MM-DD HH:mm[:ss]' (vd '2026-07-01 10:30'). CÁCH A để nhập thời điểm — dùng field này HOẶC bộ số year+month+day+hour, KHÔNG dùng cả hai."},"tz":{"type":"number","minimum":-14,"maximum":14,"description":"Múi giờ (UTC offset). Mặc định 7 = giờ Việt Nam (UTC+7).","default":7},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"required":["method"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"primary":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"mutual":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"changed":{"type":"object","properties":{"code":{"type":"string"},"kingWen":{"type":"number"},"glyph":{"type":"string"},"binary":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"judgment":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭) từ 周易, kèm bản dịch tiếng Việt của naturaos."}},"required":["code","kingWen","glyph","binary","name","judgment"],"additionalProperties":false},"movingLine":{"type":"object","properties":{"position":{"type":"number","description":"1..6, 1 = hào dưới cùng (Hào 1)."},"primary":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"mutual":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"changed":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["position","primary","mutual","changed"],"additionalProperties":false,"description":"Hào từ (爻辭) của hào động, đọc ở cả ba quẻ — bản quái, hỗ quái, biến quái."},"numbers":{"type":"object","properties":{"upper":{"type":"number"},"lower":{"type":"number"},"moving":{"type":"number"}},"required":["upper","lower","moving"],"additionalProperties":false}},"required":["primary","mutual","changed","movingLine","numbers"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/iching/hexagram":{"get":{"tags":["iching"],"description":"Look up a kinh dịch hexagram WITHOUT casting — no datetime, no moving line. Returns structural facts: the two trigrams with their 卦德/tượng/ngũ hành, the six lines with their classical relations (đắc chính, trung, ứng, tị/thừa/thặng, tam tài), and optionally the relation graph (tống, thác, hỗ, lưỡng tượng dịch, tiêu tức). Text rides on include: 'canonicalText' = the 周易 scripture (zh + vi, Text layer also en/Legge 1882), 'interpretation' = naturaos's own editorial commentary (vi). Tra quẻ: query = số King Wen, binary 6 bit, 'hex.NN', hoặc tên tiếng Việt.","summary":"Tham số trên URL (query string) — tiện thử nhanh / share link","operationId":"iching_hexagram_get","parameters":[{"name":"query","in":"query","required":true,"description":"Quẻ cần tra. Năm dạng, phân giải theo đúng thứ tự này: (1) số nguyên 1-64 → số King Wen; (2) chuỗi 6 ký tự 0/1 → binary đọc từ dưới lên, vd '100000' = Địa Lôi Phục; (3) chuỗi 1-2 chữ số → cũng là số King Wen, vd '24' (GET truyền mọi thứ dạng chuỗi; không đệm số 0, '024' không tra được vì dạng 2 phải được ưu tiên); (4) 'hex.NN' → mã quẻ, đúng 2 chữ số và viết thường, vd 'hex.24' (không phải 'hex.1'); (5) còn lại → tên tiếng Việt đầy đủ, vd 'Địa Lôi Phục' (chỉ hỗ trợ tiếng Việt; tên rút gọn như 'Phục' KHÔNG tra được). Tên trùng sau khi bỏ dấu → lỗi liệt kê ứng viên.","schema":{"type":"string","minLength":1,"maxLength":64,"description":"Quẻ cần tra. Năm dạng, phân giải theo đúng thứ tự này: (1) số nguyên 1-64 → số King Wen; (2) chuỗi 6 ký tự 0/1 → binary đọc từ dưới lên, vd '100000' = Địa Lôi Phục; (3) chuỗi 1-2 chữ số → cũng là số King Wen, vd '24' (GET truyền mọi thứ dạng chuỗi; không đệm số 0, '024' không tra được vì dạng 2 phải được ưu tiên); (4) 'hex.NN' → mã quẻ, đúng 2 chữ số và viết thường, vd 'hex.24' (không phải 'hex.1'); (5) còn lại → tên tiếng Việt đầy đủ, vd 'Địa Lôi Phục' (chỉ hỗ trợ tiếng Việt; tên rút gọn như 'Phục' KHÔNG tra được). Tên trùng sau khi bỏ dấu → lỗi liệt kê ứng viên."}},{"name":"view","in":"query","required":false,"description":"Độ chi tiết: compact = định danh + hai quái; standard (mặc định) = thêm tóm tắt 6 hào; full = thêm đầy đủ quan hệ hào vị (ứng, tị/thừa/thặng, tam tài, vai vị).","schema":{"type":"string","enum":["compact","standard","full"],"default":"standard","description":"Độ chi tiết: compact = định danh + hai quái; standard (mặc định) = thêm tóm tắt 6 hào; full = thêm đầy đủ quan hệ hào vị (ứng, tị/thừa/thặng, tam tài, vai vị)."}},{"name":"include","in":"query","required":false,"description":"Khối tuỳ chọn, trực giao với view. 'relations' = đồ thị quan hệ (tống, thác, hỗ, lưỡng tượng dịch, tiêu tức quái). 'canonicalText' = kinh văn: quái từ, thoán truyện, đại tượng, hào từ và tiểu tượng, kèm bản dịch tiếng Việt. 'interpretation' = luận quẻ do naturaos viết — lời bàn biên tập, KHÔNG phải kinh văn. Qua GET: ?include=relations,canonicalText,interpretation.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["relations","canonicalText","interpretation"]},"default":[],"description":"Khối tuỳ chọn, trực giao với view. 'relations' = đồ thị quan hệ (tống, thác, hỗ, lưỡng tượng dịch, tiêu tức quái). 'canonicalText' = kinh văn: quái từ, thoán truyện, đại tượng, hào từ và tiểu tượng, kèm bản dịch tiếng Việt. 'interpretation' = luận quẻ do naturaos viết — lời bàn biên tập, KHÔNG phải kinh văn. Qua GET: ?include=relations,canonicalText,interpretation."}},{"name":"lang","in":"query","required":false,"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","schema":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"}},{"name":"format","in":"query","required":false,"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","schema":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}}],"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"glyph":{"type":"string"},"binary":{"type":"string"}},"required":["kingWen","code","glyph","binary"],"additionalProperties":false},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"trigrams":{"type":"object","properties":{"lower":{"type":"object","properties":{"code":{"type":"string"},"binary":{"type":"string"},"glyph":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"attribute":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"image":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"phase":{"type":"string"},"familyRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"fuxiSequenceNumber":{"type":"number"},"earlierHeaven":{"type":"object","properties":{"direction":{"type":"string"}},"required":["direction"],"additionalProperties":false},"laterHeaven":{"type":"object","properties":{"number":{"type":"number"},"direction":{"type":"string"}},"required":["number","direction"],"additionalProperties":false}},"required":["code","binary","glyph","name","attribute","image","phase","familyRole","fuxiSequenceNumber","earlierHeaven","laterHeaven"],"additionalProperties":false},"upper":{"type":"object","properties":{"code":{"type":"string"},"binary":{"type":"string"},"glyph":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"attribute":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"image":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"phase":{"type":"string"},"familyRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"fuxiSequenceNumber":{"type":"number"},"earlierHeaven":{"type":"object","properties":{"direction":{"type":"string"}},"required":["direction"],"additionalProperties":false},"laterHeaven":{"type":"object","properties":{"number":{"type":"number"},"direction":{"type":"string"}},"required":["number","direction"],"additionalProperties":false}},"required":["code","binary","glyph","name","attribute","image","phase","familyRole","fuxiSequenceNumber","earlierHeaven","laterHeaven"],"additionalProperties":false}},"required":["lower","upper"],"additionalProperties":false},"combinedAttribute":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"hasCorrectPosition":{"type":"boolean"},"isCentral":{"type":"boolean"},"isCentralAndCorrect":{"type":"boolean"},"correspondence":{"type":"object","properties":{"withPosition":{"type":"number"},"status":{"type":"string","enum":["correspondent","none"]}},"required":["withPosition","status"],"additionalProperties":false},"adjacency":{"type":"object","properties":{"below":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"relation":{"type":"string","enum":["supports","rides"],"nullable":true}},"required":["position","isYang","relation"],"additionalProperties":false,"nullable":true},"above":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"relation":{"type":"string","enum":["supports","rides"],"nullable":true}},"required":["position","isYang","relation"],"additionalProperties":false,"nullable":true}},"required":["below","above"],"additionalProperties":false},"positionRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"threePowers":{"type":"string","enum":["earth","human","heaven"]},"trigramMembership":{"type":"string","enum":["lower","upper"]}},"required":["position","isYang","hasCorrectPosition","isCentral"],"additionalProperties":false}},"relations":{"type":"object","properties":{"overturnedHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"complementaryHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"nuclearHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"swappedTrigramsHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"isSelfOverturned":{"type":"boolean"},"isPureHexagram":{"type":"boolean"},"waningWaxingHexagram":{"type":"object","properties":{"lunarMonth":{"type":"number"},"monthBranch":{"type":"string"},"yangLineCount":{"type":"number"},"cyclePhase":{"type":"string","enum":["waxing","waning"]}},"required":["lunarMonth","monthBranch","yangLineCount","cyclePhase"],"additionalProperties":false,"nullable":true}},"required":["overturnedHexagram","complementaryHexagram","nuclearHexagram","swappedTrigramsHexagram","isSelfOverturned","isPureHexagram","waningWaxingHexagram"],"additionalProperties":false},"canonicalText":{"type":"object","properties":{"judgment":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭)"},"judgmentCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Thoán truyện (彖傳)"},"greatImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Đại Tượng truyện (大象傳)"},"sequenceCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tự Quái truyện (序卦傳) — vì sao quẻ này nối tiếp quẻ trước trong thứ tự King Wen"},"mixedCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tạp Quái truyện (雜卦傳) — một câu định nghĩa, thường nêu đối với quẻ đối. Vì thiên này dựng theo cặp đối, một câu có thể bao hai (hoặc bốn) quẻ; cả hai giữ nguyên câu, không cắt đôi. Xem sharedWith.mixedCommentary để biết câu này còn thuộc quẻ nào."},"sharedWith":{"type":"object","properties":{"sequenceCommentary":{"type":"array","items":{"type":"integer","minimum":1,"maximum":64}},"mixedCommentary":{"type":"array","items":{"type":"integer","minimum":1,"maximum":64}}},"required":["sequenceCommentary","mixedCommentary"],"additionalProperties":false,"description":"Số hiệu King Wen của những quẻ KHÁC cùng mang đúng câu 序卦傳 / 雜卦傳 này. Mảng rỗng = câu đó của riêng quẻ này. Chỉ 1 trong 64 quẻ có câu 雜卦傳 của riêng mình, nên trường này là thứ phân biệt được 'định nghĩa viết cho quẻ này' với 'câu mà quẻ này chỉ có mặt trong đó'."},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Hào từ (爻辭)"},"smallImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tiểu Tượng truyện (小象傳)"}},"required":["position","text","smallImage"],"additionalProperties":false},"description":"Sáu hào, theo thứ tự từ dưới lên."},"yong":{"type":"object","properties":{"code":{"type":"string","enum":["yongJiu","yongLiu"]},"text":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Một đoạn kinh văn. zh = nguyên văn, vi = bản dịch của naturaos."},"smallImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Một đoạn kinh văn. zh = nguyên văn, vi = bản dịch của naturaos."}},"required":["code","text","smallImage"],"additionalProperties":false,"description":"Chỉ quẻ 1 (用九) và quẻ 2 (用六). KHÔNG phải hào thứ bảy — đây là lệ bói dùng khi gieo được sáu hào đều biến."},"source":{"type":"object","properties":{"page":{"type":"string"},"revid":{"type":"integer"}},"required":["page","revid"],"additionalProperties":false,"description":"Bản zh.wikisource đã nhập, ghim theo revid để truy nguồn được."}},"required":["judgment","judgmentCommentary","greatImage","sequenceCommentary","mixedCommentary","sharedWith","lines","source"],"additionalProperties":false},"interpretation":{"type":"object","properties":{"overview":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Luận quẻ do naturaos viết — KHÔNG phải kinh văn, không phải bản dịch. Chỉ có tiếng Việt."},"author":{"type":"string","enum":["naturaos"]}},"required":["overview","author"],"additionalProperties":false}},"required":["id","name","trigrams","combinedAttribute"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}},"post":{"tags":["iching"],"description":"Look up a kinh dịch hexagram WITHOUT casting — no datetime, no moving line. Returns structural facts: the two trigrams with their 卦德/tượng/ngũ hành, the six lines with their classical relations (đắc chính, trung, ứng, tị/thừa/thặng, tam tài), and optionally the relation graph (tống, thác, hỗ, lưỡng tượng dịch, tiêu tức). Text rides on include: 'canonicalText' = the 周易 scripture (zh + vi, Text layer also en/Legge 1882), 'interpretation' = naturaos's own editorial commentary (vi). Tra quẻ: query = số King Wen, binary 6 bit, 'hex.NN', hoặc tên tiếng Việt.","summary":"Tham số trong JSON body — tiện gọi từ code","operationId":"iching_hexagram_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"anyOf":[{"type":"integer","minimum":1,"maximum":64},{"type":"string","minLength":1,"maxLength":64}],"description":"Quẻ cần tra. Năm dạng, phân giải theo đúng thứ tự này: (1) số nguyên 1-64 → số King Wen; (2) chuỗi 6 ký tự 0/1 → binary đọc từ dưới lên, vd '100000' = Địa Lôi Phục; (3) chuỗi 1-2 chữ số → cũng là số King Wen, vd '24' (GET truyền mọi thứ dạng chuỗi; không đệm số 0, '024' không tra được vì dạng 2 phải được ưu tiên); (4) 'hex.NN' → mã quẻ, đúng 2 chữ số và viết thường, vd 'hex.24' (không phải 'hex.1'); (5) còn lại → tên tiếng Việt đầy đủ, vd 'Địa Lôi Phục' (chỉ hỗ trợ tiếng Việt; tên rút gọn như 'Phục' KHÔNG tra được). Tên trùng sau khi bỏ dấu → lỗi liệt kê ứng viên."},"view":{"type":"string","enum":["compact","standard","full"],"default":"standard","description":"Độ chi tiết: compact = định danh + hai quái; standard (mặc định) = thêm tóm tắt 6 hào; full = thêm đầy đủ quan hệ hào vị (ứng, tị/thừa/thặng, tam tài, vai vị)."},"include":{"type":"array","items":{"type":"string","enum":["relations","canonicalText","interpretation"]},"default":[],"description":"Khối tuỳ chọn, trực giao với view. 'relations' = đồ thị quan hệ (tống, thác, hỗ, lưỡng tượng dịch, tiêu tức quái). 'canonicalText' = kinh văn: quái từ, thoán truyện, đại tượng, hào từ và tiểu tượng, kèm bản dịch tiếng Việt. 'interpretation' = luận quẻ do naturaos viết — lời bàn biên tập, KHÔNG phải kinh văn. Qua GET: ?include=relations,canonicalText,interpretation."},"lang":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi.","default":"vi"},"format":{"type":"string","enum":["json","text-tree"],"description":"Định dạng output: json (mặc định) hoặc text-tree (cây thụt lề, dễ đọc cho người/LLM).","default":"json"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success — the `{ ok, data, meta }` envelope","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"glyph":{"type":"string"},"binary":{"type":"string"}},"required":["kingWen","code","glyph","binary"],"additionalProperties":false},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"trigrams":{"type":"object","properties":{"lower":{"type":"object","properties":{"code":{"type":"string"},"binary":{"type":"string"},"glyph":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"attribute":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"image":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"phase":{"type":"string"},"familyRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"fuxiSequenceNumber":{"type":"number"},"earlierHeaven":{"type":"object","properties":{"direction":{"type":"string"}},"required":["direction"],"additionalProperties":false},"laterHeaven":{"type":"object","properties":{"number":{"type":"number"},"direction":{"type":"string"}},"required":["number","direction"],"additionalProperties":false}},"required":["code","binary","glyph","name","attribute","image","phase","familyRole","fuxiSequenceNumber","earlierHeaven","laterHeaven"],"additionalProperties":false},"upper":{"type":"object","properties":{"code":{"type":"string"},"binary":{"type":"string"},"glyph":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"attribute":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"image":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"phase":{"type":"string"},"familyRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"fuxiSequenceNumber":{"type":"number"},"earlierHeaven":{"type":"object","properties":{"direction":{"type":"string"}},"required":["direction"],"additionalProperties":false},"laterHeaven":{"type":"object","properties":{"number":{"type":"number"},"direction":{"type":"string"}},"required":["number","direction"],"additionalProperties":false}},"required":["code","binary","glyph","name","attribute","image","phase","familyRole","fuxiSequenceNumber","earlierHeaven","laterHeaven"],"additionalProperties":false}},"required":["lower","upper"],"additionalProperties":false},"combinedAttribute":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"hasCorrectPosition":{"type":"boolean"},"isCentral":{"type":"boolean"},"isCentralAndCorrect":{"type":"boolean"},"correspondence":{"type":"object","properties":{"withPosition":{"type":"number"},"status":{"type":"string","enum":["correspondent","none"]}},"required":["withPosition","status"],"additionalProperties":false},"adjacency":{"type":"object","properties":{"below":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"relation":{"type":"string","enum":["supports","rides"],"nullable":true}},"required":["position","isYang","relation"],"additionalProperties":false,"nullable":true},"above":{"type":"object","properties":{"position":{"type":"number"},"isYang":{"type":"boolean"},"relation":{"type":"string","enum":["supports","rides"],"nullable":true}},"required":["position","isYang","relation"],"additionalProperties":false,"nullable":true}},"required":["below","above"],"additionalProperties":false},"positionRole":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false}},"required":["code","label"],"additionalProperties":false},"threePowers":{"type":"string","enum":["earth","human","heaven"]},"trigramMembership":{"type":"string","enum":["lower","upper"]}},"required":["position","isYang","hasCorrectPosition","isCentral"],"additionalProperties":false}},"relations":{"type":"object","properties":{"overturnedHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"complementaryHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"nuclearHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"swappedTrigramsHexagram":{"type":"object","properties":{"kingWen":{"type":"number"},"code":{"type":"string"},"name":{"type":"object","properties":{"vi":{"type":"string"},"en":{"type":"string"},"zh":{"type":"string"},"pinyin":{"type":"string"}},"additionalProperties":false},"binary":{"type":"string"}},"required":["kingWen","code","name","binary"],"additionalProperties":false},"isSelfOverturned":{"type":"boolean"},"isPureHexagram":{"type":"boolean"},"waningWaxingHexagram":{"type":"object","properties":{"lunarMonth":{"type":"number"},"monthBranch":{"type":"string"},"yangLineCount":{"type":"number"},"cyclePhase":{"type":"string","enum":["waxing","waning"]}},"required":["lunarMonth","monthBranch","yangLineCount","cyclePhase"],"additionalProperties":false,"nullable":true}},"required":["overturnedHexagram","complementaryHexagram","nuclearHexagram","swappedTrigramsHexagram","isSelfOverturned","isPureHexagram","waningWaxingHexagram"],"additionalProperties":false},"canonicalText":{"type":"object","properties":{"judgment":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Quái từ (卦辭)"},"judgmentCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Thoán truyện (彖傳)"},"greatImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Đại Tượng truyện (大象傳)"},"sequenceCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tự Quái truyện (序卦傳) — vì sao quẻ này nối tiếp quẻ trước trong thứ tự King Wen"},"mixedCommentary":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tạp Quái truyện (雜卦傳) — một câu định nghĩa, thường nêu đối với quẻ đối. Vì thiên này dựng theo cặp đối, một câu có thể bao hai (hoặc bốn) quẻ; cả hai giữ nguyên câu, không cắt đôi. Xem sharedWith.mixedCommentary để biết câu này còn thuộc quẻ nào."},"sharedWith":{"type":"object","properties":{"sequenceCommentary":{"type":"array","items":{"type":"integer","minimum":1,"maximum":64}},"mixedCommentary":{"type":"array","items":{"type":"integer","minimum":1,"maximum":64}}},"required":["sequenceCommentary","mixedCommentary"],"additionalProperties":false,"description":"Số hiệu King Wen của những quẻ KHÁC cùng mang đúng câu 序卦傳 / 雜卦傳 này. Mảng rỗng = câu đó của riêng quẻ này. Chỉ 1 trong 64 quẻ có câu 雜卦傳 của riêng mình, nên trường này là thứ phân biệt được 'định nghĩa viết cho quẻ này' với 'câu mà quẻ này chỉ có mặt trong đó'."},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Hào từ (爻辭)"},"smallImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Tiểu Tượng truyện (小象傳)"}},"required":["position","text","smallImage"],"additionalProperties":false},"description":"Sáu hào, theo thứ tự từ dưới lên."},"yong":{"type":"object","properties":{"code":{"type":"string","enum":["yongJiu","yongLiu"]},"text":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Một đoạn kinh văn. zh = nguyên văn, vi = bản dịch của naturaos."},"smallImage":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Một đoạn kinh văn. zh = nguyên văn, vi = bản dịch của naturaos."}},"required":["code","text","smallImage"],"additionalProperties":false,"description":"Chỉ quẻ 1 (用九) và quẻ 2 (用六). KHÔNG phải hào thứ bảy — đây là lệ bói dùng khi gieo được sáu hào đều biến."},"source":{"type":"object","properties":{"page":{"type":"string"},"revid":{"type":"integer"}},"required":["page","revid"],"additionalProperties":false,"description":"Bản zh.wikisource đã nhập, ghim theo revid để truy nguồn được."}},"required":["judgment","judgmentCommentary","greatImage","sequenceCommentary","mixedCommentary","sharedWith","lines","source"],"additionalProperties":false},"interpretation":{"type":"object","properties":{"overview":{"type":"object","properties":{"zh":{"type":"string"},"vi":{"type":"string"}},"additionalProperties":false,"description":"Luận quẻ do naturaos viết — KHÔNG phải kinh văn, không phải bản dịch. Chỉ có tiếng Việt."},"author":{"type":"string","enum":["naturaos"]}},"required":["overview","author"],"additionalProperties":false}},"required":["id","name","trigrams","combinedAttribute"],"additionalProperties":false},"meta":{"type":"object","properties":{"engine":{"type":"string"},"language":{"type":"object","properties":{"requested":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"resolved":{"type":"string","enum":["vi","en","zh","all"],"description":"Ngôn ngữ của các nhãn trong response. vi (mặc định) · en · zh (kèm pinyin) · all (mọi ngôn ngữ có sẵn). Nhãn thiếu ngôn ngữ được yêu cầu thì rơi về vi; meta.language.available cho biết response này thật sự có những ngôn ngữ nào. Không ảnh hưởng thông điệp lỗi."},"available":{"type":"array","items":{"type":"string"}},"partial":{"type":"array","items":{"type":"string"}}},"required":["requested","resolved","available","partial"],"additionalProperties":false},"conventions":{"type":"object","additionalProperties":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rightsStatus":{"type":"string","enum":["public_domain","permissive","attribution_required","attribution_uncertain","permission_pending","permission_granted","link_only","all_rights_reserved"]},"appliesTo":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","rightsStatus","appliesTo"],"additionalProperties":false}}},"required":["engine"],"additionalProperties":false}},"required":["ok","data","meta"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","error"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input (missing/out-of-range/impossible date)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"500":{"description":"Unexpected engine error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}},"/api/v1/usage":{"get":{"tags":["account"],"summary":"Hạn mức còn lại của chính bạn","description":"How much of the current period's allowance this credential's org has spent. Reading it is free — it does not itself count against the allowance.","operationId":"account_usage_get","responses":{"200":{"description":"Success — the `{ ok, data }` envelope","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["used","limit","remaining","period","resetAt"],"properties":{"used":{"type":"integer","description":"Units spent this period"},"limit":{"type":"integer","description":"Units the plan allows per period"},"remaining":{"type":"integer"},"period":{"type":"string","description":"The period being counted — a day on free, a month on pro"},"resetAt":{"type":"string","description":"When the counter next returns to zero, in Asia/Ho_Chi_Minh"}}}}}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}},"429":{"description":"Allowance exhausted for this period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResult"}}}}}}}},"components":{"schemas":{"ErrorResult":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable error code (BAD_INPUT, FORBIDDEN, …)"},"message":{"type":"string"}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as a Bearer token"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}