{"openapi":"3.1.0","info":{"title":"VietLex API","version":"1.0.0","description":"Open API for Vietnamese legal database VietLex.vn. 30,000+ laws, decrees, circulars, decisions. No auth, no quota for fair-use. Data CC BY 4.0.","termsOfService":"https://vietlex.vn/dieu-khoan-su-dung","contact":{"name":"VietLex.vn","url":"https://vietlex.vn/lien-he","email":"hoangquochaibqd@gmail.com"},"license":{"name":"CC BY 4.0 (data) / MIT (code)","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://vietlex.vn/api/v1","description":"Production"},{"url":"http://localhost:3003/api/v1","description":"Local dev"}],"x-additional-endpoints":{"note":"File proxy endpoints ngoài /api/v1 namespace. Stream qua proxy nội bộ, không leak upstream.","endpoints":[{"method":"GET","url":"https://vietlex.vn/api/dau-thau/file/{notifyNo}/{filename}","purpose":"Tải file Hồ sơ mời thầu (HSMT)"},{"method":"GET","url":"https://vietlex.vn/api/dau-thau/tbmt/{notifyNo}/{filename}","purpose":"Tải file đính kèm Thông báo mời thầu (TBMT) — file PDF kèm theo nếu có"},{"method":"GET","url":"https://vietlex.vn/api/dau-thau/kqlcnt/{notifyNo}/{filename}","purpose":"Tải file đính kèm Kết quả LCNT"},{"method":"GET","url":"https://vietlex.vn/dau-thau/goi-thau/{notifyNo}/tbmt","purpose":"Bản TBMT chuẩn 17 mục theo Luật 22/2023 (HTML, in PDF qua Ctrl+P)"},{"method":"GET","url":"https://vietlex.vn/dau-thau/ket-qua/{notifyNo}/van-ban","purpose":"Bản KQLCNT chuẩn 12 mục theo Luật 22/2023 Điều 70 (HTML, in PDF qua Ctrl+P)"}]},"paths":{"/":{"get":{"summary":"Service metadata","description":"List available endpoints, license, contact.","responses":{"200":{"description":"Service info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInfo"}}}}}}},"/search":{"get":{"summary":"Full-text search VBPL","description":"Search Vietnamese legal documents by keyword, with filters by type, year, field, locality.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search keyword (UTF-8, có dấu hoặc không dấu)"},{"name":"loai","in":"query","schema":{"type":"string","enum":["Luật","Bộ luật","Nghị định","Thông tư","Quyết định","Nghị quyết","Pháp lệnh","Lệnh","Chỉ thị","Thông báo","Công văn"]},"description":"Loại VBPL"},{"name":"nam","in":"query","schema":{"type":"integer","minimum":1945,"maximum":2030},"description":"Năm ban hành"},{"name":"linh_vuc","in":"query","schema":{"type":"string"},"description":"Lĩnh vực (vd \"Dân sự\", \"Hình sự\", \"Thuế\")"},{"name":"dia_phuong","in":"query","schema":{"type":"string"},"description":"Tỉnh/TP ban hành (sau sáp nhập 34 ĐVHC)"},{"name":"kind_group","in":"query","schema":{"type":"string","enum":["linh-vuc","dia-phuong","van-ban-dang","an-le","ban-an","ket-luan-thanh-tra","kiem-toan-nha-nuoc"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/VbplHit"}},"estimatedTotalHits":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}}},"/document/{id}":{"get":{"summary":"Get VBPL detail","description":"Full document including metadata, fulltext (if available), tags.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"VBPL ID (vd \"doc_12345\" hoặc UUID)"}],"responses":{"200":{"description":"Document detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VbplDoc"}}}},"404":{"description":"Not found"}}}},"/citator/{id}":{"get":{"summary":"Get citator tier for VBPL","description":"Returns 5-tier legal status: green (còn hiệu lực), yellow (sửa đổi/bổ sung), orange (đính chính), red (hết hiệu lực/bãi bỏ), gray (hợp nhất). Plus inbound/outbound legal relationships.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Citator data","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"string","enum":["green","yellow","orange","red","gray"]},"inbound":{"type":"array","items":{"$ref":"#/components/schemas/EffectEdge"}},"outbound":{"type":"array","items":{"$ref":"#/components/schemas/EffectEdge"}}}}}}}}}},"/effects/{id}":{"get":{"summary":"Get legal effects","description":"All inbound/outbound edges for this VBPL (sửa đổi, thay thế, bãi bỏ, dẫn chiếu...).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Effects list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EffectEdge"}}}}}}}},"/timeline/{id}":{"get":{"summary":"Get VBPL timeline","description":"Chronological versions of this VBPL (original + amendments + consolidations).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Timeline","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}}},"/linh-vuc":{"get":{"summary":"List legal fields (lĩnh vực)","description":"All 54 legal fields (lĩnh vực) categorizing VBPL.","responses":{"200":{"description":"Field list","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}}},"/dia-phuong":{"get":{"summary":"List localities (34 ĐVHC sau sáp nhập 7/2025)","description":"6 thành phố TW + 28 tỉnh sau sáp nhập 7/2025.","responses":{"200":{"description":"Locality list","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}}},"/dump":{"get":{"summary":"Bulk export VBPL metadata (NDJSON)","description":"NDJSON dump of ~30K VBPL metadata. Use for academic research, bulk processing.","responses":{"200":{"description":"NDJSON stream","content":{"application/x-ndjson":{"schema":{"type":"string"}}}}}}},"/effects-dump":{"get":{"summary":"Bulk export citator edges (NDJSON)","description":"NDJSON dump of ~28K citator edges (vbpl_effects). Use for legal network analysis.","responses":{"200":{"description":"NDJSON stream","content":{"application/x-ndjson":{"schema":{"type":"string"}}}}}}},"/dau-thau/heatmap":{"get":{"summary":"Heatmap 34 ĐVHC + scope counts","description":"Count gói thầu trong 12 tháng theo 34 đơn vị hành chính cấp tỉnh (sau sáp nhập 7/2025) + 3 phạm vi đặc biệt (toàn quốc/đa tỉnh/nước ngoài). Phase A.5 sub-step 22/5/2026.","parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["12m","all"],"default":"12m"}}],"responses":{"200":{"description":"Heatmap data","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string"},"total":{"type":"integer","description":"Số DVHC có data"},"data":{"type":"array","items":{"$ref":"#/components/schemas/HeatmapEntry"}},"stats":{"$ref":"#/components/schemas/HeatmapStats"},"generated_at":{"type":"string","format":"date-time"}}}}}}}}},"/dau-thau/scope":{"get":{"summary":"Drill-down gói thầu theo phạm vi đặc biệt","description":"List gói thầu thuộc 3 phạm vi (toàn quốc/đa tỉnh/nước ngoài) — provCode 3-digit ngoài 34 ĐVHC. Pagination 20/trang max 100. Phase A.5 sub-step 22/5/2026.","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["national","multi","foreign"]}},{"name":"period","in":"query","schema":{"type":"string","enum":["12m","all"],"default":"12m"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Scope packages list + aggregate value","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"period":{"type":"string"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalValueVnd":{"type":"integer"},"averageValueVnd":{"type":"integer"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/ScopePackage"}},"generated_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"valid":{"type":"array","items":{"type":"string"}}}}}}}}}},"/theses/search":{"get":{"summary":"Search academic theses","description":"Search MA/PhD theses harvested via OAI-PMH from 18 university repositories (9 VN + 9 international: HAL France, EThOS UK, MIT, Columbia, Stanford, Oxford, Cambridge, Tsinghua, NUS).","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text search (Vietnamese or English)"},{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"type","in":"query","schema":{"type":"string","enum":["Thesis","Master's Thesis","Doctoral Thesis","Article","Working Paper"]}},{"name":"source","in":"query","schema":{"type":"string"},"description":"Source slug (e.g. 01-VNU-HN, HAL-FR)"},{"name":"country","in":"query","schema":{"type":"string","enum":["VN","FR","UK","US","CN","SG"]}},{"name":"lang","in":"query","schema":{"type":"string"},"description":"ISO 639-1"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Theses search results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/ThesisHit"}}}}}}}}}}},"components":{"schemas":{"ServiceInfo":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"},"license":{"type":"string"},"contact":{"type":"string"},"cors":{"type":"string"},"rate_limit":{"type":"string"},"endpoints":{"type":"object","additionalProperties":{"type":"string"}}}},"VbplHit":{"type":"object","properties":{"id":{"type":"string"},"soHieu":{"type":"string"},"loai":{"type":"string"},"ngayBanHanh":{"type":"string","format":"date"},"nam":{"type":"integer"},"linhVuc":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"VbplDoc":{"allOf":[{"$ref":"#/components/schemas/VbplHit"},{"type":"object","properties":{"content":{"type":"string","description":"Fulltext (max 50K chars)"},"hasFulltext":{"type":"boolean"},"capBanHanh":{"type":"string"},"capBanHanhTen":{"type":"string"},"pdfUrl":{"type":"string","format":"uri"},"pdfHash":{"type":"string","description":"SHA-256 hex (64 chars)"},"tags":{"type":"array","items":{"type":"string"},"maxItems":10},"titleEn":{"type":"string"},"titleZh":{"type":"string"},"titleJa":{"type":"string"},"titleKo":{"type":"string"},"titleFr":{"type":"string"},"titleRu":{"type":"string"},"titleEs":{"type":"string"}}}]},"ThesisHit":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"titleEn":{"type":"string"},"creators":{"type":"string"},"date":{"type":"string"},"year":{"type":"integer"},"type":{"type":"string"},"subject":{"type":"string"},"lang":{"type":"string"},"source":{"type":"string"},"sourceSlug":{"type":"string"},"country":{"type":"string"},"handle":{"type":"string"},"pdfUrl":{"type":"string","format":"uri"}}},"EffectEdge":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"string","description":"Source VBPL id"},"to":{"type":"string","description":"Target VBPL id"},"type":{"type":"string","enum":["thay_the","bai_bo","sua_doi","bo_sung","hop_nhat","dinh_chinh"]},"refLoai":{"type":"string"},"refSo":{"type":"string"},"createdAt":{"type":"integer"},"source":{"type":"string","enum":["auto","manual"]}}},"HeatmapEntry":{"type":"object","properties":{"code":{"type":"string","description":"2-digit GSO hoặc 3-digit single-province"},"name":{"type":"string"},"slug":{"type":"string"},"vung":{"type":"string"},"count":{"type":"integer"}}},"HeatmapStats":{"type":"object","properties":{"nationalCount":{"type":"integer","description":"Gói \"Toàn quốc\" (provCode 824)"},"multiProvinceCount":{"type":"integer","description":"Gói đa tỉnh (12 codes 3-digit)"},"foreignCount":{"type":"integer","description":"Gói ngoài lãnh thổ VN (provCode 825)"},"unmappedCount":{"type":"integer","description":"Defensive — 3-digit chưa map"}}},"ScopePackage":{"type":"object","properties":{"id":{"type":"string"},"notifyNo":{"type":"string"},"bidName":{"type":"string"},"investorName":{"type":"string"},"bidPrice":{"type":"integer"},"publicDate":{"type":"string","format":"date-time"},"publicDateTs":{"type":"integer"},"locations":{"type":"string"},"bidForm":{"type":"string"},"status":{"type":"string"},"provCode":{"type":"string"}}}}},"externalDocs":{"description":"Full documentation","url":"https://vietlex.vn/cho-ai/api"},"tags":[{"name":"search","description":"Full-text search"},{"name":"document","description":"Single document"},{"name":"citator","description":"Legal relationships"},{"name":"bulk","description":"Bulk export"},{"name":"dau-thau","description":"Đấu thầu mua sắm công analytics"},{"name":"theses","description":"Academic theses harvested OAI-PMH"}]}