{"openapi":"3.1.0","info":{"title":"Vietnam facts for AI agents","description":"Sourced, dated, signed facts about Vietnam that changed after LLM training cutoffs. Reference only, not legal or financial advice. Optional free API key: send `Authorization: Bearer <key>` (get one at /agent/khoa-api). Data licence CC BY 4.0.","version":"0.3.0"},"servers":[{"url":"https://hieuluc.io.vn"}],"paths":{"/agent/v1/changes":{"get":{"summary":"V1 Changes","description":"Legal/administrative changes effective on or after `since` (YYYY-MM-DD). Start here with your training cutoff.","operationId":"v1_changes_agent_v1_changes_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":"0000-00-00","title":"Since"}},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/provinces":{"get":{"summary":"V1 Provinces","description":"All 34 province-level units after the 2025 merger and what each was merged from.","operationId":"v1_provinces_agent_v1_provinces_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/provinces/lookup":{"get":{"summary":"V1 Lookup","description":"Resolve an old (pre-2025) or current province name, with or without diacritics, to the current unit.","operationId":"v1_lookup_agent_v1_provinces_lookup_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/exchange-rates":{"get":{"summary":"V1 Rates","description":"VND exchange rates posted by Vietcombank (cached up to 10 minutes). Not the SBV central rate.","operationId":"v1_rates_agent_v1_exchange_rates_get","parameters":[{"name":"currencies","in":"query","required":false,"schema":{"type":"string","maxLength":200,"default":"","title":"Currencies"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/figures":{"get":{"summary":"V1 Figures","description":"Key figures LLMs often get wrong (salary, tax, insurance, provinces, ministries, holidays). `as_of` returns the rule in force on a past date.","operationId":"v1_figures_agent_v1_figures_get","parameters":[{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"}},{"name":"as_of","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"As Of"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/documents":{"get":{"summary":"V1 Documents","description":"Legal document registry: in force, not yet effective, or replaced (by which document, from when).","operationId":"v1_documents_agent_v1_documents_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200,"default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/check":{"get":{"summary":"V1 Check Get","description":"Contradiction check for one or more `claims` (repeat the parameter). See POST for many claims.","operationId":"v1_check_get_agent_v1_check_get","parameters":[{"name":"claims","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"maxItems":500,"title":"Claims"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"summary":"V1 Check Post","description":"Contradiction check: send statements you believe about Vietnam; each gets outdated | confirmed | unknown | no_match plus the authoritative fact card.","operationId":"v1_check_post_agent_v1_check_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claims"],"properties":{"claims":{"type":"array","items":{"type":"string","maxLength":500},"minItems":1,"maxItems":20}}},"example":{"claims":["Việt Nam có 63 tỉnh","Lương cơ sở là 2.340.000 đồng"]}}}}}},"/agent/v1/verify-citation":{"get":{"summary":"V1 Verify Citation","description":"Is this URL a Vietnamese state publication, and which facts/documents cite it? Does not fetch the URL.","operationId":"v1_verify_citation_agent_v1_verify_citation_get","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","maxLength":2000,"title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/status":{"get":{"summary":"V1 Status","description":"Freshness contract per dataset: last_checked, check_interval_days, max_staleness_days, check levels.","operationId":"v1_status_agent_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/dump.json":{"get":{"summary":"V1 Dump","description":"Full signed dump of curated facts (changes, figures, documents, provinces, holidays) for RAG/offline use. CC BY 4.0.","operationId":"v1_dump_agent_v1_dump_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/bench.json":{"get":{"summary":"V1 Bench","description":"vn-staleness-bench: public eval questions whose answers changed recently (CC BY 4.0).","operationId":"v1_bench_agent_v1_bench_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/report":{"post":{"summary":"V1 Report","description":"Report a wrong/outdated fact. Requires source_url on a Vietnamese state publisher; reviewed by a human.","operationId":"v1_report_agent_v1_report_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"claim":{"type":"string","maxLength":500},"message":{"type":"string","maxLength":2000,"minLength":10},"source_url":{"type":"string","format":"uri"},"slug":{"type":"string"}},"type":"object","required":["claim","message","source_url"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/v1/wards":{"get":{"summary":"V1 Wards","description":"Search the 3,321 commune-level units (phường/xã/đặc khu) by name, optionally within a province.","operationId":"v1_wards_agent_v1_wards_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Name"}},{"name":"province","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Province"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/wards/{code}":{"get":{"summary":"V1 Ward","description":"Get a commune-level unit by its official code.","operationId":"v1_ward_agent_v1_wards__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/calendar":{"get":{"summary":"V1 Calendar","description":"Convert solar <-> Vietnamese lunar dates (UTC+7) with can-chi names.","operationId":"v1_calendar_agent_v1_calendar_get","parameters":[{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Date"}},{"name":"lunar_day","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":30,"minimum":1},{"type":"null"}],"title":"Lunar Day"}},{"name":"lunar_month","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":12,"minimum":1},{"type":"null"}],"title":"Lunar Month"}},{"name":"lunar_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1900},{"type":"null"}],"title":"Lunar Year"}},{"name":"leap","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Leap"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/holidays":{"get":{"summary":"V1 Holidays","description":"Statutory paid public holidays for a year plus official public-sector schedules.","operationId":"v1_holidays_agent_v1_holidays_get","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":1900,"title":"Year"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/banks":{"get":{"summary":"V1 Banks","description":"Vietnamese bank codes for VietQR/NAPAS: BIN, short code, SWIFT.","operationId":"v1_banks_agent_v1_banks_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100,"default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/changes.atom":{"get":{"summary":"V1 Changes Atom","description":"Atom feed of changes.","operationId":"v1_changes_atom_agent_v1_changes_atom_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp":{"post":{"summary":"Mcp Post","description":"MCP endpoint (Streamable HTTP, stateless JSON-RPC 2.0). Tools: vn_check, vn_lookup, vn_changes_since, vn_calendar, vn_report_error.","operationId":"mcp_post_mcp_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC 2.0 request (initialize, tools/list, tools/call, ping)"},"example":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"vn_check","arguments":{"claims":["Việt Nam có 63 tỉnh"]}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{},{"bearer":[]},{"apiKey":[]}]}