{"openapi":"3.0.3","info":{"title":"MPBxChange API","version":"1.0.0","description":"Cross-border B2B procurement platform anchored on Thailand. Per-vertical trust surfaces (PCB · Semi · Solar · HVAC · EVB · DC · Auto · Med · Mach). RLS-enforced multi-tenancy on Supabase.","contact":{"name":"MPBxChange Engineering","email":"api@mpbxchange.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://mpbxchange.com","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase session JWT · obtained via /api/auth/login"}},"schemas":{"ApiSuccess":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"description":"Response payload · shape varies per endpoint"}}},"ApiError":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Stable machine-readable code · e.g. mime_mismatch, virus_detected"}}},"TariffScenario":{"type":"object","properties":{"origin_country":{"type":"string","example":"TH"},"mfn_rate":{"type":"number","example":0},"preferential_rate":{"type":"number","nullable":true},"additional_duty_rate":{"type":"number","example":0.25,"description":"Section 301 or similar"},"effective_rate":{"type":"number"},"landed_cost_usd":{"type":"number"},"savings_vs_current_usd":{"type":"number"}}},"RiskScore":{"type":"object","properties":{"composite_score":{"type":"integer","minimum":0,"maximum":100},"band":{"type":"string","enum":["green","amber","red","black"]},"components":{"type":"object","properties":{"drift_score":{"type":"integer"},"counsel_score":{"type":"integer"},"violations_score":{"type":"integer"},"sanctions_score":{"type":"integer"},"payment_score":{"type":"integer"},"concentration_score":{"type":"integer"}}},"top_signals":{"type":"array","items":{"type":"string"}}}},"HardenedUploadError":{"type":"object","properties":{"success":{"type":"boolean","const":false},"code":{"type":"string","enum":["too_large","mime_disallowed","mime_mismatch","extension_blocked","empty_file","filename_invalid","magic_unknown","virus_detected"]},"error":{"type":"string"},"virus_signature":{"type":"string","nullable":true}}}}},"paths":{"/api/dashboard/executive":{"get":{"summary":"Executive cockpit aggregator","description":"Returns the full executive dashboard payload: decision queue, algo health, 6 hero rows, 4 mini-panels, activity feed. Cached 30 s per org_id. Role-gated: owner, admin, or system admin.","tags":["Dashboards"],"responses":{"200":{"description":"Cockpit payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Role not in cockpit access matrix"}}}},"/api/dashboard/procurement":{"get":{"summary":"Procurement manager cockpit","description":"Same shape as executive but pool-filtered to the org's suppliers + RFQs + corridors.","tags":["Dashboards"],"responses":{"200":{"description":"Pool-filtered payload"},"401":{},"403":{}}}},"/api/dashboard/finance":{"get":{"summary":"CFO finance cockpit","description":"4 rows: FX exposure, trade-finance fit, escrow drift, CBAM forecast.","tags":["Dashboards"],"responses":{"200":{"description":"CFO payload"},"401":{},"403":{}}}},"/api/arbitrage/tariff-optimize":{"post":{"summary":"Compute tariff arbitrage scenarios","description":"Compares landed cost across origin countries for the same HS-6 product. Returns ranked alternatives with savings vs current.","tags":["Algorithms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hs_code_6","destination_country","current_origin_country","total_value_usd"],"properties":{"hs_code_6":{"type":"string","pattern":"^\\d{6}$","example":"853400"},"destination_country":{"type":"string","minLength":2,"maxLength":2,"example":"US"},"current_origin_country":{"type":"string","minLength":2,"maxLength":2,"example":"CN"},"total_value_usd":{"type":"number","minimum":1,"example":250000},"candidate_origins":{"type":"array","items":{"type":"string"},"example":["TH","VN","KR"]},"contract_id":{"type":"string","format":"uuid","nullable":true},"persist":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Ranked scenarios","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"current_scenario":{"$ref":"#/components/schemas/TariffScenario"},"alternative_scenarios":{"type":"array","items":{"$ref":"#/components/schemas/TariffScenario"}},"savings_usd":{"type":"number"},"savings_pct":{"type":"number"}}}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/api/risk/compute":{"post":{"summary":"Compute predictive risk score","description":"6-signal composite (drift + counsel + violations + sanctions + payment + concentration) for one supplier or all suppliers (admin only).","tags":["Algorithms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["supplier_user_id"],"properties":{"supplier_user_id":{"type":"string","format":"uuid"}}},{"type":"object","required":["all"],"properties":{"all":{"type":"boolean","const":true}}}]}}}},"responses":{"200":{"description":"Score persisted + returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskScore"}}}},"403":{"description":"Bulk path requires admin"}}}},"/api/matchmaker/run":{"post":{"summary":"Rank suppliers for an RFQ","description":"AI Holistic Matchmaker: 5-signal ranking (spec fit + cert stack + CBAM + lead time + capacity) × risk band modifier.","tags":["Algorithms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listing_id"],"properties":{"listing_id":{"type":"string","format":"uuid"},"top_n":{"type":"integer","minimum":1,"maximum":50,"default":10}}}}}},"responses":{"200":{"description":"Ranked matches with reasons + blockers"},"403":{}}}},"/api/sanctions/sweep":{"post":{"summary":"Screen suppliers against sanctions lists","description":"Admin-only. Matches every supplier company name against OFAC + EU CFSP + UN 1267 + UK HMT.","tags":["Admin"],"responses":{"200":{"description":"Sweep complete · hits persisted"},"403":{"description":"Admin only"}}}},"/api/sanctions/list-refresh":{"post":{"summary":"Fetch + upsert sanctions list entries","description":"Admin-only. Downloads from source URLs (OFAC SDN CSV, EU CFSP CSV, UN XML, UK HMT CSV) and upserts entries.","tags":["Admin"],"responses":{"200":{"description":"List entries upserted"},"403":{"description":"Admin only"}}}},"/api/storage/sign":{"get":{"summary":"Issue short-lived signed URL for a private storage object","description":"Auth-gated. RLS checks that caller owns the path (path starts with their user_id, OR they're party-to-contract for contracts bucket, OR admin). Returns 5-min signed URL.","tags":["Storage"],"parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string","enum":["kyc-documents","corporate-contracts","datasheets","evidence-bundles","signed-contracts","admin-directory"]}},{"name":"path","in":"query","required":true,"schema":{"type":"string"}},{"name":"ttl","in":"query","required":false,"schema":{"type":"integer","default":300,"maximum":3600}}],"responses":{"200":{"description":"Signed URL + expiry"},"401":{"description":"Unauthorized"},"403":{"description":"Caller is not authorized for this bucket+path"}}}},"/api/profile/kyc":{"post":{"summary":"Upload a KYC document","description":"Multipart upload with hardenUpload: filename sanitize, MIME allowlist (PDF/JPG/PNG/WebP), magic-byte sniff, extension blocklist, SHA-256, virus scan (when VIRUS_SCANNER configured), EXIF strip for images.","tags":["Profile"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","doc_type"],"properties":{"file":{"type":"string","format":"binary"},"doc_type":{"type":"string","enum":["company_cert","vat_cert","director_id","factory_license"]}}}}}},"responses":{"201":{"description":"KYC document persisted"},"400":{"description":"Hardened upload rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardenedUploadError"}}}},"413":{"description":"File too large"},"415":{"description":"MIME disallowed"},"422":{"description":"Virus detected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardenedUploadError"}}}},"429":{"description":"Rate limit · 10/hour per IP"}}}}}}