{"openapi":"3.1.0","info":{"title":"UN Comtrade (BYOK) API","version":"0.1.0","description":"UN Comtrade (BYOK) lets an AI assistant read your own UN Comtrade data through the UN Comtrade API with a key you supply (UN Comtrade API subscription key). Read-only: 6 tools (get_trade_data, get_trade_balance, get_bilateral_data, get_data_availability, get_metadata, get_live_update). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-uncomtrade.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-uncomtrade/docs"},"termsOfService":"https://connectorbay.com/byok-uncomtrade/terms"},"servers":[{"url":"https://byok-uncomtrade.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-uncomtrade/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_trade_data":{"post":{"operationId":"get_trade_data","summary":"Get final trade records (value, quantity, weight) by reporter, partner, commodity and flow for given periods; the free k","description":"Get final trade records (value, quantity, weight) by reporter, partner, commodity and flow for given periods; the free key plan may cap records. Use for \"What were Australia's total exports in 2023 according to UN Comtrade\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type_code":{"description":"Product type: C for goods or S for services.","enum":["C","S"],"title":"Type Code","type":"string"},"freq_code":{"description":"Frequency: A for annual or M for monthly.","enum":["A","M"],"title":"Freq Code","type":"string"},"cl_code":{"description":"Classification: HS, SITC, BEC or EBOPS (for services), or a versioned code such as S1, H6, as listed by UN Comtrade.","maxLength":200,"title":"Cl Code","type":"string"},"period":{"description":"Year (2023) or month (202305); several can be given comma-separated.","maxLength":60,"title":"Period","type":"string"},"reporter_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Reporting country numeric code, for example 36 (Australia) or 842 (USA); comma-separate several.","title":"Reporter Code"},"cmd_code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Commodity code such as TOTAL, 01 or 8703; comma-separate several.","title":"Cmd Code"},"flow_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Trade flow: X exports, M imports, RX re-exports, RM re-imports.","title":"Flow Code"},"partner_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Partner country numeric code; 0 means World.","title":"Partner Code"},"partner2_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Second partner country code (trade via another country).","title":"Partner2 Code"},"mot_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Mode of transport code.","title":"Mot Code"},"customs_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Customs procedure code.","title":"Customs Code"},"aggregate_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Aggregate the result by these fields (see UN Comtrade documentation).","title":"Aggregate By"},"breakdown_mode":{"anyOf":[{"enum":["classic","plus"],"type":"string"},{"type":"null"}],"default":null,"description":"classic (partner and product) or plus (extended breakdown).","title":"Breakdown Mode"},"count_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only the number of matching records.","title":"Count Only"},"max_records":{"anyOf":[{"maximum":250000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum records to return (1 to 250000; free keys may be limited to fewer).","title":"Max Records"},"include_desc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to add readable descriptions of codes to each record.","title":"Include Desc"}},"required":["type_code","freq_code","cl_code","period"],"title":"get_trade_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_trade_balance":{"post":{"operationId":"get_trade_balance","summary":"Get the trade balance (exports minus imports) for a reporter, partner and commodity over given periods. Use for \"What wa","description":"Get the trade balance (exports minus imports) for a reporter, partner and commodity over given periods. Use for \"What was Australia's trade balance with the world in 2023\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type_code":{"description":"Product type: C for goods or S for services.","enum":["C","S"],"title":"Type Code","type":"string"},"freq_code":{"description":"Frequency: A for annual or M for monthly.","enum":["A","M"],"title":"Freq Code","type":"string"},"cl_code":{"description":"Classification: HS, SITC, BEC or EBOPS (for services), or a versioned code such as S1, H6, as listed by UN Comtrade.","maxLength":200,"title":"Cl Code","type":"string"},"period":{"description":"Year (2023) or month (202305); several can be given comma-separated.","maxLength":60,"title":"Period","type":"string"},"reporter_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Reporting country numeric code, for example 36 (Australia) or 842 (USA); comma-separate several.","title":"Reporter Code"},"cmd_code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Commodity code such as TOTAL, 01 or 8703; comma-separate several.","title":"Cmd Code"},"partner_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Partner country numeric code; 0 means World.","title":"Partner Code"},"max_records":{"anyOf":[{"maximum":250000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum records to return (1 to 250000; free keys may be limited to fewer).","title":"Max Records"},"include_desc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to add readable descriptions of codes to each record.","title":"Include Desc"}},"required":["type_code","freq_code","cl_code","period"],"title":"get_trade_balanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_bilateral_data":{"post":{"operationId":"get_bilateral_data","summary":"Compare what a reporter says it traded with a partner against the partner's mirror report, for one flow and commodity. U","description":"Compare what a reporter says it traded with a partner against the partner's mirror report, for one flow and commodity. Use for \"How do Australian exports to China compare with China's reported imports from Australia in 2023\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type_code":{"description":"Product type: C for goods or S for services.","enum":["C","S"],"title":"Type Code","type":"string"},"freq_code":{"description":"Frequency: A for annual or M for monthly.","enum":["A","M"],"title":"Freq Code","type":"string"},"cl_code":{"description":"Classification: HS, SITC, BEC or EBOPS (for services), or a versioned code such as S1, H6, as listed by UN Comtrade.","maxLength":200,"title":"Cl Code","type":"string"},"period":{"description":"Year (2023) or month (202305); several can be given comma-separated.","maxLength":60,"title":"Period","type":"string"},"reporter_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Reporting country numeric code, for example 36 (Australia) or 842 (USA); comma-separate several.","title":"Reporter Code"},"cmd_code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Commodity code such as TOTAL, 01 or 8703; comma-separate several.","title":"Cmd Code"},"flow_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Trade flow: X exports, M imports, RX re-exports, RM re-imports.","title":"Flow Code"},"partner_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Partner country numeric code; 0 means World.","title":"Partner Code"},"max_records":{"anyOf":[{"maximum":250000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum records to return (1 to 250000; free keys may be limited to fewer).","title":"Max Records"},"include_desc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to add readable descriptions of codes to each record.","title":"Include Desc"}},"required":["type_code","freq_code","cl_code","period"],"title":"get_bilateral_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_data_availability":{"post":{"operationId":"get_data_availability","summary":"Show which reporters and periods have published data for a product type, frequency and classification, optionally by pub","description":"Show which reporters and periods have published data for a product type, frequency and classification, optionally by publication date. Use for \"Which countries have published annual HS goods data for 2023\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type_code":{"description":"Product type: C for goods or S for services.","enum":["C","S"],"title":"Type Code","type":"string"},"freq_code":{"description":"Frequency: A for annual or M for monthly.","enum":["A","M"],"title":"Freq Code","type":"string"},"cl_code":{"description":"Classification: HS, SITC, BEC or EBOPS (for services), or a versioned code such as S1, H6, as listed by UN Comtrade.","maxLength":200,"title":"Cl Code","type":"string"},"period":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Year (2023) or month (202305); comma-separate several.","title":"Period"},"reporter_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Reporting country numeric code, for example 36 (Australia) or 842 (USA); comma-separate several.","title":"Reporter Code"},"published_date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only data published on or after this date (yyyy-mm-dd).","title":"Published Date From"},"published_date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only data published on or before this date (yyyy-mm-dd).","title":"Published Date To"}},"required":["type_code","freq_code","cl_code"],"title":"get_data_availabilityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_metadata":{"post":{"operationId":"get_metadata","summary":"Get publication notes for a reporter and period: data sets, publication dates and remarks. Use for \"What notes accompany","description":"Get publication notes for a reporter and period: data sets, publication dates and remarks. Use for \"What notes accompany Australia's 2023 annual goods data in UN Comtrade\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type_code":{"description":"Product type: C for goods or S for services.","enum":["C","S"],"title":"Type Code","type":"string"},"freq_code":{"description":"Frequency: A for annual or M for monthly.","enum":["A","M"],"title":"Freq Code","type":"string"},"cl_code":{"description":"Classification: HS, SITC, BEC or EBOPS (for services), or a versioned code such as S1, H6, as listed by UN Comtrade.","maxLength":200,"title":"Cl Code","type":"string"},"reporter_code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Reporting country numeric code, for example 36.","title":"Reporter Code"},"period":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Year (2023) or month (202305).","title":"Period"}},"required":["type_code","freq_code","cl_code"],"title":"get_metadataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_live_update":{"post":{"operationId":"get_live_update","summary":"List the most recent data publications on UN Comtrade (which reporters and periods were just released). Use for \"What di","description":"List the most recent data publications on UN Comtrade (which reporters and periods were just released). Use for \"What did UN Comtrade publish most recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_live_updateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}