HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/api/TradeService.openapi.json

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
{"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"},"ComtradeFlowRecord":{"description":"ComtradeFlowRecord is a single bilateral commodity flow record.","properties":{"cmdCode":{"description":"HS commodity code.","type":"string"},"cmdDesc":{"description":"Commodity description.","type":"string"},"isAnomaly":{"description":"True if the YoY change exceeds the anomaly threshold (30%).","type":"boolean"},"netWeightKg":{"description":"Net weight in kg.","format":"double","type":"number"},"partnerCode":{"description":"Partner country code (\"000\" = world total).","type":"string"},"partnerName":{"description":"Partner country name.","type":"string"},"reporterCode":{"description":"UN Comtrade reporter code.","type":"string"},"reporterName":{"description":"Reporter country name.","type":"string"},"tradeValueUsd":{"description":"Trade value in USD.","format":"double","type":"number"},"year":{"description":"Reporting year.","format":"int32","type":"integer"},"yoyChange":{"description":"Year-over-year change (ratio, e.g. 0.35 = +35%).","format":"double","type":"number"}},"type":"object"},"CustomsRevenueMonth":{"description":"Monthly US customs duties revenue from Treasury MTS data.","properties":{"calendarMonth":{"format":"int32","type":"integer"},"calendarYear":{"format":"int32","type":"integer"},"fiscalYear":{"format":"int32","type":"integer"},"fytdAmountBillions":{"format":"double","type":"number"},"monthlyAmountBillions":{"format":"double","type":"number"},"recordDate":{"type":"string"}},"type":"object"},"EffectiveTariffRate":{"description":"Current effective tariff estimate for countries with coverage beyond WTO MFN baselines.","properties":{"observationPeriod":{"description":"Human-readable observation period (for example \"December 2025\").","type":"string"},"sourceName":{"description":"Source name for the effective-rate estimate.","type":"string"},"sourceUrl":{"description":"Canonical source URL for the estimate/methodology.","type":"string"},"tariffRate":{"description":"Effective tariff rate (percentage).","format":"double","type":"number"},"updatedAt":{"description":"ISO 8601 date when the source page was last updated, if known.","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"},"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"},"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"},"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"},"GetBilateralTariffRequest":{"description":"Applied tariff on one HS6 product between two countries, from UNCTAD TRAINS\n via World Bank WITS. Excludes unilateral duties (Section 301/232, IEEPA,\n AD/CVD, safeguards).","properties":{"hsCode":{"description":"Six-digit HS subheading (\"870323\").","pattern":"^[0-9]{6}$","type":"string"},"partnerCountry":{"description":"Exporter, 3-digit UN M49 (\"484\"). \"000\" returns MFN only.","pattern":"^[0-9]{3}$","type":"string"},"reportingCountry":{"description":"Importer, 3-digit UN M49 (\"840\"). EU members use the EU schedule.","pattern":"^[0-9]{3}$","type":"string"},"year":{"description":"Tariff year; 0 = latest year TRAINS lists for the importer.","format":"int32","maximum":2100,"minimum":0,"type":"integer"}},"required":["reportingCountry","partnerCountry","hsCode"],"type":"object"},"GetBilateralTariffResponse":{"description":"Applied tariff on one HS6 product between two countries.","properties":{"appliedRate":{"$ref":"#/components/schemas/TariffRateDetail"},"basis":{"description":"Source of applied_rate.","enum":["APPLIED_TARIFF_BASIS_UNSPECIFIED","APPLIED_TARIFF_BASIS_PREFERENTIAL","APPLIED_TARIFF_BASIS_MFN","APPLIED_TARIFF_BASIS_MFN_PREFERENCES_NOT_REPORTED"],"type":"string"},"filingReporter":{"description":"Reporter code queried: \"918\" for EU members.","type":"string"},"groupPreferences":{"items":{"$ref":"#/components/schemas/GroupTariffPreference"},"type":"array"},"hsCode":{"description":"HS6 code, as requested.","type":"string"},"mfnAveRate":{"$ref":"#/components/schemas/TariffRateDetail"},"mfnRate":{"$ref":"#/components/schemas/TariffRateDetail"},"nomenclature":{"description":"HS edition the importer filed in (\"H5\" = HS 2017).","type":"string"},"partnerCountry":{"description":"Exporter code, as requested.","type":"string"},"preferentialRate":{"$ref":"#/components/schemas/TariffRateDetail"},"reportingCountry":{"description":"Importer code, as requested.","type":"string"},"source":{"description":"Data source.","type":"string"},"sourceUrl":{"description":"WITS query behind the rows.","type":"string"},"unavailableReason":{"description":"Why no rate was served. NOT_COVERED is final; UPSTREAM_UNAVAILABLE is a fault.","enum":["BILATERAL_TARIFF_UNAVAILABLE_REASON_UNSPECIFIED","BILATERAL_TARIFF_UNAVAILABLE_REASON_INVALID_REQUEST","BILATERAL_TARIFF_UNAVAILABLE_REASON_NOT_COVERED","BILATERAL_TARIFF_UNAVAILABLE_REASON_UPSTREAM_UNAVAILABLE"],"type":"string"},"upstreamUnavailable":{"description":"True on a fault, false on a coverage answer.","type":"boolean"},"year":{"description":"Year served; 0 when none.","format":"int32","type":"integer"}},"type":"object"},"GetCustomsRevenueRequest":{"type":"object"},"GetCustomsRevenueResponse":{"properties":{"fetchedAt":{"type":"string"},"months":{"items":{"$ref":"#/components/schemas/CustomsRevenueMonth"},"type":"array"},"upstreamUnavailable":{"type":"boolean"}},"type":"object"},"GetTariffTrendsRequest":{"description":"Request for tariff timeseries data.\n\n Without partner_country or product_sector, this serves the reporter's WTO MFN\n applied average over all products (indicator TP_A_0010), seeded on Railway; a\n reporter outside the seed is reported as uncovered, not fetched.\n\n With a partner other than World, or a product group other than all, it serves\n the reporter's effectively applied tariff (preferences included) on those\n goods, from World Bank WITS (UNCTAD TRAINS), fetched on demand and cached.\n Both are schedule rates: neither includes unilateral duties such as Section\n 301 (see get-us-import-duty).","properties":{"partnerCountry":{"description":"Exporting partner, 3-digit UN M49 code (\"000\" = World). Empty or \"000\"\n with no product_sector selects the MFN series.","pattern":"^([0-9]{3})?$","type":"string"},"productSector":{"description":"WITS product group: an HS section such as \"84-85_MachElec\" or \"50-63_TextCloth\",\n or \"AgrRaw\", \"Chemical\", \"Food\", \"Fuels\", \"manuf\", \"OresMtls\", \"Textiles\",\n \"Transp\" (case-insensitive). Empty or \"all\" means all products. Other values\n are answered NOT_COVERED.","pattern":"^([a-zA-Z0-9_-]{0,16})?$","type":"string"},"reportingCountry":{"description":"WTO member code of reporting country, as a 3-digit UN M49 code\n (for example \"840\" = United States). Empty selects the \"840\" default.","pattern":"^([0-9]{3})?$","type":"string"},"years":{"description":"Number of years to look back from the newest seeded year, inclusive of\n both endpoints (years = 10 returns 11 calendar years). 0 selects the\n default of 10; the maximum is 30, which is the full seeded window.","format":"int32","maximum":30,"minimum":0,"type":"integer"}},"type":"object"},"GetTariffTrendsResponse":{"description":"Response containing tariff trend datapoints.","properties":{"coverageEndYear":{"format":"int32","type":"integer"},"coverageStartYear":{"description":"First and last calendar year covered by `datapoints`. Both are 0 when no\n datapoints are returned. This is the effective window after slicing to\n `years`, which may be narrower than the requested lookback when the seed\n starts later.","format":"int32","type":"integer"},"datapoints":{"items":{"$ref":"#/components/schemas/TariffDataPoint"},"type":"array"},"effectiveTariffRate":{"$ref":"#/components/schemas/EffectiveTariffRate"},"fetchedAt":{"description":"ISO 8601 time the data was fetched from WTO or WITS.","type":"string"},"unavailableReason":{"description":"TariffTrendUnavailableReason says why no datapoints were returned. The\n distinction that matters is NOT_COVERED — a contract answer, nothing is\n broken and a retry cannot help — against every other member, which names a\n fault.","enum":["TARIFF_TREND_UNAVAILABLE_REASON_UNSPECIFIED","TARIFF_TREND_UNAVAILABLE_REASON_INVALID_REQUEST","TARIFF_TREND_UNAVAILABLE_REASON_NOT_COVERED","TARIFF_TREND_UNAVAILABLE_REASON_SEED_MISSING","TARIFF_TREND_UNAVAILABLE_REASON_COVERAGE_UNKNOWN","TARIFF_TREND_UNAVAILABLE_REASON_CACHE_UNAVAILABLE","TARIFF_TREND_UNAVAILABLE_REASON_UPSTREAM_UNAVAILABLE"],"type":"string"},"upstreamUnavailable":{"description":"True when datapoints could not be served because of a fault — a seeded\n reporter whose cache entry is gone, or a cache read that failed. False when\n datapoints are served AND when the request names a combination that is\n simply not part of seeded coverage, which is a contract answer rather than\n an outage.","type":"boolean"}},"type":"object"},"GetTradeBarriersRequest":{"description":"Request for SPS/TBT trade barrier notifications.","properties":{"countries":{"items":{"description":"WTO member codes to filter by. Empty = all.\n Accepted but currently ignored; no-op until this handler supports the parameter.","type":"string"},"type":"array"},"limit":{"description":"Max results to return (server caps at 100).","format":"int32","type":"integer"},"measureType":{"description":"Filter by measure type: \"SPS\", \"TBT\", or empty for both.\n Accepted but currently ignored; no-op until this handler supports the parameter.","type":"string"}},"type":"object"},"GetTradeBarriersResponse":{"description":"Response containing trade barrier notifications.","properties":{"barriers":{"items":{"$ref":"#/components/schemas/TradeBarrier"},"type":"array"},"fetchedAt":{"description":"ISO 8601 timestamp when data was fetched from WTO.","type":"string"},"upstreamUnavailable":{"description":"True if upstream fetch failed and results may be stale/empty.","type":"boolean"}},"type":"object"},"GetTradeFlowsRequest":{"description":"Request for merchandise trade flow data, reporter versus World.\n\n Coverage is seed-backed: Railway pre-fetches a fixed set of\n reporter/partner pairs from WTO and this API serves slices of that history.\n It never calls WTO per request, so a well-formed combination outside the\n seeded set is reported as uncovered (see GetTradeFlowsResponse.\n unavailable_reason) rather than fetched on demand.","properties":{"partnerCountry":{"description":"WTO member code of partner country, as a 3-digit UN M49 code.\n Empty selects \"000\" = World, which is the only partner currently covered:\n the WTO indicators behind these flows (ITS_MTV_AX, ITS_MTV_AM) publish a\n World total and answer 204 for every named partner. Any other code is\n accepted by validation and answered with unavailable_reason\n TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED, so coverage can widen without a\n contract change.","pattern":"^([0-9]{3})?$","type":"string"},"reportingCountry":{"description":"WTO member code of reporting country, as a 3-digit UN M49 code\n (for example \"840\" = United States). Empty selects the \"840\" default.","pattern":"^([0-9]{3})?$","type":"string"},"years":{"description":"Number of years to look back from the newest seeded year, inclusive of\n both endpoints (years = 10 returns 11 calendar years). 0 selects the\n default of 10; the maximum is 30, which is the full seeded window.","format":"int32","maximum":30,"minimum":0,"type":"integer"}},"type":"object"},"GetTradeFlowsResponse":{"description":"Response containing trade flow records.","properties":{"coverageEndYear":{"format":"int32","type":"integer"},"coverageStartYear":{"description":"First and last calendar year covered by `flows`. Both are 0 when no flows\n are returned. This is the effective window after slicing to `years`, which\n may be narrower than the requested lookback when the seed starts later.","format":"int32","type":"integer"},"fetchedAt":{"description":"ISO 8601 timestamp when data was fetched from WTO.","type":"string"},"flows":{"items":{"$ref":"#/components/schemas/TradeFlowRecord"},"type":"array"},"unavailableReason":{"description":"TradeFlowUnavailableReason says why no rows were returned. The distinction\n that matters is NOT_COVERED — a contract answer, nothing is broken and a\n retry cannot help — against every other member, which names a fault.","enum":["TRADE_FLOW_UNAVAILABLE_REASON_UNSPECIFIED","TRADE_FLOW_UNAVAILABLE_REASON_INVALID_REQUEST","TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED","TRADE_FLOW_UNAVAILABLE_REASON_SEED_MISSING","TRADE_FLOW_UNAVAILABLE_REASON_COVERAGE_UNKNOWN","TRADE_FLOW_UNAVAILABLE_REASON_CACHE_UNAVAILABLE"],"type":"string"},"upstreamUnavailable":{"description":"True when flows could not be served because of a fault — a seeded pair\n whose cache entry is gone, or a cache read that failed. False when flows\n are served AND when the request names a combination that is simply not\n part of seeded coverage, which is a contract answer rather than an outage.","type":"boolean"}},"type":"object"},"GetTradeRestrictionsRequest":{"description":"Request for quantitative restriction data.","properties":{"countries":{"items":{"description":"WTO member codes to filter by. Empty = all.\n Accepted but currently ignored; no-op until this handler supports the parameter.","type":"string"},"type":"array"},"limit":{"description":"Max results to return (server caps at 100).","format":"int32","type":"integer"}},"type":"object"},"GetTradeRestrictionsResponse":{"description":"Response containing trade restrictions and fetch metadata.","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when data was fetched from WTO.","type":"string"},"restrictions":{"items":{"$ref":"#/components/schemas/TradeRestriction"},"type":"array"},"upstreamUnavailable":{"description":"True if upstream fetch failed and results may be stale/empty.","type":"boolean"}},"type":"object"},"GetUsImportDutyRequest":{"description":"Current US duty on a product from one country: HTS columns plus the\n chapter 99 Section 301 and 232 duties. IEEPA duties are not collected\n since 2026-02-24 and are not reported. Excludes AD/CVD.","properties":{"hsCode":{"description":"HTS code: 6, 8 or 10 digits, no dots (\"870323\").","pattern":"^[0-9]{6}([0-9]{2}){0,2}$","type":"string"},"partnerCountry":{"description":"Exporter, 3-digit UN M49 (\"156\").","pattern":"^[0-9]{3}$","type":"string"}},"required":["hsCode","partnerCountry"],"type":"object"},"GetUsImportDutyResponse":{"description":"Current US duty on a product from one country.","properties":{"additionalDutiesLoaded":{"description":"False when the chapter 99 index was unavailable.","type":"boolean"},"hsCode":{"description":"HTS code, as requested.","type":"string"},"htsRelease":{"description":"HTS release of the chapter 99 index (\"2026HTSRev21\").","type":"string"},"lines":{"items":{"$ref":"#/components/schemas/UsTariffLine"},"type":"array"},"partnerCountry":{"description":"Exporter code, as requested.","type":"string"},"source":{"description":"Data source.","type":"string"},"sourceUrl":{"description":"HTS search page for the code.","type":"string"},"unavailableReason":{"description":"Why no line was served. NOT_COVERED is final; UPSTREAM_UNAVAILABLE is a fault.","enum":["US_IMPORT_DUTY_UNAVAILABLE_REASON_UNSPECIFIED","US_IMPORT_DUTY_UNAVAILABLE_REASON_INVALID_REQUEST","US_IMPORT_DUTY_UNAVAILABLE_REASON_NOT_COVERED","US_IMPORT_DUTY_UNAVAILABLE_REASON_UPSTREAM_UNAVAILABLE"],"type":"string"},"upstreamUnavailable":{"description":"True on a fault, false on a coverage answer.","type":"boolean"}},"type":"object"},"GroupTariffPreference":{"description":"Preference granted to a partner group. Membership is not resolved.","properties":{"groupCode":{"description":"WITS group code (\"A41\").","type":"string"},"groupName":{"description":"WITS group name; empty when WITS has none.","type":"string"},"rate":{"$ref":"#/components/schemas/TariffRateDetail"}},"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"},"ListComtradeFlowsRequest":{"description":"ListComtradeFlowsRequest filters strategic commodity trade flows.","properties":{"anomaliesOnly":{"description":"If true, only return flows with a year-over-year change exceeding 30%.","type":"boolean"},"cmdCode":{"description":"HS commodity code (e.g. \"2709\" = crude oil). Empty returns all commodities.","type":"string"},"reporterCode":{"description":"UN Comtrade reporter code (e.g. \"842\" = US, \"156\" = China). Empty returns all reporters.","type":"string"}},"type":"object"},"ListComtradeFlowsResponse":{"description":"ListComtradeFlowsResponse contains strategic commodity trade flows.","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when data was seeded.","type":"string"},"flows":{"items":{"$ref":"#/components/schemas/ComtradeFlowRecord"},"type":"array"},"upstreamUnavailable":{"description":"True if seeded data is missing or stale.","type":"boolean"}},"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"},"TariffDataPoint":{"description":"One year of a reporter's average tariff: the WTO MFN all-products average\n (TP_A_0010), or a WITS applied average for a partner and/or product group.","properties":{"boundRate":{"description":"WTO bound tariff rate (percentage). Reserved: always 0.","format":"double","type":"number"},"indicatorCode":{"description":"Indicator: TP_A_0010 (WTO) or AHS-SMPL-AVRG (WITS).","type":"string"},"partnerCountry":{"description":"Partner: \"World\", or the requested 3-digit code.","type":"string"},"productSector":{"description":"\"All products\", or the requested WITS product group.","type":"string"},"reportingCountry":{"description":"WTO member code of reporting country.","type":"string"},"tariffRate":{"description":"Simple average applied tariff (percentage): MFN on TP_A_0010, effectively\n applied on AHS-SMPL-AVRG.","format":"double","type":"number"},"weightedRate":{"description":"Import-weighted average (percentage). WITS series only; 0 on TP_A_0010.","format":"double","type":"number"},"year":{"description":"Year of observation.","format":"int32","type":"integer"}},"type":"object"},"TariffRateDetail":{"description":"Simple average across the importer's national tariff lines, in percent.","properties":{"maxRate":{"description":"Highest line rate.","format":"double","type":"number"},"minRate":{"description":"Lowest line rate.","format":"double","type":"number"},"nonAdValoremLines":{"description":"Specific or compound lines, excluded from the average.","format":"int32","type":"integer"},"rate":{"description":"Average ad valorem rate.","format":"double","type":"number"},"tariffLines":{"description":"National tariff lines.","format":"int32","type":"integer"}},"type":"object"},"TradeBarrier":{"description":"SPS or TBT trade barrier notification.","properties":{"dateDistributed":{"description":"ISO 8601 date when notification was distributed.","type":"string"},"id":{"description":"Unique barrier notification identifier.","type":"string"},"measureType":{"description":"Measure classification: \"SPS\" or \"TBT\".","type":"string"},"notifyingCountry":{"description":"Country that notified the measure.","type":"string"},"objective":{"description":"Stated objective of the measure.","type":"string"},"productDescription":{"description":"Product description or affected goods.","type":"string"},"sourceUrl":{"description":"WTO source document URL (must be http/https protocol).","type":"string"},"status":{"description":"Status of the notification.","type":"string"},"title":{"description":"Title of the notification.","type":"string"}},"type":"object"},"TradeFlowRecord":{"description":"Bilateral trade flow record for a reporting-partner pair.","properties":{"exportValueUsd":{"description":"Merchandise export value in millions USD.","format":"double","type":"number"},"importValueUsd":{"description":"Merchandise import value in millions USD.","format":"double","type":"number"},"partnerCountry":{"description":"WTO member code of partner country.","type":"string"},"productSector":{"description":"Product sector or HS chapter.","type":"string"},"reportingCountry":{"description":"WTO member code of reporting country.","type":"string"},"year":{"description":"Year of observation.","format":"int32","type":"integer"},"yoyExportChange":{"description":"Year-over-year export change (percentage).","format":"double","type":"number"},"yoyImportChange":{"description":"Year-over-year import change (percentage).","format":"double","type":"number"}},"type":"object"},"TradeRestriction":{"description":"Quantitative restriction or export control measure notified to WTO.","properties":{"affectedCountry":{"description":"Country affected by the restriction.","type":"string"},"description":{"description":"Human-readable description of the measure.","type":"string"},"id":{"description":"Unique restriction identifier from WTO.","type":"string"},"measureType":{"description":"Measure classification: \"QR\", \"EXPORT_BAN\", \"IMPORT_BAN\", \"LICENSING\".","type":"string"},"notifiedAt":{"description":"ISO 8601 date when measure was notified.","type":"string"},"productSector":{"description":"Product sector or HS chapter description.","type":"string"},"reportingCountry":{"description":"ISO 3166-1 alpha-3 or WTO member code of reporting country.","type":"string"},"sourceUrl":{"description":"WTO source document URL (must be http/https protocol).","type":"string"},"status":{"description":"Current status: \"IN_FORCE\", \"TERMINATED\", \"NOTIFIED\".","type":"string"}},"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"},"UsAdditionalDuty":{"description":"A chapter 99 duty on one line.","properties":{"addedRate":{"description":"Percentage points added to the base rate.","format":"double","type":"number"},"authority":{"description":"Legal authority of a chapter 99 duty.","enum":["US_DUTY_AUTHORITY_UNSPECIFIED","US_DUTY_AUTHORITY_SECTION_301","US_DUTY_AUTHORITY_SECTION_232","US_DUTY_AUTHORITY_COLUMN_2"],"type":"string"},"condition":{"description":"What decides the status.","type":"string"},"effectiveFrom":{"description":"First day in force, when dated.","type":"string"},"heading":{"description":"Chapter 99 heading (\"9903.88.03\").","type":"string"},"legalNote":{"description":"Chapter 99 U.S. note listing the products.","type":"string"},"program":{"description":"Action name (\"China List 3\").","type":"string"},"status":{"description":"Whether a chapter 99 duty applies to this line and partner.","enum":["US_ADDITIONAL_DUTY_STATUS_UNSPECIFIED","US_ADDITIONAL_DUTY_STATUS_APPLIES","US_ADDITIONAL_DUTY_STATUS_CONDITIONAL","US_ADDITIONAL_DUTY_STATUS_EXEMPT","US_ADDITIONAL_DUTY_STATUS_SCHEDULED"],"type":"string"},"topUpTo":{"description":"Combined rate the base is raised to; 0 when none.","format":"double","type":"number"}},"type":"object"},"UsTariffLine":{"description":"One 8-digit HTS line.","properties":{"additionalDuties":{"items":{"$ref":"#/components/schemas/UsAdditionalDuty"},"type":"array"},"baseAdValorem":{"description":"Base rate in percent; 0 when not ad valorem.","format":"double","type":"number"},"baseNonAdValorem":{"description":"True when the base rate is specific or compound.","type":"boolean"},"baseRate":{"description":"Base rate text.","type":"string"},"basis":{"description":"Column the base rate comes from.","enum":["US_DUTY_BASIS_UNSPECIFIED","US_DUTY_BASIS_MFN","US_DUTY_BASIS_PREFERENTIAL","US_DUTY_BASIS_COLUMN_2"],"type":"string"},"column2Rate":{"description":"Column 2.","type":"string"},"description":{"description":"Article description.","type":"string"},"estimateComplete":{"description":"False when the base is not ad valorem or a duty is not APPLIES/EXEMPT.","type":"boolean"},"estimatedRate":{"description":"Base plus APPLIES duties, in percent.","format":"double","type":"number"},"generalRate":{"description":"Column 1 General.","type":"string"},"htsCode":{"description":"8-digit HTS line (\"8703.23.01\").","type":"string"},"preferenceProgram":{"description":"Special program applied (\"S\" = USMCA).","type":"string"},"specialRate":{"description":"Column 1 Special, with program codes.","type":"string"},"unresolvedPrograms":{"items":{"description":"Special programs whose partner eligibility is not resolved.","type":"string"},"type":"array"}},"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"}},"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":"TradeService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/trade/v1/get-bilateral-tariff":{"get":{"description":"Applied tariff on one HS6 product between two countries (UNCTAD TRAINS). PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetBilateralTariff","parameters":[{"description":"Importer, 3-digit UN M49 (\"840\"). EU members use the EU schedule.","example":"840","in":"query","name":"reporting_country","required":true,"schema":{"pattern":"^[0-9]{3}$","type":"string"}},{"description":"Exporter, 3-digit UN M49 (\"484\"). \"000\" returns MFN only.","example":"484","in":"query","name":"partner_country","required":true,"schema":{"pattern":"^[0-9]{3}$","type":"string"}},{"description":"Six-digit HS subheading (\"870323\").","example":"870323","in":"query","name":"hs_code","required":true,"schema":{"pattern":"^[0-9]{6}$","type":"string"}},{"description":"Tariff year; 0 = latest year TRAINS lists for the importer.","example":2021,"in":"query","name":"year","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":{"appliedRate":{"maxRate":0,"minRate":0,"nonAdValoremLines":0,"rate":0,"tariffLines":1},"basis":"APPLIED_TARIFF_BASIS_PREFERENTIAL","filingReporter":"840","groupPreferences":[{"groupCode":"P22","groupName":"North American Free Trade Agreement (NAFTA)","rate":{"maxRate":0,"minRate":0,"nonAdValoremLines":0,"rate":0,"tariffLines":1}}],"hsCode":"870323","mfnRate":{"maxRate":2.5,"minRate":2.5,"nonAdValoremLines":0,"rate":2.5,"tariffLines":1},"nomenclature":"H5","partnerCountry":"484","preferentialRate":{"maxRate":0,"minRate":0,"nonAdValoremLines":0,"rate":0,"tariffLines":1},"reportingCountry":"840","source":"UNCTAD TRAINS via World Bank WITS","sourceUrl":"https://wits.worldbank.org/API/V1/SDMX/V21/datasource/TRN/reporter/840/partner/all/product/870323/year/2021/datatype/reported","upstreamUnavailable":false,"year":2021},"schema":{"$ref":"#/components/schemas/GetBilateralTariffResponse"}}},"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":"GetBilateralTariff","tags":["TradeService"]}},"/api/trade/v1/get-customs-revenue":{"get":{"description":"GetCustomsRevenue returns monthly and fiscal-year-to-date US customs duty receipts in billions from the Monthly Treasury Statement, up to 50 recent months.","operationId":"GetCustomsRevenue","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","months":[{"calendarMonth":1,"calendarYear":1,"fiscalYear":1,"fytdAmountBillions":1.5,"monthlyAmountBillions":1.5}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetCustomsRevenueResponse"}}},"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":"GetCustomsRevenue","tags":["TradeService"]}},"/api/trade/v1/get-tariff-trends":{"get":{"description":"Average applied tariff timeseries for one reporting economy: the MFN rate\n over all products, or with a partner and/or product group the effectively\n applied rate on those imports. Not an HS-line rate. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetTariffTrends","parameters":[{"description":"WTO member code of reporting country, as a 3-digit UN M49 code\n (for example \"840\" = United States). Empty selects the \"840\" default.","example":"840","in":"query","name":"reporting_country","required":false,"schema":{"pattern":"^([0-9]{3})?$","type":"string"}},{"description":"Exporting partner, 3-digit UN M49 code (\"000\" = World). Empty or \"000\"\n with no product_sector selects the MFN series.","example":"156","in":"query","name":"partner_country","required":false,"schema":{"pattern":"^([0-9]{3})?$","type":"string"}},{"description":"WITS product group: an HS section such as \"84-85_MachElec\" or \"50-63_TextCloth\",\n or \"AgrRaw\", \"Chemical\", \"Food\", \"Fuels\", \"manuf\", \"OresMtls\", \"Textiles\",\n \"Transp\" (case-insensitive). Empty or \"all\" means all products. Other values\n are answered NOT_COVERED.","example":"all","in":"query","name":"product_sector","required":false,"schema":{"pattern":"^([a-zA-Z0-9_-]{0,16})?$","type":"string"}},{"description":"Number of years to look back from the newest seeded year, inclusive of\n both endpoints (years = 10 returns 11 calendar years). 0 selects the\n default of 10; the maximum is 30, which is the full seeded window.","example":1,"in":"query","name":"years","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":{"coverageEndYear":1,"coverageStartYear":1,"datapoints":[{"boundRate":0,"indicatorCode":"example","partnerCountry":"World","productSector":"All products","reportingCountry":"840"}],"effectiveTariffRate":{"observationPeriod":"daily","sourceName":"WorldMonitor Analyst","sourceUrl":"https://example.com/worldmonitor","tariffRate":75.25,"updatedAt":"2026-01-15"},"fetchedAt":"2026-01-15T12:00:00Z"},"schema":{"$ref":"#/components/schemas/GetTariffTrendsResponse"}}},"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":"GetTariffTrends","tags":["TradeService"]}},"/api/trade/v1/get-trade-barriers":{"get":{"description":"GetTradeBarriers returns each WTO reporter's agricultural versus non-agricultural tariff gap, largest first, up to 100 economies; a missing series counts as 0%.","operationId":"GetTradeBarriers","parameters":[{"description":"WTO member codes to filter by. Empty = all.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":["840"],"explode":true,"in":"query","name":"countries","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Filter by measure type: \"SPS\", \"TBT\", or empty for both.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":"SPS","in":"query","name":"measure_type","required":false,"schema":{"type":"string"}},{"description":"Max results to return (server caps at 100).","example":25,"in":"query","name":"limit","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":{"barriers":[{"dateDistributed":"2026-01-15","id":"example-id","measureType":"SPS","notifyingCountry":"US","objective":"example"}],"fetchedAt":"2026-01-15T12:00:00Z","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetTradeBarriersResponse"}}},"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":"GetTradeBarriers","tags":["TradeService"]}},"/api/trade/v1/get-trade-flows":{"get":{"description":"GetTradeFlows returns a reporter's annual merchandise exports and imports with the World from seeded WTO data, up to 30 years, with a reason when uncovered.","operationId":"GetTradeFlows","parameters":[{"description":"WTO member code of reporting country, as a 3-digit UN M49 code\n (for example \"840\" = United States). Empty selects the \"840\" default.","example":"840","in":"query","name":"reporting_country","required":false,"schema":{"pattern":"^([0-9]{3})?$","type":"string"}},{"description":"WTO member code of partner country, as a 3-digit UN M49 code.\n Empty selects \"000\" = World, which is the only partner currently covered:\n the WTO indicators behind these flows (ITS_MTV_AX, ITS_MTV_AM) publish a\n World total and answer 204 for every named partner. Any other code is\n accepted by validation and answered with unavailable_reason\n TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED, so coverage can widen without a\n contract change.","example":"000","in":"query","name":"partner_country","required":false,"schema":{"pattern":"^([0-9]{3})?$","type":"string"}},{"description":"Number of years to look back from the newest seeded year, inclusive of\n both endpoints (years = 10 returns 11 calendar years). 0 selects the\n default of 10; the maximum is 30, which is the full seeded window.","example":1,"in":"query","name":"years","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":{"coverageEndYear":1,"coverageStartYear":1,"fetchedAt":"2026-01-15T12:00:00Z","flows":[{"exportValueUsd":1.5,"importValueUsd":1.5,"partnerCountry":"000","productSector":"Total merchandise","reportingCountry":"840"}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetTradeFlowsResponse"}}},"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":"GetTradeFlows","tags":["TradeService"]}},"/api/trade/v1/get-trade-restrictions":{"get":{"description":"GetTradeRestrictions returns each WTO reporter's latest MFN applied tariff average from the WTO Timeseries API, highest first, up to 100 economies.","operationId":"GetTradeRestrictions","parameters":[{"description":"WTO member codes to filter by. Empty = all.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":["840"],"explode":true,"in":"query","name":"countries","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Max results to return (server caps at 100).","example":25,"in":"query","name":"limit","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":{"fetchedAt":"2026-01-15T12:00:00Z","restrictions":[{"affectedCountry":"US","description":"Example WorldMonitor observation.","id":"example-id","measureType":"all","notifiedAt":"2026-01-15T12:00:00Z"}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetTradeRestrictionsResponse"}}},"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":"GetTradeRestrictions","tags":["TradeService"]}},"/api/trade/v1/get-us-import-duty":{"get":{"description":"GetUsImportDuty returns the USITC HTS base rate and Section 301 and 232 duties on one HS code from one country. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"GetUsImportDuty","parameters":[{"description":"HTS code: 6, 8 or 10 digits, no dots (\"870323\").","example":"870380","in":"query","name":"hs_code","required":true,"schema":{"pattern":"^[0-9]{6}([0-9]{2}){0,2}$","type":"string"}},{"description":"Exporter, 3-digit UN M49 (\"156\").","example":"156","in":"query","name":"partner_country","required":true,"schema":{"pattern":"^[0-9]{3}$","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":{"additionalDutiesLoaded":true,"hsCode":"870380","htsRelease":"2026HTSRev21","lines":[{"additionalDuties":[{"addedRate":100,"authority":"US_DUTY_AUTHORITY_SECTION_301","condition":"","effectiveFrom":"2024-09-27","heading":"9903.91.03","legalNote":"U.S. note 31(d)","program":"China four-year review","status":"US_ADDITIONAL_DUTY_STATUS_APPLIES","topUpTo":0},{"addedRate":25,"authority":"US_DUTY_AUTHORITY_SECTION_232","condition":"Section 232 rates vary by origin deal and, for some derivatives, apply to metal content only.","effectiveFrom":"","heading":"9903.94.01","legalNote":"U.S. note 33(b)","program":"Passenger vehicles and light trucks","status":"US_ADDITIONAL_DUTY_STATUS_CONDITIONAL","topUpTo":0}],"baseAdValorem":2.5,"baseNonAdValorem":false,"baseRate":"2.5%","basis":"US_DUTY_BASIS_MFN","column2Rate":"10%","description":"Other vehicles, with only electric motors for propulsion","estimateComplete":false,"estimatedRate":102.5,"generalRate":"2.5%","htsCode":"8703.80.00","preferenceProgram":"","specialRate":"Free (A+,AU,B,BH,CL,CO,D,E,IL,JO,KR,MA,OM,P,PA,PE,S,SG)","unresolvedPrograms":["D","E"]}],"partnerCountry":"156","source":"USITC Harmonized Tariff Schedule","sourceUrl":"https://hts.usitc.gov/search?query=8703.80","upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/GetUsImportDutyResponse"}}},"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":"GetUsImportDuty","tags":["TradeService"]}},"/api/trade/v1/list-comtrade-flows":{"get":{"description":"ListComtradeFlows returns UN Comtrade strategic-commodity flows by reporter and HS code, flagging 30% yearly swings. PRO-gated. Requires entitlement tier \u003e= 1.","operationId":"ListComtradeFlows","parameters":[{"description":"UN Comtrade reporter code (e.g. \"842\" = US, \"156\" = China). Empty returns all reporters.","example":"842","in":"query","name":"reporter_code","required":false,"schema":{"type":"string"}},{"description":"HS commodity code (e.g. \"2709\" = crude oil). Empty returns all commodities.","example":"2709","in":"query","name":"cmd_code","required":false,"schema":{"pattern":"^\\d{4,6}$","type":"string"}},{"description":"If true, only return flows with a year-over-year change exceeding 30%.","example":true,"in":"query","name":"anomalies_only","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":{"fetchedAt":"2026-01-15T12:00:00Z","flows":[{"cmdCode":"2709","cmdDesc":"example","isAnomaly":true,"netWeightKg":1.5,"partnerCode":"example"}],"upstreamUnavailable":false},"schema":{"$ref":"#/components/schemas/ListComtradeFlowsResponse"}}},"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":"ListComtradeFlows","tags":["TradeService"]}}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]}],"servers":[{"url":"https://api.worldmonitor.app"}]}