{"components":{"schemas":{"BillingVerificationError":{"description":"Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After.","properties":{"code":{"description":"Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.","enum":["renewal_verification_pending","renewal_verification_failed","entitlement_verification_unavailable"],"type":"string"},"error":{"description":"Human-readable billing-verification failure reason.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.","format":"int32","type":"integer"}},"required":["error","code"],"type":"object"},"BypassCorridorOption":{"description":"BypassCorridorOption is a single enriched bypass corridor for the Route Explorer UI.\n Includes coordinate endpoints so the client can call MapContainer.setBypassRoutes\n directly without any client-side geometry lookup.","properties":{"addedCostMultiplier":{"format":"double","type":"number"},"addedTransitDays":{"format":"int32","type":"integer"},"fromPort":{"$ref":"#/components/schemas/GeoPoint"},"id":{"type":"string"},"name":{"type":"string"},"status":{"description":"Status of a bypass corridor for UI labeling. \"active\" means usable today;\n \"proposed\" means documented but not yet built/operational; \"unavailable\"\n means blockaded or otherwise blocked from use.","enum":["CORRIDOR_STATUS_UNSPECIFIED","CORRIDOR_STATUS_ACTIVE","CORRIDOR_STATUS_PROPOSED","CORRIDOR_STATUS_UNAVAILABLE"],"type":"string"},"toPort":{"$ref":"#/components/schemas/GeoPoint"},"type":{"type":"string"},"warRiskTier":{"type":"string"}},"type":"object"},"BypassOption":{"properties":{"activationThreshold":{"type":"string"},"addedCostMultiplier":{"format":"double","type":"number"},"addedTransitDays":{"format":"int32","type":"integer"},"bypassWarRiskTier":{"description":"War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat\n classification. Free field (no PRO gate).","enum":["WAR_RISK_TIER_UNSPECIFIED","WAR_RISK_TIER_NORMAL","WAR_RISK_TIER_ELEVATED","WAR_RISK_TIER_HIGH","WAR_RISK_TIER_CRITICAL","WAR_RISK_TIER_WAR_ZONE"],"type":"string"},"capacityConstraintTonnage":{"format":"int64","type":"string"},"id":{"type":"string"},"liveScore":{"format":"double","type":"number"},"name":{"type":"string"},"notes":{"type":"string"},"suitableCargoTypes":{"items":{"type":"string"},"type":"array"},"type":{"type":"string"},"waypointChokepointIds":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ChinaCorridorCondition":{"properties":{"availability":{"enum":["available","partial","stale","unavailable"],"type":"string"},"family":{"enum":["port","aviation","hazard","power_energy","strategic_industry","trade"],"type":"string"},"provenance":{"oneOf":[{"$ref":"#/components/schemas/ChinaCorridorProvenance"},{"type":"null"}]},"providerId":{"type":"string"},"reason":{"type":["string","null"]},"sourceSignals":{"items":{"properties":{"availability":{"enum":["available","stale","unavailable"],"type":"string"},"contentFreshness":{"enum":["current","stale","unavailable","partial","timestamp_unknown"],"type":"string"},"corridorIds":{"items":{"enum":["china-yangtze-river-delta","china-greater-bay-area","china-bohai-rim","china-western-land-sea-corridor"],"type":"string"},"type":"array"},"family":{"enum":["port","aviation","hazard","power_energy","strategic_industry","trade"],"type":"string"},"id":{"type":"string"},"metrics":{"additionalProperties":{"type":["string","number","boolean","null"]},"type":"object"},"observationTime":{"type":["string","null"]},"observationTimePrecision":{"enum":["instant","day","month","year","unknown"],"type":"string"},"publisher":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"enum":["official","market","independent","derived","unknown"],"type":"string"}},"required":["id","name","type"],"type":"object"},"releaseTime":{"type":["string","null"]},"releaseTimePrecision":{"enum":["instant","day","month","year","unknown"],"type":"string"},"retrievalTime":{"type":["string","null"]},"retrievalTimePrecision":{"enum":["instant","day","month","year","unknown"],"type":"string"},"revision":{"oneOf":[{"properties":{"sequence":{"type":"number"},"state":{"enum":["original","revised","corrected"],"type":"string"},"vintageId":{"type":"string"}},"required":["vintageId","sequence","state"],"type":"object"},{"type":"null"}]},"selectorId":{"type":"string"},"sourceScope":{"enum":["node","regional","national"],"type":"string"},"sourceUrl":{"format":"uri","type":["string","null"]},"summary":{"type":"string"},"transportFreshness":{"enum":["fresh","stale","missing","error"],"type":"string"}},"required":["id","family","selectorId","availability","publisher","sourceUrl","sourceScope","observationTime","observationTimePrecision","releaseTime","releaseTimePrecision","retrievalTime","retrievalTimePrecision","revision","transportFreshness","contentFreshness","summary","metrics"],"type":"object"},"type":"array"}},"required":["family","providerId","availability","reason","sourceSignals","provenance"],"type":"object"},"ChinaCorridorControlTower":{"properties":{"availability":{"enum":["available","partial","stale","unavailable"],"type":"string"},"boundary":{"items":{"properties":{"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"}},"required":["lat","lon"],"type":"object"},"type":"array"},"conditions":{"items":{"$ref":"#/components/schemas/ChinaCorridorCondition"},"type":"array"},"description":{"type":"string"},"id":{"enum":["china-yangtze-river-delta","china-greater-bay-area","china-bohai-rim","china-western-land-sea-corridor"],"type":"string"},"name":{"type":"string"},"nodes":{"items":{"properties":{"id":{"type":"string"},"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"},"name":{"type":"string"},"sourceOwner":{"type":"string"},"sourceSelector":{"properties":{"family":{"enum":["port","aviation","hazard","power_energy","strategic_industry","trade"],"type":"string"},"id":{"type":"string"}},"required":["family","id"],"type":"object"},"type":{"enum":["port","airport","crossing","industrial"],"type":"string"}},"required":["id","name","type","lat","lon","sourceOwner"],"type":"object"},"type":"array"}},"required":["id","name","description","boundary","nodes","availability","conditions"],"type":"object"},"ChinaCorridorControlTowerResponse":{"description":"Canonical transparent China logistics corridor composition decoded from payloadJson.","properties":{"corridors":{"items":{"$ref":"#/components/schemas/ChinaCorridorControlTower"},"type":"array"},"generatedAt":{"format":"date-time","type":"string"}},"required":["generatedAt","corridors"],"type":"object"},"ChinaCorridorProvenance":{"description":"The #5581 decision-signal provenance envelope retained for the composed condition.","properties":{"claims":{"properties":{"classification_confidence":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"properties":{"method":{"minLength":1,"pattern":"\\S","type":"string"},"score":{"maximum":1,"minimum":0,"type":"number"}},"required":["score","method"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"content_freshness":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"state":{"enum":["current","stale"]}},"required":["contentAsOf"]},{"not":{"required":["contentAsOf"]},"properties":{"state":{"const":"timestamp_unknown"}}},{"properties":{"state":{"enum":["unavailable","partial"]}}}],"properties":{"assessedAt":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},"contentAsOf":{"oneOf":[{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"},{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"},{"pattern":"^\\d{4}$","type":"string"}]},"state":{"enum":["current","stale","unavailable","partial","timestamp_unknown"],"type":"string"}},"required":["state","assessedAt"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"corroboration":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"sourceSignalIds":{"items":{"minLength":1,"pattern":"\\S","type":"string"},"maxItems":1,"minItems":1,"type":"array","uniqueItems":true},"state":{"const":"single_source"}}},{"properties":{"sourceSignalIds":{"items":{"minLength":1,"pattern":"\\S","type":"string"},"minItems":2,"type":"array","uniqueItems":true},"state":{"enum":["multi_source","independently_corroborated","contradicted"]}}}],"properties":{"sourceSignalIds":{"items":{"minLength":1,"pattern":"\\S","type":"string"},"type":"array","uniqueItems":true},"state":{"enum":["single_source","multi_source","independently_corroborated","contradicted"],"type":"string"}},"required":["state","sourceSignalIds"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"derivation":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"properties":{"computedAt":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},"inputSignalIds":{"items":{"minLength":1,"pattern":"\\S","type":"string"},"minItems":1,"type":"array","uniqueItems":true},"methodId":{"minLength":1,"pattern":"\\S","type":"string"},"methodVersion":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["methodId","methodVersion","computedAt","inputSignalIds"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"effective_time":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"precision":{"const":"instant"},"value":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"}}},{"properties":{"precision":{"const":"day"},"value":{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"}}},{"properties":{"precision":{"const":"month"},"value":{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"}}},{"properties":{"precision":{"const":"year"},"value":{"pattern":"^\\d{4}$","type":"string"}}}],"properties":{"precision":{"enum":["instant","day","month","year"],"type":"string"},"role":{"const":"effective","type":"string"},"value":{"oneOf":[{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"},{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"},{"pattern":"^\\d{4}$","type":"string"}]}},"required":["role","value","precision"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"extraction_confidence":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"properties":{"method":{"minLength":1,"pattern":"\\S","type":"string"},"score":{"maximum":1,"minimum":0,"type":"number"}},"required":["score","method"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"observation_time":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"precision":{"const":"instant"},"value":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"}}},{"properties":{"precision":{"const":"day"},"value":{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"}}},{"properties":{"precision":{"const":"month"},"value":{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"}}},{"properties":{"precision":{"const":"year"},"value":{"pattern":"^\\d{4}$","type":"string"}}}],"properties":{"precision":{"enum":["instant","day","month","year"],"type":"string"},"role":{"const":"observation","type":"string"},"value":{"oneOf":[{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"},{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"},{"pattern":"^\\d{4}$","type":"string"}]}},"required":["role","value","precision"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"original_language":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"original_reference":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"properties":{"contentHash":{"pattern":"^sha256:[a-f0-9]{64}$","type":"string"},"id":{"minLength":1,"pattern":"\\S","type":"string"},"kind":{"enum":["document","text","observation","event","dataset"],"type":"string"}},"required":["kind","id"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"publication_time":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"precision":{"const":"instant"},"value":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"}}},{"properties":{"precision":{"const":"day"},"value":{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"}}},{"properties":{"precision":{"const":"month"},"value":{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"}}},{"properties":{"precision":{"const":"year"},"value":{"pattern":"^\\d{4}$","type":"string"}}}],"properties":{"precision":{"enum":["instant","day","month","year"],"type":"string"},"role":{"const":"publication","type":"string"},"value":{"oneOf":[{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"},{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"},{"pattern":"^\\d{4}$","type":"string"}]}},"required":["role","value","precision"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"publisher":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"registryReference":{"type":"null"},"type":{"const":"derived_output"}}},{"properties":{"registryReference":{"additionalProperties":false,"properties":{"propagandaRisk":{"minLength":1,"pattern":"\\S","type":"string"},"sourceName":{"minLength":1,"pattern":"\\S","type":"string"},"sourceType":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["sourceName","sourceType","propagandaRisk"],"type":"object"},"type":{"enum":["official_government","state_controlled_media","official_exchange","independent_observation","independent_media","wire_service","market_publisher","unknown"]}}}],"properties":{"id":{"minLength":1,"pattern":"\\S","type":"string"},"name":{"minLength":1,"pattern":"\\S","type":"string"},"registryReference":{"oneOf":[{"additionalProperties":false,"properties":{"propagandaRisk":{"minLength":1,"pattern":"\\S","type":"string"},"sourceName":{"minLength":1,"pattern":"\\S","type":"string"},"sourceType":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["sourceName","sourceType","propagandaRisk"],"type":"object"},{"type":"null"}]},"type":{"enum":["official_government","state_controlled_media","official_exchange","independent_observation","independent_media","wire_service","market_publisher","derived_output","unknown"],"type":"string"}},"required":["id","name","type","registryReference"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"retrieval_time":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"precision":{"const":"instant"},"value":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"}}},{"properties":{"precision":{"const":"day"},"value":{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"}}},{"properties":{"precision":{"const":"month"},"value":{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"}}},{"properties":{"precision":{"const":"year"},"value":{"pattern":"^\\d{4}$","type":"string"}}}],"properties":{"precision":{"enum":["instant","day","month","year"],"type":"string"},"role":{"const":"retrieval","type":"string"},"value":{"oneOf":[{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},{"format":"date","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))$","type":"string"},{"pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$","type":"string"},{"pattern":"^\\d{4}$","type":"string"}]}},"required":["role","value","precision"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"revision":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"sequence":{"const":1},"state":{"enum":["preliminary","original"]}}},{"properties":{"sequence":{"minimum":2,"type":"integer"},"state":{"enum":["revised","corrected"]}}}],"properties":{"sequence":{"minimum":1,"type":"integer"},"state":{"enum":["preliminary","original","revised","corrected"],"type":"string"},"vintageId":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["vintageId","sequence","state"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"source_url":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"format":"uri","pattern":"^https://(?![^/?#]*@)[^/?#\\s]+(?:[/?#]\\S*)?$","type":"string"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"supersession":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"not":{"anyOf":[{"required":["relatedSignalId"]},{"required":["reason"]}]},"properties":{"state":{"const":"current"}}},{"properties":{"state":{"enum":["corrected","superseded"]}},"required":["relatedSignalId"]},{"properties":{"state":{"const":"cancelled"}},"required":["reason"]}],"properties":{"reason":{"minLength":1,"pattern":"\\S","type":"string"},"relatedSignalId":{"minLength":1,"pattern":"\\S","type":"string"},"state":{"enum":["current","corrected","cancelled","superseded"],"type":"string"}},"required":["state"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"translation":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"oneOf":[{"properties":{"state":{"enum":["machine_assisted","human_reviewed"]}},"required":["targetLanguage"]},{"not":{"required":["targetLanguage"]},"properties":{"state":{"enum":["unavailable","not_translated"]}}}],"properties":{"state":{"enum":["unavailable","not_translated","machine_assisted","human_reviewed"],"type":"string"},"targetLanguage":{"minLength":1,"pattern":"\\S","type":"string"}},"required":["state"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]},"transport_freshness":{"oneOf":[{"additionalProperties":false,"properties":{"status":{"const":"known","type":"string"},"value":{"additionalProperties":false,"properties":{"assessedAt":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},"lastSuccessAt":{"format":"date-time","pattern":"^(?:(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:\\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:00|0[48]|[2468][048]|[13579][26])00)-02-29))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$","type":"string"},"state":{"enum":["fresh","stale","missing","error"],"type":"string"}},"required":["state","assessedAt"],"type":"object"}},"required":["status","value"],"type":"object"},{"$ref":"#/components/schemas/ChinaCorridorProvenanceClaim"}]}},"required":["publisher","source_url","original_reference","original_language","translation","observation_time","effective_time","publication_time","retrieval_time","revision","supersession","extraction_confidence","classification_confidence","corroboration","transport_freshness","content_freshness","derivation"],"type":"object"},"contractVersion":{"const":"decision-signal-provenance/v1","type":"string"},"familyId":{"const":"composed_corridor_condition","type":"string"},"signalId":{"type":"string"}},"required":["contractVersion","signalId","familyId","claims"],"type":"object"},"ChinaCorridorProvenanceClaim":{"additionalProperties":false,"properties":{"reason":{"type":"string"},"status":{"enum":["unknown","not_applicable"],"type":"string"}},"required":["status","reason"],"type":"object"},"ChokepointDependency":{"properties":{"band":{"description":"Score band: low, moderate, high, or critical; empty when the score is absent.","type":"string"},"commodity":{"description":"Human-readable commodity name.","type":"string"},"commodityId":{"description":"Stable reviewed commodity mapping identifier.","type":"string"},"countryIso2":{"description":"ISO 3166-1 alpha-2 code for the exposed country.","type":"string"},"countryName":{"description":"English display name for the exposed country.","type":"string"},"methodologyVersion":{"description":"Version of the scoring methodology that produced this dependency.","type":"string"},"reasons":{"items":{"description":"Machine-readable explanations for an insufficient or stale state.","type":"string"},"type":"array"},"score":{"description":"Commodity vulnerability score from 0 to 100; absent when evidence is insufficient.","format":"double","type":"number"},"state":{"description":"Evidence state: ok, insufficient_data, or stale_input.","type":"string"},"transitShare":{"description":"Share of the country's mapped commodity exposure using this chokepoint, from 0 to 1.","format":"double","type":"number"},"weightedTransitShare":{"description":"Disruption-adjusted transit share, from 0 to 1.","format":"double","type":"number"}},"type":"object"},"ChokepointExposureEntry":{"description":"ChokepointExposureEntry holds per-chokepoint exposure data for a country.","properties":{"chokepointId":{"description":"Canonical chokepoint ID from the chokepoint registry.","type":"string"},"chokepointName":{"description":"Human-readable chokepoint name.","type":"string"},"coastSide":{"description":"Which ocean/basin side the country's ports face (atlantic, pacific, indian, med, multi, landlocked).","type":"string"},"exposureScore":{"description":"Exposure score 0-100; higher = more dependent on this chokepoint. With\n bilateral product data, sums routeCoverage * exporterShare * productWeight\n * 100 across matching products; fallback uses route overlap only. HS2 27\n supported energy chokepoints receive a 1.5x boost capped at 100.","format":"double","type":"number"},"shockSupported":{"description":"Whether the shock model is supported for this chokepoint + hs2 combination.","type":"boolean"}},"type":"object"},"ChokepointExposureSummary":{"properties":{"chokepointId":{"type":"string"},"chokepointName":{"type":"string"},"exposurePct":{"format":"int32","type":"integer"}},"type":"object"},"ChokepointInfo":{"properties":{"activeWarnings":{"format":"int32","type":"integer"},"affectedRoutes":{"items":{"type":"string"},"type":"array"},"aisDisruptions":{"format":"int32","type":"integer"},"aisSnapshotAvailable":{"description":"True when the AIS snapshot source returned a valid response; owns\n ais_disruptions and congestion_level. A missing value fails closed.","type":"boolean"},"congestionLevel":{"description":"AIS-derived congestion level. \"normal\" is an observed AIS level, not a\n default. Empty when ais_snapshot_available is false.","type":"string"},"description":{"type":"string"},"directionalDwt":{"deprecated":true,"items":{"$ref":"#/components/schemas/DirectionalDwt"},"type":"array"},"directions":{"items":{"type":"string"},"type":"array"},"disruptionScore":{"format":"int32","type":"integer"},"flowEstimate":{"$ref":"#/components/schemas/FlowEstimate"},"id":{"type":"string"},"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"},"name":{"type":"string"},"navigationalWarningsAvailable":{"description":"True when the NGA navigational-warning source returned a valid response,\n empty list included; a missing value fails closed.","type":"boolean"},"status":{"description":"Traffic-light score badge: green (\u003c20), yellow (20-49), or red (\u003e=50).\n Not an operational closure taxonomy.","type":"string"},"transitSummary":{"$ref":"#/components/schemas/TransitSummary"},"warRiskTier":{"description":"War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat\n classification. Free field (no PRO gate).","enum":["WAR_RISK_TIER_UNSPECIFIED","WAR_RISK_TIER_NORMAL","WAR_RISK_TIER_ELEVATED","WAR_RISK_TIER_HIGH","WAR_RISK_TIER_CRITICAL","WAR_RISK_TIER_WAR_ZONE"],"type":"string"}},"type":"object"},"CommodityVulnerability":{"properties":{"band":{"description":"Score band: low, moderate, high, or critical; empty when the score is absent.","type":"string"},"commodity":{"description":"Human-readable commodity name.","type":"string"},"commodityId":{"description":"Stable reviewed commodity mapping identifier.","type":"string"},"components":{"$ref":"#/components/schemas/VulnerabilityComponents"},"countryIso2":{"description":"ISO 3166-1 alpha-2 code for the scored country.","type":"string"},"countryName":{"description":"English display name for the scored country.","type":"string"},"coverage":{"items":{"description":"Source coverage labels that contributed to this score.","type":"string"},"type":"array"},"methodologyVersion":{"description":"Version of the scoring methodology that produced this row.","type":"string"},"reasons":{"items":{"description":"Machine-readable explanations for an insufficient or stale state.","type":"string"},"type":"array"},"score":{"description":"Vulnerability score from 0 to 100; absent when evidence is insufficient.","format":"double","type":"number"},"state":{"description":"Evidence state: ok, insufficient_data, or stale_input.","type":"string"}},"type":"object"},"CountryProduct":{"properties":{"denominatorBasis":{"description":"Share denominator: \"reported_world\" (the provider's World import total for\n this heading and year) or \"observed_partners\" (the sum of observed partner\n values). Absent on legacy rows, whose denominator is unverified.","type":"string"},"description":{"type":"string"},"fetchedAt":{"description":"ISO timestamp this heading alone was fetched at. Present only on a heading\n recovered on demand, whose fetch time differs from the payload's.","type":"string"},"hs4":{"type":"string"},"omittedPartnerCount":{"description":"Origins ranked below the ones shown. Absent under \"leading_5\", where the\n omitted set is not measured.","format":"int32","type":"integer"},"omittedPartnerShare":{"description":"Combined share of the omitted origins, 0-1. Absent under \"leading_5\".","format":"double","type":"number"},"partnerBasis":{"description":"How top_exporters was selected: \"share_threshold\" (every origin at or above\n 1% of the denominator, padded to 5 and capped at 25; served only for the\n requested hs4) or \"leading_5\" (the canonical leading five). Always present\n on a served row.","type":"string"},"topExporters":{"items":{"$ref":"#/components/schemas/ProductExporter"},"type":"array"},"totalValue":{"format":"double","type":"number"},"year":{"format":"int32","type":"integer"}},"type":"object"},"CountryProductEvidence":{"description":"Cache evidence for the returned products. Missing data is not zero trade.","properties":{"lastAttemptAt":{"description":"ISO timestamp of the last refresh attempt; empty when unknown.","type":"string"},"lastAttemptState":{"description":"Result of the last refresh attempt: \"observed\", \"no_records\",\n \"legacy_no_records\", \"unsupported_reporter\", \"rate_limited\", \"unavailable\",\n \"malformed\", \"incomplete\", \"regression_rejected\", \"cache_unavailable\",\n \"cache_write_failed\", \"busy\", \"not_attempted\", \"preserved_reason_unknown\"\n or \"unknown\".","type":"string"},"missingHs4s":{"items":{"description":"Catalogue headings with no usable product row.","type":"string"},"type":"array"},"recoveredHs4s":{"items":{"description":"Headings served from an on-demand single-heading fetch rather than the\n stored payload. Empty when every row came from the stored payload.","type":"string"},"type":"array"},"requestedHs4s":{"items":{"description":"HS4 headings the producing request asked for; empty when unknown (legacy cache).","type":"string"},"type":"array"},"source":{"description":"Retrieval route of the cached payload; with no payload, the single-heading\n recovery route when a heading was recovered, else a legacy-cache label.","type":"string"},"state":{"description":"Reader state: \"observed\", \"partial\" (some catalogue headings absent, which\n includes a response holding only a heading recovered on demand),\n \"stale_preserved\" (older than 35 days; last-good data kept),\n \"cache_unavailable\", or, when no payload exists and nothing was recovered,\n the last attempt state (see last_attempt_state) or \"missing\".","type":"string"},"worldExportsFetchedAt":{"description":"ISO timestamp of the world-export snapshot the scale figures came from.\n Absent when no snapshot is cached or no hs4 was requested, in which case no\n row carries a scale.","type":"string"}},"type":"object"},"CriticalMineral":{"properties":{"globalProduction":{"format":"double","type":"number"},"hhi":{"format":"double","type":"number"},"mineral":{"type":"string"},"riskRating":{"type":"string"},"topProducers":{"items":{"$ref":"#/components/schemas/MineralProducer"},"type":"array"},"unit":{"type":"string"}},"type":"object"},"DirectionalDwt":{"properties":{"direction":{"type":"string"},"dwtThousandTonnes":{"format":"double","type":"number"},"wowChangePct":{"format":"double","type":"number"}},"type":"object"},"EnergyDisruptionEntry":{"properties":{"assetId":{"description":"Maps to a pipeline or storage-facility id seeded elsewhere.","type":"string"},"assetType":{"description":"One of: \"pipeline\" | \"storage\"","type":"string"},"capacityOfflineBcmYr":{"description":"Headline-offline capacity (contextual — 0 when not applicable).","format":"double","type":"number"},"capacityOfflineMbd":{"format":"double","type":"number"},"causeChain":{"items":{"description":"Contributing causes, primary-first.","type":"string"},"type":"array"},"classifierConfidence":{"format":"double","type":"number"},"classifierVersion":{"type":"string"},"countries":{"items":{"description":"Countries touched by the referenced asset (pipeline: fromCountry +\n toCountry + transitCountries; storage: country). Denormalised at seed\n time so CountryDeepDivePanel can filter events without a second RPC.\n Always non-empty in well-formed payloads; empty only if the upstream\n asset was removed without an event update. Per plan §R/#5 decision B.","type":"string"},"type":"array"},"endAt":{"description":"Empty string when event is still ongoing.","type":"string"},"eventType":{"description":"One of: \"sabotage\" | \"sanction\" | \"maintenance\" | \"mechanical\" |\n         \"weather\" | \"commercial\" | \"war\" | \"other\"","type":"string"},"id":{"type":"string"},"lastEvidenceUpdate":{"type":"string"},"shortDescription":{"type":"string"},"sources":{"items":{"$ref":"#/components/schemas/EnergyDisruptionSource"},"type":"array"},"startAt":{"type":"string"}},"type":"object"},"EnergyDisruptionSource":{"properties":{"authority":{"type":"string"},"date":{"type":"string"},"sourceType":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"}},"type":"object"},"Error":{"description":"Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.","properties":{"message":{"description":"Error message (e.g., 'user not found', 'database connection failed')","type":"string"}},"type":"object"},"ExporterScale":{"description":"An origin's reported world exports of the same heading, so a shown share can\n be read against the supplier's total capacity rather than this importer alone.","properties":{"rank":{"description":"1-based position by value among the reporters that filed this heading for\n `year` (see reporter_count), not among every world exporter.","format":"int32","type":"integer"},"reporterCount":{"description":"Reporters ranked for this heading and year: rank is out of this many.","format":"int32","type":"integer"},"unrankedReporterCount":{"description":"Reporters whose newest filing for this heading predates `year` (late filers\n or lapsed exporters). They are left out of the ranking, so one that files\n later can move every rank below it. Absent on a snapshot written before the\n count was recorded.","format":"int32","type":"integer"},"worldExportsKg":{"description":"Reported world-export weight in kilograms. Absent when the origin reported\n no weight (the provider writes 0 for \"not reported\"), never 0 for absent.","format":"double","type":"number"},"worldExportsUsd":{"description":"Reported world exports of this heading by this origin, in USD.","format":"double","type":"number"},"year":{"description":"Trade observation year of the world-export figures, not the fetch year.\n Always equal to the row's year: a scale from another year is not attached.","format":"int32","type":"integer"}},"type":"object"},"FieldViolation":{"description":"FieldViolation describes a single validation error for a specific field.","properties":{"description":{"description":"Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')","type":"string"},"field":{"description":"The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')","type":"string"}},"required":["field","description"],"type":"object"},"FlowEstimate":{"properties":{"baselineMbd":{"description":"EIA 2023 annual reference level in million barrels/day for the mapped\n seven-item live-flow subset.","format":"double","type":"number"},"currentMbd":{"description":"Current estimated flow in million barrels/day. Computed as\n baseline_mbd * flow_ratio.","format":"double","type":"number"},"disrupted":{"description":"True when each of the latest 3 daily ratios is below 85% of the same\n rolling baseline window. Separate from the green/yellow/red status badge.","type":"boolean"},"flowRatio":{"description":"Latest 7-day PortWatch average divided by the preceding rolling baseline\n window of up to 90 days, clamped to 0.0-1.5.","format":"double","type":"number"},"hazardAlertLevel":{"description":"Nearest active GDACS hazard alert level within the configured radius:\n \"RED\", \"ORANGE\", or empty string when no nearby alert applies.","type":"string"},"hazardAlertName":{"description":"Name of the nearest active GDACS hazard event within the configured\n radius, or empty string when no nearby alert applies.","type":"string"},"latestDate":{"description":"Last PortWatch day behind flow_ratio, YYYY-MM-DD; may be empty.","type":"string"},"source":{"description":"Coverage basis behind a PortWatch-derived flow estimate: \"portwatch-dwt\"\n when the rolling baseline window has DWT-majority coverage, otherwise\n \"portwatch-counts\" for vessel-count coverage. FLOW_SOURCE_UNSPECIFIED means\n the cached estimate carried a basis this taxonomy does not list, which the\n endpoint reports rather than passing through undeclared.","enum":["FLOW_SOURCE_UNSPECIFIED","portwatch-dwt","portwatch-counts"],"type":"string"}},"type":"object"},"ForbiddenError":{"description":"Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.","properties":{"code":{"description":"Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).","enum":["subscription_lapsed"],"type":"string"},"currentTier":{"description":"Caller entitlement tier when known.","format":"int32","type":"integer"},"error":{"description":"Human-readable entitlement failure reason.","type":"string"},"planKey":{"description":"Caller plan key when known.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint.","format":"int32","type":"integer"}},"required":["error"],"type":"object"},"FuelShortageEntry":{"properties":{"causeChain":{"items":{"description":"Contributing root causes, ordered primary-first. Subset of:\n   \"upstream_refinery\" | \"logistics\" | \"policy\" | \"chokepoint\" |\n   \"sanction\" | \"war\" | \"import_cut\"","type":"string"},"type":"array"},"country":{"type":"string"},"evidence":{"$ref":"#/components/schemas/FuelShortageEvidence"},"firstSeen":{"type":"string"},"id":{"type":"string"},"impactTypes":{"items":{"description":"Observable consumer-facing impacts. Subset of:\n   \"stations_closed\" | \"rationing\" | \"flights_cancelled\" | \"import_cut\" | \"price_spike\"","type":"string"},"type":"array"},"lastConfirmed":{"type":"string"},"product":{"description":"One of: \"petrol\" | \"diesel\" | \"jet\" | \"heating_oil\"","type":"string"},"resolvedAt":{"description":"Empty string when not yet resolved.","type":"string"},"severity":{"description":"One of: \"confirmed\" | \"watch\"  (classifier output — not a client-side derivation)","type":"string"},"shortDescription":{"type":"string"}},"type":"object"},"FuelShortageEvidence":{"properties":{"classifierConfidence":{"format":"double","type":"number"},"classifierVersion":{"type":"string"},"evidenceSources":{"items":{"$ref":"#/components/schemas/FuelShortageEvidenceSource"},"type":"array"},"firstRegulatorConfirmation":{"description":"ISO date of the first regulator confirmation, if any. Empty when\n severity is \"watch\" on press-only signal.","type":"string"},"lastEvidenceUpdate":{"type":"string"}},"type":"object"},"FuelShortageEvidenceSource":{"properties":{"authority":{"type":"string"},"date":{"type":"string"},"sourceType":{"description":"One of: \"regulator\" | \"operator\" | \"press\" | \"ais-relay\" | \"satellite\"","type":"string"},"title":{"type":"string"},"url":{"type":"string"}},"type":"object"},"GatewayError":{"description":"Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.","properties":{"error":{"description":"Gateway error reason or structured gateway failure details.","oneOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]}},"required":["error"],"type":"object"},"GeoPoint":{"description":"GeoPoint is a [longitude, latitude] pair.","properties":{"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"}},"type":"object"},"GetBypassOptionsRequest":{"properties":{"cargoType":{"description":"container | tanker | bulk | roro  (default: \"container\")","type":"string"},"chokepointId":{"description":"Chokepoint identifier to evaluate for bypass options.","type":"string"},"closurePct":{"description":"0-100, percent of capacity blocked (default: 100)","format":"int32","type":"integer"}},"required":["chokepointId"],"type":"object"},"GetBypassOptionsResponse":{"properties":{"cargoType":{"type":"string"},"chokepointId":{"type":"string"},"closurePct":{"format":"int32","type":"integer"},"fetchedAt":{"type":"string"},"options":{"items":{"$ref":"#/components/schemas/BypassOption"},"type":"array"},"primaryChokepointWarRiskTier":{"description":"War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat\n classification. Free field (no PRO gate).","enum":["WAR_RISK_TIER_UNSPECIFIED","WAR_RISK_TIER_NORMAL","WAR_RISK_TIER_ELEVATED","WAR_RISK_TIER_HIGH","WAR_RISK_TIER_CRITICAL","WAR_RISK_TIER_WAR_ZONE"],"type":"string"}},"type":"object"},"GetChinaCorridorControlTowersRequest":{"type":"object"},"GetChinaCorridorControlTowersResponse":{"properties":{"generatedAt":{"type":"string"},"payloadJson":{"contentMediaType":"application/json","contentSchema":{"$ref":"#/components/schemas/ChinaCorridorControlTowerResponse"},"description":"Canonical JSON keeps the shared #5581 provenance envelope byte-for-byte\n equivalent across cache, API, UI, and later MCP adapters.","type":"string"},"upstreamUnavailable":{"description":"True only when every reviewed corridor is unavailable. Agents and API callers must treat true as upstream degradation, not as evidence that corridor conditions are normal or zero.","type":"boolean"}},"type":"object"},"GetChokepointDependenciesRequest":{"properties":{"chokepointId":{"description":"Stable chokepoint identifier, such as hormuz_strait or suez.","maxLength":80,"minLength":1,"pattern":"^[a-z0-9_\\-]+$","type":"string"},"pageSize":{"description":"Maximum dependencies to return; zero uses the server default and the maximum is 100.","format":"int32","maximum":100,"minimum":0,"type":"integer"}},"required":["chokepointId"],"type":"object"},"GetChokepointDependenciesResponse":{"properties":{"chokepoint":{"description":"Human-readable chokepoint name.","type":"string"},"chokepointId":{"description":"Stable identifier of the requested chokepoint.","type":"string"},"dependencies":{"items":{"$ref":"#/components/schemas/ChokepointDependency"},"type":"array"},"generatedAt":{"description":"ISO 8601 timestamp when the inverse index was generated.","type":"string"},"methodologyVersion":{"description":"Version of the scoring methodology used for every dependency.","type":"string"},"upstreamUnavailable":{"description":"True when the published inverse index could not be read.","type":"boolean"}},"type":"object"},"GetChokepointHistoryRequest":{"description":"GetChokepointHistory returns the transit-count history for a single\n chokepoint. Loaded lazily on card expand so the main chokepoint-status\n response can stay compact (no 180-day history per chokepoint).","properties":{"chokepointId":{"description":"Chokepoint identifier whose transit history should be returned.","type":"string"}},"required":["chokepointId"],"type":"object"},"GetChokepointHistoryResponse":{"properties":{"chokepointId":{"type":"string"},"fetchedAt":{"format":"int64","type":"string"},"history":{"items":{"$ref":"#/components/schemas/TransitDayCount"},"type":"array"}},"type":"object"},"GetChokepointStatusRequest":{"type":"object"},"GetChokepointStatusResponse":{"properties":{"chokepoints":{"items":{"$ref":"#/components/schemas/ChokepointInfo"},"type":"array"},"fetchedAt":{"description":"ISO-8601 time the status snapshot was fetched. Empty string with\n upstream_unavailable=true means the snapshot is unavailable/degraded.","type":"string"},"upstreamUnavailable":{"description":"True when upstream seed/relay data is unavailable or partial. When true, an\n empty chokepoints array is graceful degradation, not confirmed zero data.","type":"boolean"}},"type":"object"},"GetCountryChokepointIndexRequest":{"description":"GetCountryChokepointIndexRequest specifies the country and optional HS2 chapter.","properties":{"hs2":{"description":"HS2 chapter (2-digit string). Defaults to \"27\" (energy/mineral fuels) when absent.","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2 country code (uppercase).","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2"],"type":"object"},"GetCountryChokepointIndexResponse":{"description":"GetCountryChokepointIndexResponse returns exposure scores for all relevant chokepoints.","properties":{"exposures":{"items":{"$ref":"#/components/schemas/ChokepointExposureEntry"},"type":"array"},"fetchedAt":{"description":"ISO timestamp of when this data was last seeded.","type":"string"},"hs2":{"description":"HS2 chapter used for the computation.","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2 country code echoed from the request.","type":"string"},"primaryChokepointId":{"description":"Canonical ID of the chokepoint with the highest exposure score.","type":"string"},"vulnerabilityIndex":{"description":"Composite vulnerability index 0-100: top1 * 0.5 + top2 * 0.3 + top3 * 0.2.","format":"double","type":"number"}},"type":"object"},"GetCountryCostShockRequest":{"properties":{"chokepointId":{"description":"Chokepoint identifier to model as disrupted.","type":"string"},"hs2":{"description":"HS2 chapter (default: \"27\")","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2 country code for the importing country.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2","chokepointId"],"type":"object"},"GetCountryCostShockResponse":{"properties":{"chokepointId":{"type":"string"},"coverageDays":{"description":"Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors or net exporters)","format":"int32","type":"integer"},"fetchedAt":{"type":"string"},"hasEnergyModel":{"description":"Whether supply_deficit_pct and coverage_days are modelled (true) or unavailable (false)","type":"boolean"},"hs2":{"type":"string"},"iso2":{"type":"string"},"supplyDeficitPct":{"description":"Average refined-product supply deficit % under full closure at the pre-crisis Gulf crude share, after bypass rerouting for Hormuz when per-exporter shares exist (average over the products among Gasoline/Diesel/Jet fuel/LPG/Naphtha with recorded positive demand; HS 27 only)","format":"double","type":"number"},"unavailableReason":{"description":"Null/unavailable explanation for non-energy sectors","type":"string"},"warRiskPremiumBps":{"description":"War risk insurance premium in basis points for this chokepoint","format":"int32","type":"integer"},"warRiskTier":{"description":"War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat\n classification. Free field (no PRO gate).","enum":["WAR_RISK_TIER_UNSPECIFIED","WAR_RISK_TIER_NORMAL","WAR_RISK_TIER_ELEVATED","WAR_RISK_TIER_HIGH","WAR_RISK_TIER_CRITICAL","WAR_RISK_TIER_WAR_ZONE"],"type":"string"}},"type":"object"},"GetCountryProductsRequest":{"properties":{"hs4":{"description":"Optional requested heading; permits bounded recovery of a missing product.","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2 country code whose strategic products should be returned.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2"],"type":"object"},"GetCountryProductsResponse":{"properties":{"evidence":{"$ref":"#/components/schemas/CountryProductEvidence"},"fetchedAt":{"description":"ISO timestamp from the seeded payload (empty when no data is cached).","type":"string"},"iso2":{"type":"string"},"products":{"items":{"$ref":"#/components/schemas/CountryProduct"},"type":"array"}},"type":"object"},"GetCountryVulnerabilitiesRequest":{"properties":{"iso2":{"description":"Uppercase ISO 3166-1 alpha-2 country code.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2"],"type":"object"},"GetCountryVulnerabilitiesResponse":{"properties":{"country":{"description":"Human-readable name of the requested country.","type":"string"},"generatedAt":{"description":"ISO 8601 timestamp when the country index was generated.","type":"string"},"iso2":{"description":"Uppercase ISO 3166-1 alpha-2 code for the requested country.","type":"string"},"methodologyVersion":{"description":"Version of the scoring methodology used for every row.","type":"string"},"upstreamUnavailable":{"description":"True when the published country index could not be read.","type":"boolean"},"vulnerabilities":{"items":{"$ref":"#/components/schemas/CommodityVulnerability"},"type":"array"}},"type":"object"},"GetCriticalMineralsRequest":{"type":"object"},"GetCriticalMineralsResponse":{"properties":{"fetchedAt":{"type":"string"},"minerals":{"items":{"$ref":"#/components/schemas/CriticalMineral"},"type":"array"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"GetFuelShortageDetailRequest":{"description":"GetFuelShortageDetail returns a single shortage with full evidence\n bundle + citation timeline. Loaded lazily on drawer open.","properties":{"shortageId":{"description":"Fuel-shortage identifier to load with full evidence details.","type":"string"}},"required":["shortageId"],"type":"object"},"GetFuelShortageDetailResponse":{"properties":{"fetchedAt":{"type":"string"},"shortage":{"$ref":"#/components/schemas/FuelShortageEntry"},"unavailable":{"type":"boolean"}},"type":"object"},"GetMineralProductionRequest":{"properties":{"commodity":{"description":"USGS commodity id or label (e.g. \"cobalt\"). Empty returns every commodity.","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2. When set, countries[] is scoped to this producer and\n the countries portfolio is populated.","type":"string"},"stage":{"description":"\"mine\" or \"refinery\". Empty returns both stages when present.","type":"string"}},"type":"object"},"GetMineralProductionResponse":{"properties":{"commodities":{"items":{"$ref":"#/components/schemas/MineralProductionRecord"},"type":"array"},"countries":{"items":{"$ref":"#/components/schemas/MineralCountryPortfolio"},"type":"array"},"dataYear":{"format":"int32","type":"integer"},"fetchedAt":{"type":"string"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"GetMultiSectorCostShockRequest":{"properties":{"chokepointId":{"description":"Chokepoint identifier to model as disrupted.","type":"string"},"closureDays":{"description":"Closure-window duration in days. Server clamps to [1, 365]. Defaults to 30.","format":"int32","type":"integer"},"iso2":{"description":"ISO 3166-1 alpha-2 country code for the importing country.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2","chokepointId"],"type":"object"},"GetMultiSectorCostShockResponse":{"properties":{"chokepointId":{"type":"string"},"closureDays":{"description":"Server-clamped closure-window duration in days (1-365).","format":"int32","type":"integer"},"fetchedAt":{"type":"string"},"iso2":{"type":"string"},"sectors":{"items":{"$ref":"#/components/schemas/MultiSectorCostShock"},"type":"array"},"totalAddedCost":{"description":"Sum of total_cost_shock across all sectors.","format":"double","type":"number"},"unavailableReason":{"description":"Populated when no seeded import data is available for the country.","type":"string"},"warRiskTier":{"description":"War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat\n classification. Free field (no PRO gate).","enum":["WAR_RISK_TIER_UNSPECIFIED","WAR_RISK_TIER_NORMAL","WAR_RISK_TIER_ELEVATED","WAR_RISK_TIER_HIGH","WAR_RISK_TIER_CRITICAL","WAR_RISK_TIER_WAR_ZONE"],"type":"string"}},"type":"object"},"GetPipelineDetailRequest":{"description":"GetPipelineDetail returns a single pipeline with its full evidence bundle.\n Evidence surface here is richer than ListPipelinesResponse — the list view\n is designed for the map layer's compact shape; detail is designed for the\n click-through drawer.","properties":{"pipelineId":{"description":"Pipeline identifier to load with full evidence details.","type":"string"}},"required":["pipelineId"],"type":"object"},"GetPipelineDetailResponse":{"properties":{"fetchedAt":{"type":"string"},"pipeline":{"$ref":"#/components/schemas/PipelineEntry"},"revisions":{"items":{"$ref":"#/components/schemas/PipelineRevisionEntry"},"type":"array"},"unavailable":{"type":"boolean"}},"type":"object"},"GetRouteExplorerLaneRequest":{"properties":{"cargoType":{"description":"One of: container, tanker, bulk, roro","type":"string"},"fromIso2":{"description":"ISO 3166-1 alpha-2 origin country code for the trade lane.","pattern":"^[A-Z]{2}$","type":"string"},"hs2":{"description":"HS2 chapter code, e.g. \"27\", \"85\"","type":"string"},"toIso2":{"description":"ISO 3166-1 alpha-2 destination country code for the trade lane.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["fromIso2","toIso2","hs2","cargoType"],"type":"object"},"GetRouteExplorerLaneResponse":{"properties":{"bypassOptions":{"items":{"$ref":"#/components/schemas/BypassCorridorOption"},"type":"array"},"cargoType":{"type":"string"},"chokepointExposures":{"items":{"$ref":"#/components/schemas/ChokepointExposureSummary"},"type":"array"},"disruptionScore":{"format":"double","type":"number"},"estFreightUsdPerTeuRange":{"$ref":"#/components/schemas/NumberRange"},"estTransitDaysRange":{"$ref":"#/components/schemas/NumberRange"},"fetchedAt":{"type":"string"},"fromIso2":{"type":"string"},"hs2":{"type":"string"},"noModeledLane":{"description":"True when the wrapper fell back to the origin's first route (no shared route\n between origin and destination clusters). Signals \"no modeled lane\" to the UI.","type":"boolean"},"primaryRouteGeometry":{"items":{"$ref":"#/components/schemas/GeoPoint"},"type":"array"},"primaryRouteId":{"description":"Primary trade route ID from TRADE_ROUTES config. Empty when no modeled lane.","type":"string"},"toIso2":{"type":"string"},"warRiskTier":{"type":"string"}},"type":"object"},"GetRouteImpactRequest":{"properties":{"fromIso2":{"description":"ISO 3166-1 alpha-2 origin country code for the route.","pattern":"^[A-Z]{2}$","type":"string"},"hs2":{"description":"HS2 chapter code for the product sector on the route.","type":"string"},"toIso2":{"description":"ISO 3166-1 alpha-2 destination country code for the route.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["fromIso2","toIso2","hs2"],"type":"object"},"GetRouteImpactResponse":{"properties":{"comtradeSource":{"type":"string"},"dependencyFlags":{"items":{"description":"DependencyFlag classifies how a country+sector dependency can fail.","enum":["DEPENDENCY_FLAG_UNSPECIFIED","DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL","DEPENDENCY_FLAG_SINGLE_CORRIDOR_CRITICAL","DEPENDENCY_FLAG_COMPOUND_RISK","DEPENDENCY_FLAG_DIVERSIFIABLE"],"type":"string"},"type":"array"},"fetchedAt":{"type":"string"},"hs2InSeededUniverse":{"type":"boolean"},"laneValueUsd":{"format":"double","type":"number"},"primaryExporterIso2":{"type":"string"},"primaryExporterShare":{"format":"double","type":"number"},"resilienceScore":{"format":"double","type":"number"},"topStrategicProducts":{"items":{"$ref":"#/components/schemas/StrategicProduct"},"type":"array"}},"type":"object"},"GetSectorDependencyRequest":{"properties":{"hs2":{"description":"HS2 chapter code, e.g. \"27\" (mineral fuels), \"85\" (electronics)","type":"string"},"iso2":{"description":"ISO 3166-1 alpha-2 country code whose sector dependency should be analyzed.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["iso2","hs2"],"type":"object"},"GetSectorDependencyResponse":{"properties":{"fetchedAt":{"type":"string"},"flags":{"items":{"description":"DependencyFlag classifies how a country+sector dependency can fail.","enum":["DEPENDENCY_FLAG_UNSPECIFIED","DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL","DEPENDENCY_FLAG_SINGLE_CORRIDOR_CRITICAL","DEPENDENCY_FLAG_COMPOUND_RISK","DEPENDENCY_FLAG_DIVERSIFIABLE"],"type":"string"},"type":"array"},"hasViableBypass":{"description":"Whether at least one viable bypass corridor exists for the primary chokepoint.","type":"boolean"},"hs2":{"type":"string"},"hs2Label":{"description":"Human-readable HS2 chapter name.","type":"string"},"iso2":{"type":"string"},"primaryChokepointExposure":{"description":"Exposure score for the primary chokepoint (0–100).","format":"double","type":"number"},"primaryChokepointId":{"description":"Chokepoint ID with the highest exposure score for this country+sector.","type":"string"},"primaryExporterIso2":{"description":"ISO2 of the country supplying the largest share of this sector's imports.","type":"string"},"primaryExporterShare":{"description":"Share of imports from the primary exporter (0–1). 0 = no Comtrade data available.","format":"double","type":"number"}},"type":"object"},"GetShippingRatesRequest":{"type":"object"},"GetShippingRatesResponse":{"properties":{"fetchedAt":{"type":"string"},"indices":{"items":{"$ref":"#/components/schemas/ShippingIndex"},"type":"array"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"GetShippingStressRequest":{"type":"object"},"GetShippingStressResponse":{"properties":{"carriers":{"items":{"$ref":"#/components/schemas/ShippingStressCarrier"},"type":"array"},"fetchedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"stressLevel":{"description":"\"low\" | \"moderate\" | \"elevated\" | \"critical\".","type":"string"},"stressScore":{"description":"Composite stress score 0–100 (higher = more disruption).","format":"double","type":"number"},"upstreamUnavailable":{"description":"Set to true when upstream data source is unavailable and cached data is stale.","type":"boolean"}},"type":"object"},"GetStorageFacilityDetailRequest":{"description":"GetStorageFacilityDetail returns a single facility with its full evidence\n bundle + revision log. Revisions land in Week 3 alongside the disruption\n event log (Week 3 milestone — empty array in v1).","properties":{"facilityId":{"description":"Storage facility identifier to load with full evidence details.","type":"string"}},"required":["facilityId"],"type":"object"},"GetStorageFacilityDetailResponse":{"properties":{"facility":{"$ref":"#/components/schemas/StorageFacilityEntry"},"fetchedAt":{"type":"string"},"revisions":{"items":{"$ref":"#/components/schemas/StorageFacilityRevisionEntry"},"type":"array"},"unavailable":{"type":"boolean"}},"type":"object"},"InvalidRequestBodyError":{"description":"Returned when a JSON POST request body is empty or malformed.","properties":{"message":{"description":"Invalid request body","type":"string"}},"required":["message"],"type":"object"},"JmespathProjectionError":{"description":"Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.","properties":{"_jmespath_error":{"description":"Projection error discriminator and details.","type":"string"},"original_keys":{"description":"Top-level keys or shape of the unprojected response.","items":{"type":"string"},"type":"array"}},"required":["_jmespath_error","original_keys"],"type":"object"},"LatLon":{"properties":{"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"}},"type":"object"},"ListEnergyDisruptionsRequest":{"description":"ListEnergyDisruptions returns the energy disruption event log — state\n transitions for pipelines and storage facilities (sabotage, sanction,\n maintenance, mechanical, weather, commercial, war). Each event ties\n back to an assetId seeded by the pipeline or storage registry, so the\n panel drawer can render an asset-scoped timeline without a second RPC.\n\n Seeded from a curated JSON file (scripts/data/energy-disruptions.json).\n An automated state-transition classifier was scoped but not shipped —\n the log is curated-only today.\n\n See docs/methodology/disruptions.mdx.","properties":{"assetId":{"description":"Filter to one asset. Omit for all. When set, also narrows to the\n matching asset_type if provided.","type":"string"},"assetType":{"description":"Filter to one asset type. Accepts: \"pipeline\" | \"storage\".","type":"string"},"ongoingOnly":{"description":"If true, only return events with endAt empty (still ongoing).","type":"boolean"}},"type":"object"},"ListEnergyDisruptionsResponse":{"properties":{"classifierVersion":{"type":"string"},"events":{"items":{"$ref":"#/components/schemas/EnergyDisruptionEntry"},"type":"array"},"fetchedAt":{"type":"string"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"ListFuelShortagesRequest":{"description":"ListFuelShortages returns the global fuel-shortage alert registry.\n Seeded from a curated JSON file (scripts/data/fuel-shortages.json).\n An LLM classifier extension was scoped but not shipped — the registry\n is curated-only today. Severity (\"confirmed\" or \"watch\") is a row\n field authored at curation time; the evidence is shipped alongside\n so agents and humans can audit the grounds for a severity label.\n\n See docs/methodology/shortages.mdx for the evidence-threshold spec.","properties":{"country":{"description":"Filter to one ISO 3166-1 alpha-2 country. Omit for global.","type":"string"},"product":{"description":"Filter to one product. Accepts: \"petrol\" | \"diesel\" | \"jet\" | \"heating_oil\".\n Omit for all products.","type":"string"},"severity":{"description":"Filter to one severity. Accepts: \"confirmed\" | \"watch\". Omit for both.","type":"string"}},"type":"object"},"ListFuelShortagesResponse":{"properties":{"classifierVersion":{"type":"string"},"fetchedAt":{"type":"string"},"shortages":{"items":{"$ref":"#/components/schemas/FuelShortageEntry"},"type":"array"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"ListPipelinesRequest":{"description":"ListPipelines returns the full oil and/or gas pipeline registry with\n evidence-based status per asset. Registry is curated (see\n docs/methodology/pipelines.mdx) and refreshed weekly by\n scripts/seed-pipelines-{gas,oil}.mjs. Typical consumer: PipelineStatusPanel\n rendering the DeckGL PathLayer.\n\n The public badge is DERIVED from the evidence bundle server-side at\n read time — callers MUST use `public_badge` for display, not invent\n their own derivation from `evidence` fields. This keeps the atlas and\n MCP clients consistent and versioned together.","properties":{"commodityType":{"description":"Filter to one commodity. Omit (or pass empty) to receive both.","type":"string"}},"type":"object"},"ListPipelinesResponse":{"properties":{"classifierVersion":{"type":"string"},"fetchedAt":{"type":"string"},"pipelines":{"items":{"$ref":"#/components/schemas/PipelineEntry"},"type":"array"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"ListStorageFacilitiesRequest":{"description":"ListStorageFacilities returns the curated strategic storage registry\n (underground gas storage, strategic petroleum reserves, LNG terminals,\n crude tank farms) with evidence-based status per asset. Registry is\n curated (see docs/methodology/storage.mdx) and refreshed weekly by\n scripts/seed-storage-facilities.mjs. Typical consumer:\n StorageFacilityMapPanel rendering the DeckGL ScatterplotLayer.\n\n Like pipelines, the public badge is DERIVED from the evidence bundle\n server-side at read time. Callers MUST use `public_badge` for display\n rather than inventing their own derivation from `evidence` fields, so\n the atlas and MCP clients stay consistent and versioned together.","properties":{"facilityType":{"description":"Filter to one facility type. Accepts:\n   \"ugs\" | \"spr\" | \"lng_export\" | \"lng_import\" | \"crude_tank_farm\"\n Omit (or pass empty) to receive all types.","type":"string"}},"type":"object"},"ListStorageFacilitiesResponse":{"properties":{"classifierVersion":{"type":"string"},"facilities":{"items":{"$ref":"#/components/schemas/StorageFacilityEntry"},"type":"array"},"fetchedAt":{"type":"string"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"ListVulnerabilityRankingsRequest":{"properties":{"band":{"description":"Optional score band: low, moderate, high, or critical.","pattern":"^$|^(low|moderate|high|critical)$","type":"string"},"commodityId":{"description":"Optional stable commodity mapping identifier.","maxLength":80,"pattern":"^$|^[a-z0-9_\\-]+$","type":"string"},"pageSize":{"description":"Maximum rows to return; zero uses the server default and the maximum is 25.","format":"int32","maximum":25,"minimum":0,"type":"integer"},"state":{"description":"Optional evidence state: ok, insufficient_data, or stale_input.","pattern":"^$|^(ok|insufficient_data|stale_input)$","type":"string"}},"type":"object"},"ListVulnerabilityRankingsResponse":{"properties":{"generatedAt":{"description":"ISO 8601 timestamp when the country index was generated.","type":"string"},"methodologyVersion":{"description":"Version of the scoring methodology used for every row.","type":"string"},"upstreamUnavailable":{"description":"True when the published country index could not be read.","type":"boolean"},"vulnerabilities":{"items":{"$ref":"#/components/schemas/CommodityVulnerability"},"type":"array"}},"type":"object"},"MineralCountryHolding":{"properties":{"commodity":{"type":"string"},"commodityId":{"type":"string"},"output":{"format":"double","type":"number"},"share":{"format":"double","type":"number"},"stage":{"type":"string"},"withheld":{"type":"boolean"}},"type":"object"},"MineralCountryPortfolio":{"properties":{"holdings":{"items":{"$ref":"#/components/schemas/MineralCountryHolding"},"type":"array"},"iso2":{"type":"string"}},"type":"object"},"MineralCountryShare":{"properties":{"country":{"type":"string"},"estimated":{"type":"boolean"},"iso2":{"type":"string"},"output":{"format":"double","type":"number"},"residual":{"type":"boolean"},"share":{"format":"double","type":"number"},"withheld":{"type":"boolean"}},"type":"object"},"MineralProducer":{"properties":{"country":{"type":"string"},"countryCode":{"type":"string"},"productionTonnes":{"format":"double","type":"number"},"sharePct":{"format":"double","type":"number"}},"type":"object"},"MineralProductionRecord":{"properties":{"commodity":{"type":"string"},"commodityId":{"type":"string"},"mine":{"$ref":"#/components/schemas/MineralStageSnapshot"},"refinery":{"$ref":"#/components/schemas/MineralStageSnapshot"},"sources":{"items":{"type":"string"},"type":"array"},"unit":{"type":"string"},"year":{"format":"int32","type":"integer"}},"type":"object"},"MineralStageSnapshot":{"properties":{"countries":{"items":{"$ref":"#/components/schemas/MineralCountryShare"},"type":"array"},"hhi":{"format":"double","type":"number"},"unit":{"type":"string"},"withheldCount":{"format":"int32","type":"integer"},"worldTotal":{"format":"double","type":"number"},"year":{"format":"int32","type":"integer"}},"type":"object"},"MultiSectorCostShock":{"properties":{"addedTransitDays":{"description":"Bypass-corridor transit penalty (informational).","format":"int32","type":"integer"},"closureDays":{"description":"Echoes the clamped closure duration used for total_cost_shock (1-365).","format":"int32","type":"integer"},"freightAddedPctPerTon":{"description":"Bypass-corridor freight uplift fraction (0.10 == +10% per ton).","format":"double","type":"number"},"hs2":{"description":"HS2 chapter code (e.g. \"27\" mineral fuels, \"85\" electronics).","type":"string"},"hs2Label":{"description":"Friendly chapter label (e.g. \"Energy\", \"Electronics\").","type":"string"},"importValueAnnual":{"description":"Total annual import value (USD) for this sector.","format":"double","type":"number"},"totalCostShock":{"description":"Cost for the requested closure_days window.","format":"double","type":"number"},"totalCostShock30Days":{"format":"double","type":"number"},"totalCostShock90Days":{"format":"double","type":"number"},"totalCostShockPerDay":{"format":"double","type":"number"},"warRiskPremiumBps":{"description":"War-risk insurance premium (basis points) sourced from the chokepoint tier.","format":"int32","type":"integer"}},"type":"object"},"NumberRange":{"description":"Inclusive integer range for transit days / freight USD estimates.","properties":{"max":{"format":"int32","type":"integer"},"min":{"format":"int32","type":"integer"}},"type":"object"},"OperatorStatement":{"properties":{"date":{"type":"string"},"text":{"type":"string"},"url":{"type":"string"}},"type":"object"},"PipelineEntry":{"properties":{"capacityBcmYr":{"format":"double","type":"number"},"capacityMbd":{"format":"double","type":"number"},"commodityType":{"description":"Either \"gas\" or \"oil\".","type":"string"},"endPoint":{"$ref":"#/components/schemas/LatLon"},"evidence":{"$ref":"#/components/schemas/PipelineEvidence"},"fromCountry":{"type":"string"},"id":{"type":"string"},"inService":{"format":"int32","type":"integer"},"lengthKm":{"format":"int32","type":"integer"},"name":{"type":"string"},"operator":{"type":"string"},"publicBadge":{"description":"Server-derived public badge. One of:\n   \"flowing\" | \"reduced\" | \"offline\" | \"disputed\"","type":"string"},"startPoint":{"$ref":"#/components/schemas/LatLon"},"toCountry":{"type":"string"},"transitCountries":{"items":{"type":"string"},"type":"array"},"waypoints":{"items":{"$ref":"#/components/schemas/LatLon"},"type":"array"}},"type":"object"},"PipelineEvidence":{"properties":{"classifierConfidence":{"format":"double","type":"number"},"classifierVersion":{"type":"string"},"commercialState":{"description":"One of: \"under_contract\" | \"expired\" | \"suspended\" | \"unknown\"","type":"string"},"lastEvidenceUpdate":{"type":"string"},"operatorStatement":{"$ref":"#/components/schemas/OperatorStatement"},"physicalState":{"description":"One of: \"flowing\" | \"reduced\" | \"offline\" | \"unknown\"","type":"string"},"physicalStateSource":{"description":"One of: \"operator\" | \"regulator\" | \"press\" | \"satellite\" | \"ais-relay\"","type":"string"},"sanctionRefs":{"items":{"$ref":"#/components/schemas/SanctionRef"},"type":"array"}},"type":"object"},"PipelineRevisionEntry":{"properties":{"classifierVersion":{"type":"string"},"date":{"type":"string"},"fieldChanged":{"type":"string"},"newValue":{"type":"string"},"previousValue":{"type":"string"},"sourcesUsed":{"items":{"type":"string"},"type":"array"},"trigger":{"description":"One of: \"classifier\" | \"source\" | \"decay\" | \"override\"","type":"string"}},"type":"object"},"ProductExporter":{"properties":{"netWeightEstimated":{"description":"True when the provider flagged the net weight as its own estimate.","type":"boolean"},"netWeightKg":{"description":"Net weight of the shown flow in kilograms. Absent when the provider\n reported no weight; \"not reported\" is never rendered as 0 trade.","format":"double","type":"number"},"partnerCode":{"format":"int32","type":"integer"},"partnerIso2":{"type":"string"},"quantity":{"description":"Reported quantity in the unit named by quantity_unit_code. Absent when no\n quantity was reported or its unit is outside the pinned unit registry.","format":"double","type":"number"},"quantityUnitCode":{"description":"UN Comtrade quantity unit code (8 = kg, 12 = m3, 5 = items, 7 = litres).\n Absent whenever quantity is absent.","format":"int32","type":"integer"},"scale":{"$ref":"#/components/schemas/ExporterScale"},"share":{"format":"double","type":"number"},"value":{"format":"double","type":"number"}},"type":"object"},"RateLimitError":{"description":"Returned when a gateway or handler rate limit rejects the request.","properties":{"error":{"description":"Human-readable rate-limit failure reason.","type":"string"}},"required":["error"],"type":"object"},"SanctionRef":{"properties":{"authority":{"type":"string"},"date":{"type":"string"},"listId":{"type":"string"},"url":{"type":"string"}},"type":"object"},"ShippingIndex":{"properties":{"changePct":{"description":"Legacy display field with the same fail-OPEN fallback as previous_value\n (a flat 0 when no prior exists). Use period_change_pct for decision work.","format":"double","type":"number"},"currentValue":{"format":"double","type":"number"},"history":{"items":{"$ref":"#/components/schemas/ShippingRatePoint"},"type":"array"},"indexId":{"type":"string"},"name":{"type":"string"},"periodChangeBasis":{"description":"Basis for the decision-grade period-over-period change.","enum":["PERIOD_CHANGE_BASIS_UNSPECIFIED","publisher_reported","derived_from_prior_period_level"],"type":"string"},"periodChangePct":{"description":"Decision-grade period-over-period move in percent (#6066). Optional so a\n missing reading is ABSENT from the response rather than collapsing to 0,\n which would render identically to a real unchanged period. Fails CLOSED:\n present only when the publisher reported its own percentage or a\n comparable prior-period level. A single index level never becomes a\n change. The endpoint normalizes a missing reading to ABSENT (canonical\n ProtoJSON: serializers omit, parsers treat null as unset) — a plain JSON\n client can still tell absent from null, so read absence, not null.","format":"double","type":"number"},"previousValue":{"description":"Legacy display field. For the Shanghai Shipping Exchange indices (SCFI,\n CCFI) this DELIBERATELY falls back to the current level when the exchange\n published no comparable prior, so it cannot distinguish \"unchanged week\"\n from \"no prior at all\". Use prior_period_value for decision work.","format":"double","type":"number"},"priorPeriodDate":{"description":"Observation date (YYYY-MM-DD) of prior_period_value, as published. Absent\n whenever prior_period_value is absent, or when the publisher dated the\n level only implicitly.","type":"string"},"priorPeriodValue":{"description":"The publisher's own prior-period index level that period_change_pct was\n measured against. Absent when the publisher shipped no comparable prior.","format":"double","type":"number"},"spikeAlert":{"type":"boolean"},"unit":{"type":"string"}},"type":"object"},"ShippingRatePoint":{"properties":{"date":{"type":"string"},"value":{"format":"double","type":"number"}},"type":"object"},"ShippingStressCarrier":{"description":"ShippingStressCarrier represents market stress data for a carrier or shipping index.","properties":{"carrierType":{"description":"Carrier type: \"etf\" | \"carrier\" | \"index\".","type":"string"},"changePct":{"description":"Percentage change from previous close.","format":"double","type":"number"},"name":{"description":"Human-readable name.","type":"string"},"price":{"description":"Current price.","format":"double","type":"number"},"sparkline":{"items":{"description":"30-day price sparkline.","format":"double","type":"number"},"type":"array"},"symbol":{"description":"Ticker or identifier (e.g., \"BDRY\", \"ZIM\").","type":"string"}},"type":"object"},"StorageEvidence":{"properties":{"classifierConfidence":{"format":"double","type":"number"},"classifierVersion":{"type":"string"},"commercialState":{"description":"One of: \"under_contract\" | \"expired\" | \"suspended\" | \"unknown\"","type":"string"},"fillDisclosed":{"description":"Whether working-gas / stock-level fill is publicly disclosed for this\n asset. LNG export terminals, for instance, tend NOT to disclose; UGS\n sites in Europe are required to disclose via GIE AGSI+.","type":"boolean"},"fillSource":{"description":"Source of the disclosed fill series (\"GIE AGSI+\", \"EIA SPR weekly\n stock report\", etc.). Empty when fill_disclosed=false.","type":"string"},"lastEvidenceUpdate":{"type":"string"},"operatorStatement":{"$ref":"#/components/schemas/StorageOperatorStatement"},"physicalState":{"description":"One of: \"operational\" | \"reduced\" | \"offline\" | \"under_construction\" | \"unknown\"","type":"string"},"physicalStateSource":{"description":"One of: \"operator\" | \"regulator\" | \"press\" | \"satellite\" | \"ais-relay\"","type":"string"},"sanctionRefs":{"items":{"$ref":"#/components/schemas/StorageSanctionRef"},"type":"array"}},"type":"object"},"StorageFacilityEntry":{"properties":{"capacityMb":{"format":"double","type":"number"},"capacityMtpa":{"format":"double","type":"number"},"capacityTwh":{"description":"Working capacity in the facility's native unit (see working_capacity_unit).\n Exactly ONE of these is populated per facility, chosen by facility_type:\n   ugs                              → capacity_twh\n   spr, crude_tank_farm             → capacity_mb\n   lng_export, lng_import           → capacity_mtpa","format":"double","type":"number"},"country":{"type":"string"},"evidence":{"$ref":"#/components/schemas/StorageEvidence"},"facilityType":{"description":"One of: \"ugs\" | \"spr\" | \"lng_export\" | \"lng_import\" | \"crude_tank_farm\"","type":"string"},"id":{"type":"string"},"inService":{"format":"int32","type":"integer"},"location":{"$ref":"#/components/schemas/StorageLatLon"},"name":{"type":"string"},"operator":{"type":"string"},"publicBadge":{"description":"Server-derived public badge. One of:\n   \"operational\" | \"reduced\" | \"offline\" | \"disputed\"","type":"string"},"workingCapacityUnit":{"description":"One of: \"TWh\" | \"Mb\" | \"Mtpa\"","type":"string"}},"type":"object"},"StorageFacilityRevisionEntry":{"properties":{"classifierVersion":{"type":"string"},"date":{"type":"string"},"fieldChanged":{"type":"string"},"newValue":{"type":"string"},"previousValue":{"type":"string"},"sourcesUsed":{"items":{"type":"string"},"type":"array"},"trigger":{"description":"One of: \"classifier\" | \"source\" | \"decay\" | \"override\"","type":"string"}},"type":"object"},"StorageLatLon":{"properties":{"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"}},"type":"object"},"StorageOperatorStatement":{"properties":{"date":{"type":"string"},"text":{"type":"string"},"url":{"type":"string"}},"type":"object"},"StorageSanctionRef":{"properties":{"authority":{"type":"string"},"date":{"type":"string"},"listId":{"type":"string"},"url":{"type":"string"}},"type":"object"},"StrategicProduct":{"properties":{"hs4":{"type":"string"},"label":{"type":"string"},"primaryChokepointId":{"type":"string"},"topExporterIso2":{"type":"string"},"topExporterShare":{"format":"double","type":"number"},"totalValueUsd":{"format":"double","type":"number"}},"type":"object"},"TransitDayCount":{"properties":{"capContainer":{"format":"double","type":"number"},"capDryBulk":{"format":"double","type":"number"},"capGeneralCargo":{"format":"double","type":"number"},"capRoro":{"format":"double","type":"number"},"capTanker":{"format":"double","type":"number"},"cargo":{"format":"int32","type":"integer"},"container":{"format":"int32","type":"integer"},"date":{"type":"string"},"dryBulk":{"format":"int32","type":"integer"},"generalCargo":{"format":"int32","type":"integer"},"other":{"format":"int32","type":"integer"},"roro":{"format":"int32","type":"integer"},"tanker":{"format":"int32","type":"integer"},"total":{"format":"int32","type":"integer"}},"type":"object"},"TransitSummary":{"properties":{"baselineAvgDaily":{"description":"Mean daily transits, 12 months ending a year before the seed; 0 means\n withhold. baseline_from/to: YYYY-MM-DD bounds, inclusive.","format":"double","type":"number"},"baselineFrom":{"type":"string"},"baselineTo":{"type":"string"},"dataAvailable":{"description":"False when PortWatch returned no history this cycle; wow_change_pct,\n history and official_*/baseline_* are then zero-state fill.","type":"boolean"},"disruptionPct":{"format":"double","type":"number"},"history":{"items":{"$ref":"#/components/schemas/TransitDayCount"},"type":"array"},"incidentCount7d":{"format":"int32","type":"integer"},"officialAvg7d":{"format":"double","type":"number"},"officialLatestDate":{"description":"IMF PortWatch latest published day, YYYY-MM-DD (lag of several days); empty means\n withhold official_latest_total and official_avg_7d (absent below 7 days).","type":"string"},"officialLatestTotal":{"format":"int32","type":"integer"},"riskLevel":{"type":"string"},"riskReportAction":{"type":"string"},"riskSummary":{"type":"string"},"todayCargo":{"format":"int32","type":"integer"},"todayCountsAvailable":{"description":"False when the relay's 24h AIS window held no crossings; today_* are then\n unsupplied, not a measured zero.","type":"boolean"},"todayOther":{"format":"int32","type":"integer"},"todayTanker":{"format":"int32","type":"integer"},"todayTotal":{"format":"int32","type":"integer"},"wowChangePct":{"format":"double","type":"number"}},"type":"object"},"UnauthorizedError":{"description":"Returned when the API key is missing, malformed, or lacks current API access.","properties":{"error":{"description":"Human-readable error message.","type":"string"}},"required":["error"],"type":"object"},"ValidationError":{"description":"ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.","properties":{"violations":{"description":"List of validation violations","items":{"$ref":"#/components/schemas/FieldViolation"},"type":"array"}},"required":["violations"],"type":"object"},"VulnerabilityBuffer":{"properties":{"inputs":{"items":{"$ref":"#/components/schemas/VulnerabilityInput"},"type":"array"},"kind":{"description":"Buffer source class, such as stocks_to_use or gas_storage_fill.","type":"string"},"state":{"description":"Buffer evidence state: known or unknown.","type":"string"},"vulnerability":{"description":"Residual vulnerability after the available buffer, from 0 to 1.","format":"double","type":"number"}},"type":"object"},"VulnerabilityComponents":{"properties":{"buffer":{"$ref":"#/components/schemas/VulnerabilityBuffer"},"sourceConcentration":{"$ref":"#/components/schemas/VulnerabilitySourceConcentration"},"transitExposure":{"$ref":"#/components/schemas/VulnerabilityTransitExposure"}},"type":"object"},"VulnerabilityInput":{"properties":{"detail":{"description":"Bounded explanation of the mapped input.","type":"string"},"fetchedAt":{"description":"ISO 8601 timestamp when the source snapshot was fetched.","type":"string"},"sourceKey":{"description":"Redis or source-contract key that supplied this observation.","type":"string"},"sourceName":{"description":"Human-readable source name.","type":"string"},"sourceUrl":{"description":"Public source or methodology URL.","type":"string"},"stale":{"description":"True when this observation is older than its source-specific freshness budget.","type":"boolean"},"value":{"description":"Numeric observation used by the scorer; absent when the source is unknown.","format":"double","type":"number"},"year":{"description":"Observation year when the source publishes annual data.","format":"int32","type":"integer"}},"type":"object"},"VulnerabilitySourceConcentration":{"properties":{"coverage":{"description":"Overall concentration coverage state.","type":"string"},"importHhi":{"description":"Import supplier Herfindahl-Hirschman concentration from 0 to 1.","format":"double","type":"number"},"inputs":{"items":{"$ref":"#/components/schemas/VulnerabilityInput"},"type":"array"},"mineHhi":{"description":"Mine-stage production concentration from 0 to 1.","format":"double","type":"number"},"productionCoverage":{"description":"Producer-stage coverage used for the combined concentration.","type":"string"},"productionHhi":{"description":"Combined mine and refinery production concentration from 0 to 1.","format":"double","type":"number"},"refineryHhi":{"description":"Refinery-stage production concentration from 0 to 1.","format":"double","type":"number"},"value":{"description":"Combined supplier or producer concentration from 0 to 1.","format":"double","type":"number"}},"type":"object"},"VulnerabilityTransitExposure":{"properties":{"chokepoints":{"items":{"$ref":"#/components/schemas/VulnerabilityTransitRoute"},"type":"array"},"value":{"description":"Combined chokepoint exposure from 0 to 1.","format":"double","type":"number"}},"type":"object"},"VulnerabilityTransitRoute":{"properties":{"id":{"description":"Stable chokepoint identifier.","type":"string"},"inputs":{"items":{"$ref":"#/components/schemas/VulnerabilityInput"},"type":"array"},"name":{"description":"Human-readable chokepoint name.","type":"string"},"status":{"description":"Current route state: baseline, disrupted, or unknown when the flow row is absent.","type":"string"},"transitShare":{"description":"Country and commodity exposure share using this route, from 0 to 1.","format":"double","type":"number"},"weightedTransitShare":{"description":"Transit share after the current disruption multiplier, from 0 to 1.","format":"double","type":"number"}},"type":"object"}},"securitySchemes":{"ApiKeyHeader":{"description":"Alias header for the WorldMonitor API key (X-WorldMonitor-Key).","in":"header","name":"X-Api-Key","type":"apiKey"},"BearerAuth":{"description":"Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer \u003ctoken\u003e.","scheme":"bearer","type":"http"},"WorldMonitorKey":{"description":"User-issued WorldMonitor API key.","in":"header","name":"X-WorldMonitor-Key","type":"apiKey"}}},"info":{"title":"SupplyChainService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/supply-chain/v1/get-bypass-options":{"get":{"description":"GetBypassOptions ranks a chokepoint's bypass corridors for a cargo type and closure share by cost and waypoint risk. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetBypassOptions","parameters":[{"description":"Chokepoint identifier to evaluate for bypass options.","example":"suez","in":"query","name":"chokepointId","required":true,"schema":{"type":"string"}},{"description":"container | tanker | bulk | roro  (default: \"container\")","example":"container","in":"query","name":"cargoType","required":false,"schema":{"type":"string"}},{"description":"0-100, percent of capacity blocked (default: 100)","example":1,"in":"query","name":"closurePct","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"cargoType":"container","chokepointId":"suez","closurePct":1,"fetchedAt":"2026-01-15T12:00:00Z","options":[{"activationThreshold":"example","addedCostMultiplier":75.25,"addedTransitDays":7,"bypassWarRiskTier":"WAR_RISK_TIER_NORMAL","capacityConstraintTonnage":"1717200000000"}]},"schema":{"$ref":"#/components/schemas/GetBypassOptionsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetBypassOptions","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-china-corridor-control-towers":{"get":{"description":"GetChinaCorridorControlTowers composes reviewed China logistics corridors\n from existing source caches. Conditions retain canonical provenance and\n explicit unavailable states; the response never emits a single risk score.","operationId":"GetChinaCorridorControlTowers","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"generatedAt":"2026-07-25T12:00:00.000Z","payloadJson":"{\"generatedAt\":\"2026-07-25T12:00:00.000Z\",\"corridors\":[{\"id\":\"china-yangtze-river-delta\",\"name\":\"Yangtze River Delta\",\"description\":\"Reviewed coastal logistics corridor joining Shanghai, Jiangsu, and Zhejiang gateways.\",\"boundary\":[{\"lat\":28.4,\"lon\":118.2},{\"lat\":28.4,\"lon\":123.2},{\"lat\":33.4,\"lon\":123.2},{\"lat\":33.4,\"lon\":118.2},{\"lat\":28.4,\"lon\":118.2}],\"nodes\":[{\"id\":\"china-node:yrd-port-shanghai\",\"name\":\"Shanghai\",\"type\":\"port\",\"lat\":31.1918,\"lon\":121.6442,\"sourceOwner\":\"IMF PortWatch\",\"sourceSelector\":{\"family\":\"port\",\"id\":\"port1188\"}}],\"availability\":\"partial\",\"conditions\":[{\"family\":\"port\",\"providerId\":\"portwatch\",\"availability\":\"available\",\"reason\":null,\"sourceSignals\":[{\"id\":\"signal:portwatch:port1188:2026-07-25T11:00:00.000Z\",\"family\":\"port\",\"selectorId\":\"port1188\",\"availability\":\"available\",\"publisher\":{\"id\":\"publisher:imf-portwatch\",\"name\":\"IMF PortWatch\",\"type\":\"official\"},\"sourceUrl\":\"https://portwatch.imf.org/\",\"sourceScope\":\"node\",\"observationTime\":\"2026-07-25T11:00:00.000Z\",\"observationTimePrecision\":\"instant\",\"releaseTime\":null,\"releaseTimePrecision\":\"unknown\",\"retrievalTime\":\"2026-07-25T11:05:00.000Z\",\"retrievalTimePrecision\":\"instant\",\"revision\":null,\"transportFreshness\":\"fresh\",\"contentFreshness\":\"current\",\"summary\":\"PortWatch activity observation available for Shanghai.\",\"metrics\":{\"tankerCalls30d\":14}}],\"provenance\":{\"contractVersion\":\"decision-signal-provenance/v1\",\"signalId\":\"signal:corridor-condition:china-yangtze-river-delta:port:2026-07-25T11:00:00.000Z\",\"familyId\":\"composed_corridor_condition\",\"claims\":{\"publisher\":{\"status\":\"known\",\"value\":{\"id\":\"publisher:worldmonitor-derived\",\"name\":\"WorldMonitor derived output\",\"type\":\"derived_output\",\"registryReference\":null}},\"observation_time\":{\"status\":\"known\",\"value\":{\"role\":\"observation\",\"value\":\"2026-07-25T11:00:00.000Z\",\"precision\":\"instant\"}},\"source_url\":{\"status\":\"not_applicable\",\"reason\":\"The corridor condition links source URLs through its input signals.\"},\"original_reference\":{\"status\":\"not_applicable\",\"reason\":\"The corridor condition is composed from multiple source records.\"},\"original_language\":{\"status\":\"not_applicable\",\"reason\":\"The deterministic composition has no original-language text.\"},\"translation\":{\"status\":\"not_applicable\",\"reason\":\"The deterministic composition has no translated source text.\"},\"effective_time\":{\"status\":\"known\",\"value\":{\"role\":\"effective\",\"value\":\"2026-07-25T11:00:00.000Z\",\"precision\":\"instant\"}},\"publication_time\":{\"status\":\"not_applicable\",\"reason\":\"The computed condition is not a publisher release.\"},\"retrieval_time\":{\"status\":\"known\",\"value\":{\"role\":\"retrieval\",\"value\":\"2026-07-25T11:05:00.000Z\",\"precision\":\"instant\"}},\"revision\":{\"status\":\"known\",\"value\":{\"vintageId\":\"china-yangtze-river-delta:port:2026-07-25T11:00:00.000Z\",\"sequence\":1,\"state\":\"original\"}},\"supersession\":{\"status\":\"known\",\"value\":{\"state\":\"current\"}},\"extraction_confidence\":{\"status\":\"not_applicable\",\"reason\":\"Each input signal owns its extraction confidence.\"},\"classification_confidence\":{\"status\":\"known\",\"value\":{\"score\":1,\"method\":\"exact-reviewed-selector/v1\"}},\"corroboration\":{\"status\":\"known\",\"value\":{\"state\":\"single_source\",\"sourceSignalIds\":[\"signal:portwatch:port1188:2026-07-25T11:00:00.000Z\"]}},\"transport_freshness\":{\"status\":\"known\",\"value\":{\"state\":\"fresh\",\"assessedAt\":\"2026-07-25T12:00:00.000Z\",\"lastSuccessAt\":\"2026-07-25T11:05:00.000Z\"}},\"content_freshness\":{\"status\":\"known\",\"value\":{\"state\":\"current\",\"assessedAt\":\"2026-07-25T12:00:00.000Z\",\"contentAsOf\":\"2026-07-25T11:00:00.000Z\"}},\"derivation\":{\"status\":\"known\",\"value\":{\"methodId\":\"worldmonitor:china-corridor-condition\",\"methodVersion\":\"1\",\"computedAt\":\"2026-07-25T12:00:00.000Z\",\"inputSignalIds\":[\"signal:portwatch:port1188:2026-07-25T11:00:00.000Z\"]}}}}},{\"family\":\"aviation\",\"providerId\":\"provider:aviation\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"hazard\",\"providerId\":\"provider:hazard\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"power_energy\",\"providerId\":\"provider:power_energy\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"strategic_industry\",\"providerId\":\"provider:strategic_industry\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"trade\",\"providerId\":\"provider:trade\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null}]},{\"id\":\"china-greater-bay-area\",\"name\":\"Greater Bay Area\",\"description\":\"Reviewed Pearl River Delta corridor connecting Guangdong, Hong Kong, and Macao-facing port, airport, and industrial gateways.\",\"boundary\":[{\"lat\":20.5,\"lon\":111.5},{\"lat\":20.5,\"lon\":115.8},{\"lat\":24.8,\"lon\":115.8},{\"lat\":24.8,\"lon\":111.5},{\"lat\":20.5,\"lon\":111.5}],\"nodes\":[{\"id\":\"china-node:gba-port-shekou\",\"name\":\"Shekou Shenzhen\",\"type\":\"port\",\"lat\":22.47,\"lon\":113.9,\"sourceOwner\":\"IMF PortWatch\",\"sourceSelector\":{\"family\":\"port\",\"id\":\"port1189\"}}],\"availability\":\"partial\",\"conditions\":[{\"family\":\"port\",\"providerId\":\"portwatch\",\"availability\":\"available\",\"reason\":null,\"sourceSignals\":[{\"id\":\"signal:portwatch:port1189:2026-07-25T11:00:00.000Z\",\"family\":\"port\",\"selectorId\":\"port1189\",\"availability\":\"available\",\"publisher\":{\"id\":\"publisher:imf-portwatch\",\"name\":\"IMF PortWatch\",\"type\":\"official\"},\"sourceUrl\":\"https://portwatch.imf.org/\",\"sourceScope\":\"node\",\"observationTime\":\"2026-07-25T11:00:00.000Z\",\"observationTimePrecision\":\"instant\",\"releaseTime\":null,\"releaseTimePrecision\":\"unknown\",\"retrievalTime\":\"2026-07-25T11:05:00.000Z\",\"retrievalTimePrecision\":\"instant\",\"revision\":null,\"transportFreshness\":\"fresh\",\"contentFreshness\":\"current\",\"summary\":\"PortWatch activity observation available for Shekou Shenzhen.\",\"metrics\":{\"tankerCalls30d\":14}}],\"provenance\":{\"contractVersion\":\"decision-signal-provenance/v1\",\"signalId\":\"signal:corridor-condition:china-greater-bay-area:port:2026-07-25T11:00:00.000Z\",\"familyId\":\"composed_corridor_condition\",\"claims\":{\"publisher\":{\"status\":\"known\",\"value\":{\"id\":\"publisher:worldmonitor-derived\",\"name\":\"WorldMonitor derived output\",\"type\":\"derived_output\",\"registryReference\":null}},\"observation_time\":{\"status\":\"known\",\"value\":{\"role\":\"observation\",\"value\":\"2026-07-25T11:00:00.000Z\",\"precision\":\"instant\"}},\"source_url\":{\"status\":\"not_applicable\",\"reason\":\"The corridor condition links source URLs through its input signals.\"},\"original_reference\":{\"status\":\"not_applicable\",\"reason\":\"The corridor condition is composed from multiple source records.\"},\"original_language\":{\"status\":\"not_applicable\",\"reason\":\"The deterministic composition has no original-language text.\"},\"translation\":{\"status\":\"not_applicable\",\"reason\":\"The deterministic composition has no translated source text.\"},\"effective_time\":{\"status\":\"known\",\"value\":{\"role\":\"effective\",\"value\":\"2026-07-25T11:00:00.000Z\",\"precision\":\"instant\"}},\"publication_time\":{\"status\":\"not_applicable\",\"reason\":\"The computed condition is not a publisher release.\"},\"retrieval_time\":{\"status\":\"known\",\"value\":{\"role\":\"retrieval\",\"value\":\"2026-07-25T11:05:00.000Z\",\"precision\":\"instant\"}},\"revision\":{\"status\":\"known\",\"value\":{\"vintageId\":\"china-greater-bay-area:port:2026-07-25T11:00:00.000Z\",\"sequence\":1,\"state\":\"original\"}},\"supersession\":{\"status\":\"known\",\"value\":{\"state\":\"current\"}},\"extraction_confidence\":{\"status\":\"not_applicable\",\"reason\":\"Each input signal owns its extraction confidence.\"},\"classification_confidence\":{\"status\":\"known\",\"value\":{\"score\":1,\"method\":\"exact-reviewed-selector/v1\"}},\"corroboration\":{\"status\":\"known\",\"value\":{\"state\":\"single_source\",\"sourceSignalIds\":[\"signal:portwatch:port1189:2026-07-25T11:00:00.000Z\"]}},\"transport_freshness\":{\"status\":\"known\",\"value\":{\"state\":\"fresh\",\"assessedAt\":\"2026-07-25T12:00:00.000Z\",\"lastSuccessAt\":\"2026-07-25T11:05:00.000Z\"}},\"content_freshness\":{\"status\":\"known\",\"value\":{\"state\":\"current\",\"assessedAt\":\"2026-07-25T12:00:00.000Z\",\"contentAsOf\":\"2026-07-25T11:00:00.000Z\"}},\"derivation\":{\"status\":\"known\",\"value\":{\"methodId\":\"worldmonitor:china-corridor-condition\",\"methodVersion\":\"1\",\"computedAt\":\"2026-07-25T12:00:00.000Z\",\"inputSignalIds\":[\"signal:portwatch:port1189:2026-07-25T11:00:00.000Z\"]}}}}},{\"family\":\"aviation\",\"providerId\":\"provider:aviation\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"hazard\",\"providerId\":\"provider:hazard\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"power_energy\",\"providerId\":\"provider:power_energy\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"strategic_industry\",\"providerId\":\"provider:strategic_industry\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"trade\",\"providerId\":\"provider:trade\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null}]},{\"id\":\"china-bohai-rim\",\"name\":\"Bohai Rim\",\"description\":\"Reviewed northern maritime-industrial corridor spanning Beijing-Tianjin, Hebei, Shandong, Liaoning, and their major gateways.\",\"boundary\":[{\"lat\":35.5,\"lon\":116},{\"lat\":35.5,\"lon\":123.5},{\"lat\":42.2,\"lon\":123.5},{\"lat\":42.2,\"lon\":116},{\"lat\":35.5,\"lon\":116}],\"nodes\":[{\"id\":\"china-node:bohai-port-qingdao\",\"name\":\"Qingdao\",\"type\":\"port\",\"lat\":36.07,\"lon\":120.32,\"sourceOwner\":\"IMF PortWatch\",\"sourceSelector\":{\"family\":\"port\",\"id\":\"port1069\"}}],\"availability\":\"unavailable\",\"conditions\":[{\"family\":\"port\",\"providerId\":\"provider:port\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"aviation\",\"providerId\":\"provider:aviation\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"hazard\",\"providerId\":\"provider:hazard\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"power_energy\",\"providerId\":\"provider:power_energy\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"strategic_industry\",\"providerId\":\"provider:strategic_industry\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"trade\",\"providerId\":\"provider:trade\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null}]},{\"id\":\"china-western-land-sea-corridor\",\"name\":\"Western Land-Sea Corridor\",\"description\":\"Reviewed western corridor linking inland manufacturing hubs, Xinjiang land crossings, and Guangxi gateways to regional and maritime routes.\",\"boundary\":[{\"lat\":20.4,\"lon\":106.2},{\"lat\":20.4,\"lon\":110.4},{\"lat\":32.5,\"lon\":110.4},{\"lat\":47,\"lon\":91},{\"lat\":47,\"lon\":78.5},{\"lat\":41,\"lon\":78.5},{\"lat\":27,\"lon\":99.7},{\"lat\":22,\"lon\":105.8},{\"lat\":20.4,\"lon\":106.2}],\"nodes\":[{\"id\":\"china-node:western-port-qinzhou\",\"name\":\"Qinzhou\",\"type\":\"port\",\"lat\":21.6788,\"lon\":108.6383,\"sourceOwner\":\"IMF PortWatch\",\"sourceSelector\":{\"family\":\"port\",\"id\":\"port1071\"}}],\"availability\":\"unavailable\",\"conditions\":[{\"family\":\"port\",\"providerId\":\"provider:port\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"aviation\",\"providerId\":\"provider:aviation\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"hazard\",\"providerId\":\"provider:hazard\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"power_energy\",\"providerId\":\"provider:power_energy\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"strategic_industry\",\"providerId\":\"provider:strategic_industry\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null},{\"family\":\"trade\",\"providerId\":\"provider:trade\",\"availability\":\"unavailable\",\"reason\":\"No reviewed source observation is available in this example.\",\"sourceSignals\":[],\"provenance\":null}]}]}","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetChinaCorridorControlTowersResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetChinaCorridorControlTowers","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-chokepoint-dependencies":{"get":{"description":"GetChokepointDependencies returns the inverse country/commodity dependency index. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetChokepointDependencies","parameters":[{"description":"Stable chokepoint identifier, such as hormuz_strait or suez.","example":"suez","in":"query","name":"chokepointId","required":true,"schema":{"pattern":"^[a-z0-9_\\-]+$","type":"string"}},{"description":"Maximum dependencies to return; zero uses the server default and the maximum is 100.","example":25,"in":"query","name":"pageSize","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"chokepoint":"example","chokepointId":"suez","dependencies":[{"band":"example","commodity":"example","commodityId":"example-id","countryIso2":"US","countryName":"US"}],"generatedAt":"2026-01-15T12:00:00Z","methodologyVersion":"example"},"schema":{"$ref":"#/components/schemas/GetChokepointDependenciesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetChokepointDependencies","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-chokepoint-history":{"get":{"description":"GetChokepointHistory returns transit-count history for a single chokepoint,\n loaded lazily on card expand. Keeps the status RPC compact (no 180-day\n history per chokepoint on every call).","operationId":"GetChokepointHistory","parameters":[{"description":"Chokepoint identifier whose transit history should be returned.","example":"suez","in":"query","name":"chokepointId","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"chokepointId":"suez","fetchedAt":"1717200000000","history":[{"capContainer":1.5,"capDryBulk":1.5,"capGeneralCargo":1.5,"capRoro":1.5,"capTanker":1.5}]},"schema":{"$ref":"#/components/schemas/GetChokepointHistoryResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetChokepointHistory","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-chokepoint-status":{"get":{"description":"GetChokepointStatus retrieves seeded chokepoint status. Empty chokepoints\n with upstream_unavailable=true means the seed snapshot is unavailable/\n degraded, not that there are confirmed zero chokepoints.","operationId":"GetChokepointStatus","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"chokepoints":[{"activeWarnings":1,"affectedRoutes":["example"],"aisDisruptions":1,"aisSnapshotAvailable":true,"congestionLevel":"example"}],"fetchedAt":"2026-01-15T12:00:00Z","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetChokepointStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetChokepointStatus","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-country-chokepoint-index":{"get":{"description":"GetCountryChokepointIndex returns per-chokepoint exposure scores for a country. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetCountryChokepointIndex","parameters":[{"description":"ISO 3166-1 alpha-2 country code (uppercase).","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"HS2 chapter (2-digit string). Defaults to \"27\" (energy/mineral fuels) when absent.","example":"27","in":"query","name":"hs2","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"exposures":[{"chokepointId":"suez","chokepointName":"WorldMonitor Analyst","coastSide":"example","exposureScore":42.5,"shockSupported":true}],"fetchedAt":"2026-01-15T12:00:00Z","hs2":"27","iso2":"US","primaryChokepointId":"suez"},"schema":{"$ref":"#/components/schemas/GetCountryChokepointIndexResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetCountryChokepointIndex","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-country-cost-shock":{"get":{"description":"GetCountryCostShock returns cost shock and war risk data for a country+chokepoint. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetCountryCostShock","parameters":[{"description":"ISO 3166-1 alpha-2 country code for the importing country.","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"Chokepoint identifier to model as disrupted.","example":"suez","in":"query","name":"chokepointId","required":true,"schema":{"type":"string"}},{"description":"HS2 chapter (default: \"27\")","example":"27","in":"query","name":"hs2","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"chokepointId":"suez","coverageDays":7,"fetchedAt":"2026-01-15T12:00:00Z","hasEnergyModel":true,"hs2":"27"},"schema":{"$ref":"#/components/schemas/GetCountryCostShockResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetCountryCostShock","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-country-products":{"get":{"description":"GetCountryProducts returns the seeded bilateral-HS4 import basket for a country. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetCountryProducts","parameters":[{"description":"ISO 3166-1 alpha-2 country code whose strategic products should be returned.","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"Optional requested heading; permits bounded recovery of a missing product.","example":"example","in":"query","name":"hs4","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"evidence":{"lastAttemptAt":"2026-01-15T12:00:00Z","lastAttemptState":"example","missingHs4s":["example"],"requestedHs4s":["example"],"source":"example"},"fetchedAt":"2026-01-15T12:00:00Z","iso2":"US","products":[{"denominatorBasis":"example","description":"Example WorldMonitor observation.","hs4":"example","topExporters":[{"netWeightKg":1.5,"partnerCode":1,"partnerIso2":"US","share":1.5,"value":1.5}],"totalValue":1}]},"schema":{"$ref":"#/components/schemas/GetCountryProductsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetCountryProducts","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-country-vulnerabilities":{"get":{"description":"GetCountryVulnerabilities returns the full per-commodity score evidence for one country. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetCountryVulnerabilities","parameters":[{"description":"Uppercase ISO 3166-1 alpha-2 country code.","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"country":"US","generatedAt":"2026-01-15T12:00:00Z","iso2":"US","methodologyVersion":"example","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetCountryVulnerabilitiesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetCountryVulnerabilities","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-critical-minerals":{"get":{"description":"GetCriticalMinerals returns critical-minerals supply indicators; upstream_unavailable is set when the source could not be reached.","operationId":"GetCriticalMinerals","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fetchedAt":"2026-01-15T12:00:00Z","minerals":[{"globalProduction":1.5,"hhi":1.5,"mineral":"example","riskRating":"example","topProducers":[{"country":"US","countryCode":"US","productionTonnes":1.5,"sharePct":1.5}]}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetCriticalMineralsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetCriticalMinerals","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-fuel-shortage-detail":{"get":{"description":"GetFuelShortageDetail returns a single shortage with full evidence\n bundle and citation timeline. Loaded lazily on drawer open.","operationId":"GetFuelShortageDetail","parameters":[{"description":"Fuel-shortage identifier to load with full evidence details.","example":"example-id","in":"query","name":"shortageId","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fetchedAt":"2026-01-15T12:00:00Z","shortage":{"causeChain":["example"],"country":"US","evidence":{"classifierConfidence":0.82,"classifierVersion":"example","evidenceSources":[{"authority":"example","date":"2026-01-15","sourceType":"all","title":"example","url":"https://example.com/worldmonitor"}],"firstRegulatorConfirmation":"example","lastEvidenceUpdate":"2026-01-15"},"firstSeen":"example","id":"example-id"},"unavailable":false},"schema":{"$ref":"#/components/schemas/GetFuelShortageDetailResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetFuelShortageDetail","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-mineral-production":{"get":{"description":"GetMineralProduction returns per-commodity mine and refinery country shares\n and HHI from the annual USGS MCS / BGS seed. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetMineralProduction","parameters":[{"description":"USGS commodity id or label (e.g. \"cobalt\"). Empty returns every commodity.","example":"example","in":"query","name":"commodity","required":false,"schema":{"type":"string"}},{"description":"ISO 3166-1 alpha-2. When set, countries[] is scoped to this producer and\n the countries portfolio is populated.","example":"US","in":"query","name":"iso2","required":false,"schema":{"type":"string"}},{"description":"\"mine\" or \"refinery\". Empty returns both stages when present.","example":"example","in":"query","name":"stage","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"commodities":[{"commodity":"example","commodityId":"example-id","mine":{"countries":[{"country":"US","estimated":true,"iso2":"US","output":1.5,"residual":true}],"hhi":1.5,"unit":"example","withheldCount":1,"worldTotal":1},"refinery":{"countries":[{"country":"US","estimated":true,"iso2":"US","output":1.5,"residual":true}],"hhi":1.5,"unit":"example","withheldCount":1,"worldTotal":1},"sources":["example"]}],"countries":[{"holdings":[{"commodity":"example","commodityId":"example-id","output":1.5,"share":1.5,"stage":"example"}],"iso2":"US"}],"dataYear":1,"fetchedAt":"2026-01-15T12:00:00Z","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetMineralProductionResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetMineralProduction","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-multi-sector-cost-shock":{"get":{"description":"GetMultiSectorCostShock returns per-sector cost-shock estimates for a\n country+chokepoint+closure-window. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetMultiSectorCostShock","parameters":[{"description":"ISO 3166-1 alpha-2 country code for the importing country.","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"Chokepoint identifier to model as disrupted.","example":"suez","in":"query","name":"chokepointId","required":true,"schema":{"type":"string"}},{"description":"Closure-window duration in days. Server clamps to [1, 365]. Defaults to 30.","example":7,"in":"query","name":"closureDays","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"chokepointId":"suez","closureDays":7,"fetchedAt":"2026-01-15T12:00:00Z","iso2":"US","sectors":[{"addedTransitDays":7,"closureDays":7,"freightAddedPctPerTon":1.5,"hs2":"27","hs2Label":"27"}]},"schema":{"$ref":"#/components/schemas/GetMultiSectorCostShockResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetMultiSectorCostShock","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-pipeline-detail":{"get":{"description":"GetPipelineDetail returns a single pipeline with full evidence bundle\n + auto-revision-log entries. Loaded lazily on drawer open.","operationId":"GetPipelineDetail","parameters":[{"description":"Pipeline identifier to load with full evidence details.","example":"transmed-pipeline","in":"query","name":"pipelineId","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fetchedAt":"2026-01-15T12:00:00Z","pipeline":{"capacityBcmYr":1.5,"capacityMbd":1.5,"commodityType":"oil","endPoint":{"lat":40.7128,"lon":-74.006},"evidence":{"classifierConfidence":0.82,"classifierVersion":"example","commercialState":"example","lastEvidenceUpdate":"2026-01-15","operatorStatement":{"date":"2026-01-15","text":"example","url":"https://example.com/worldmonitor"}}},"revisions":[{"classifierVersion":"example","date":"2026-01-15","fieldChanged":"example","newValue":"example","previousValue":"example"}],"unavailable":false},"schema":{"$ref":"#/components/schemas/GetPipelineDetailResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetPipelineDetail","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-route-explorer-lane":{"get":{"description":"GetRouteExplorerLane returns the primary maritime route, chokepoint exposures,\n bypass options with geometry, war risk, and static transit/freight estimates for\n a country pair + HS2 + cargo type. PRO-gated. Wraps the route-intelligence vendor\n endpoint's compute with browser-callable auth and adds fields needed by the\n Route Explorer UI. Requires entitlement tier \u003e= 1.","operationId":"GetRouteExplorerLane","parameters":[{"description":"ISO 3166-1 alpha-2 origin country code for the trade lane.","example":"US","in":"query","name":"fromIso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"ISO 3166-1 alpha-2 destination country code for the trade lane.","example":"US","in":"query","name":"toIso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"HS2 chapter code, e.g. \"27\", \"85\"","example":"27","in":"query","name":"hs2","required":true,"schema":{"type":"string"}},{"description":"One of: container, tanker, bulk, roro","example":"container","in":"query","name":"cargoType","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"bypassOptions":[{"addedCostMultiplier":75.25,"addedTransitDays":7,"fromPort":{"lat":40.7128,"lon":-74.006},"id":"example-id","name":"WorldMonitor Analyst"}],"cargoType":"container","chokepointExposures":[{"chokepointId":"suez","chokepointName":"WorldMonitor Analyst","exposurePct":1}],"disruptionScore":42.5,"estFreightUsdPerTeuRange":{"max":1,"min":1}},"schema":{"$ref":"#/components/schemas/GetRouteExplorerLaneResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetRouteExplorerLane","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-route-impact":{"get":{"description":"GetRouteImpact returns route-level trade exposure: lane value, primary exporter concentration, strategic products, resilience score, dependency flags, and Comtrade provenance. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetRouteImpact","parameters":[{"description":"ISO 3166-1 alpha-2 origin country code for the route.","example":"US","in":"query","name":"fromIso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"ISO 3166-1 alpha-2 destination country code for the route.","example":"US","in":"query","name":"toIso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"HS2 chapter code for the product sector on the route.","example":"27","in":"query","name":"hs2","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"comtradeSource":"example","dependencyFlags":["DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL"],"fetchedAt":"2026-01-15T12:00:00Z","hs2InSeededUniverse":true,"laneValueUsd":1.5},"schema":{"$ref":"#/components/schemas/GetRouteImpactResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetRouteImpact","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-sector-dependency":{"get":{"description":"GetSectorDependency returns dependency flags and risk profile for a country+HS2 sector. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetSectorDependency","parameters":[{"description":"ISO 3166-1 alpha-2 country code whose sector dependency should be analyzed.","example":"US","in":"query","name":"iso2","required":true,"schema":{"pattern":"^[A-Z]{2}$","type":"string"}},{"description":"HS2 chapter code, e.g. \"27\" (mineral fuels), \"85\" (electronics)","example":"27","in":"query","name":"hs2","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fetchedAt":"2026-01-15T12:00:00Z","flags":["DEPENDENCY_FLAG_SINGLE_SOURCE_CRITICAL"],"hasViableBypass":true,"hs2":"27","hs2Label":"27"},"schema":{"$ref":"#/components/schemas/GetSectorDependencyResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetSectorDependency","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-shipping-rates":{"get":{"description":"GetShippingRates returns current container shipping-rate indices; upstream_unavailable is set when the source could not be reached.","operationId":"GetShippingRates","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"fetchedAt":"2026-01-15T12:00:00Z","indices":[{"changePct":1.69,"currentValue":1072.16,"history":[{"date":"2026-01-15","value":1072.16}],"indexId":"CCFI","name":"CCFI - China Container Freight","periodChangeBasis":"publisher_reported","periodChangePct":1.69,"previousValue":1054.38,"priorPeriodDate":"2026-01-08","priorPeriodValue":1054.38,"spikeAlert":false,"unit":"index"},{"changePct":0,"currentValue":1972,"history":[{"date":"2026-01-15","value":1972}],"indexId":"BDI","name":"BDI - Baltic Dry Index","previousValue":1972,"spikeAlert":false,"unit":"index"}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetShippingRatesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetShippingRates","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-shipping-stress":{"get":{"description":"GetShippingStress returns Yahoo Finance quotes for the BDRY dry bulk ETF and four shipping carriers, plus a 0-100 stress score from their average daily move.","operationId":"GetShippingStress","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"carriers":[{"carrierType":"all","changePct":1.5,"name":"WorldMonitor Analyst","price":75.25,"sparkline":[1.5]}],"fetchedAt":1717200000000,"stressLevel":"example","stressScore":42.5,"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetShippingStressResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetShippingStress","tags":["SupplyChainService"]}},"/api/supply-chain/v1/get-storage-facility-detail":{"get":{"description":"GetStorageFacilityDetail returns a single facility with full evidence\n bundle + revision log. Loaded lazily on drawer open.","operationId":"GetStorageFacilityDetail","parameters":[{"description":"Storage facility identifier to load with full evidence details.","example":"rough-storage","in":"query","name":"facilityId","required":true,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"facility":{"capacityMb":1.5,"capacityMtpa":1.5,"capacityTwh":1.5,"country":"US","evidence":{"classifierConfidence":0.82,"classifierVersion":"example","commercialState":"example","fillDisclosed":true,"fillSource":"example"}},"fetchedAt":"2026-01-15T12:00:00Z","revisions":[{"classifierVersion":"example","date":"2026-01-15","fieldChanged":"example","newValue":"example","previousValue":"example"}],"unavailable":false},"schema":{"$ref":"#/components/schemas/GetStorageFacilityDetailResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetStorageFacilityDetail","tags":["SupplyChainService"]}},"/api/supply-chain/v1/list-energy-disruptions":{"get":{"description":"ListEnergyDisruptions returns the disruption event log for pipelines\n and storage facilities. Supports per-asset or per-asset-type filtering\n so panel drawers can fetch a scoped timeline without pulling the\n full registry.","operationId":"ListEnergyDisruptions","parameters":[{"description":"Filter to one asset. Omit for all. When set, also narrows to the\n matching asset_type if provided.","example":"asset-example-1","in":"query","name":"assetId","required":false,"schema":{"type":"string"}},{"description":"Filter to one asset type. Accepts: \"pipeline\" | \"storage\".","example":"pipeline","in":"query","name":"assetType","required":false,"schema":{"type":"string"}},{"description":"If true, only return events with endAt empty (still ongoing).","example":true,"in":"query","name":"ongoingOnly","required":false,"schema":{"type":"boolean"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"classifierVersion":"example","events":[{"assetId":"asset-example-1","assetType":"pipeline","capacityOfflineBcmYr":1.5,"capacityOfflineMbd":1.5,"causeChain":["example"]}],"fetchedAt":"2026-01-15T12:00:00Z","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/ListEnergyDisruptionsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListEnergyDisruptions","tags":["SupplyChainService"]}},"/api/supply-chain/v1/list-fuel-shortages":{"get":{"description":"ListFuelShortages returns the global fuel-shortage alert registry.\n Curated-only: severity (\"confirmed\" | \"watch\") is a row field authored\n at curation time, not a client-side derivation. Free tier.","operationId":"ListFuelShortages","parameters":[{"description":"Filter to one ISO 3166-1 alpha-2 country. Omit for global.","example":"US","in":"query","name":"country","required":false,"schema":{"type":"string"}},{"description":"Filter to one product. Accepts: \"petrol\" | \"diesel\" | \"jet\" | \"heating_oil\".\n Omit for all products.","example":"diesel","in":"query","name":"product","required":false,"schema":{"type":"string"}},{"description":"Filter to one severity. Accepts: \"confirmed\" | \"watch\". Omit for both.","example":"watch","in":"query","name":"severity","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"classifierVersion":"example","fetchedAt":"2026-01-15T12:00:00Z","shortages":[{"causeChain":["example"],"country":"US","evidence":{"classifierConfidence":0.82,"classifierVersion":"example","evidenceSources":[{"authority":"example","date":"2026-01-15","sourceType":"all","title":"example","url":"https://example.com/worldmonitor"}],"firstRegulatorConfirmation":"example","lastEvidenceUpdate":"2026-01-15"},"firstSeen":"example","id":"example-id"}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/ListFuelShortagesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListFuelShortages","tags":["SupplyChainService"]}},"/api/supply-chain/v1/list-pipelines":{"get":{"description":"ListPipelines returns the curated oil \u0026 gas pipeline registry for the\n Energy Atlas PathLayer. Public badges are DERIVED from evidence bundles\n server-side and versioned (classifier_version). Free-tier; see\n docs/methodology/pipelines.mdx for data + classifier spec.","operationId":"ListPipelines","parameters":[{"description":"Filter to one commodity. Omit (or pass empty) to receive both.","example":"oil","in":"query","name":"commodityType","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"classifierVersion":"example","fetchedAt":"2026-01-15T12:00:00Z","pipelines":[{"capacityBcmYr":1.5,"capacityMbd":1.5,"commodityType":"oil","endPoint":{"lat":40.7128,"lon":-74.006},"evidence":{"classifierConfidence":0.82,"classifierVersion":"example","commercialState":"example","lastEvidenceUpdate":"2026-01-15","operatorStatement":{"date":"2026-01-15","text":"example","url":"https://example.com/worldmonitor"}}}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/ListPipelinesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListPipelines","tags":["SupplyChainService"]}},"/api/supply-chain/v1/list-storage-facilities":{"get":{"description":"ListStorageFacilities returns the curated strategic storage registry\n (UGS + SPR + LNG + crude tank farms) for the Energy Atlas DeckGL\n ScatterplotLayer. Public badges are DERIVED from evidence bundles\n server-side and versioned (classifier_version). Free-tier; see\n docs/methodology/storage.mdx.","operationId":"ListStorageFacilities","parameters":[{"description":"Filter to one facility type. Accepts:\n   \"ugs\" | \"spr\" | \"lng_export\" | \"lng_import\" | \"crude_tank_farm\"\n Omit (or pass empty) to receive all types.","example":"ugs","in":"query","name":"facilityType","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"classifierVersion":"example","facilities":[{"capacityMb":1.5,"capacityMtpa":1.5,"capacityTwh":1.5,"country":"US","evidence":{"classifierConfidence":0.82,"classifierVersion":"example","commercialState":"example","fillDisclosed":true,"fillSource":"example"}}],"fetchedAt":"2026-01-15T12:00:00Z","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/ListStorageFacilitiesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListStorageFacilities","tags":["SupplyChainService"]}},"/api/supply-chain/v1/list-vulnerability-rankings":{"get":{"description":"ListVulnerabilityRankings returns a bounded global ranking with optional filters. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"ListVulnerabilityRankings","parameters":[{"description":"Optional stable commodity mapping identifier.","example":"crude_oil","in":"query","name":"commodityId","required":false,"schema":{"pattern":"^$|^[a-z0-9_\\-]+$","type":"string"}},{"description":"Optional score band: low, moderate, high, or critical.","example":"high","in":"query","name":"band","required":false,"schema":{"pattern":"^$|^(low|moderate|high|critical)$","type":"string"}},{"description":"Optional evidence state: ok, insufficient_data, or stale_input.","example":"ok","in":"query","name":"state","required":false,"schema":{"pattern":"^$|^(ok|insufficient_data|stale_input)$","type":"string"}},{"description":"Maximum rows to return; zero uses the server default and the maximum is 25.","example":25,"in":"query","name":"pageSize","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"generatedAt":"2026-01-15T12:00:00Z","methodologyVersion":"example","upstreamUnavailable":false,"vulnerabilities":[{"band":"high","commodity":"example","commodityId":"crude_oil","components":{"buffer":{"inputs":[{"detail":"example","fetchedAt":"2026-01-15T12:00:00Z","sourceKey":"example","sourceName":"WorldMonitor Analyst","sourceUrl":"https://example.com/worldmonitor"}],"kind":"example","state":"ok","vulnerability":1.5},"sourceConcentration":{"coverage":"example","importHhi":1.5,"inputs":[{"detail":"example","fetchedAt":"2026-01-15T12:00:00Z","sourceKey":"example","sourceName":"WorldMonitor Analyst","sourceUrl":"https://example.com/worldmonitor"}],"mineHhi":1.5,"productionCoverage":"diesel"},"transitExposure":{"chokepoints":[{"id":"example-id","inputs":[],"name":"WorldMonitor Analyst","status":"example","transitShare":1.5}],"value":1.5}},"countryIso2":"US"}]},"schema":{"$ref":"#/components/schemas/ListVulnerabilityRankingsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"PRO entitlement access denied.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"ListVulnerabilityRankings","tags":["SupplyChainService"]}}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]}],"servers":[{"url":"https://api.worldmonitor.app"}]}