{"openapi":"3.1.1","info":{"title":"Tradaro Public API","version":"1.0.0","description":"Published trade data with source provenance. All twelve operations require an API Bearer key; scopes are described by x-required-scope. Create and revoke keys in your organisation settings, never in browser-side application code. Each request revalidates key and organisation rights. Successful responses include per-key daily quota and minute rate headers; rejected scope or authentication attempts do not consume usage. Unknown query parameters and GET request bodies are refused. JSON numbers are finite; null never stands for zero. Examples use synthetic fixtures and do not assert live operator identities or amounts. Responses are not cacheable. Browser CORS access is not advertised; call this API from your server."},"servers":[{"url":"https://api.tradaro.com/v1","description":"Public HTTPS API"}],"tags":[{"name":"Catalogue","description":"Loaded markets, publications and derived release differences."},{"name":"Operators","description":"Declared trader-directory identities and appearances."},{"name":"Trade","description":"Published trade cells, commodity references and partner codes."},{"name":"Exports","description":"Asynchronous CSV and Parquet files scoped to the creating key."}],"security":[{"ApiKeyBearer":[]}],"paths":{"/reporters":{"get":{"operationId":"listReporters","tags":["Catalogue"],"summary":"List available reporters","description":"Returns only loaded markets visible to this key. No query parameters or body. Empty data is valid. Includes the actual source licence and attribution; adapters for unloaded markets are not advertised.","x-required-scope":"read","parameters":[],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportersResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"reporter":"GB","name":"United Kingdom","source":"hmrc_uktradeinfo","latest_period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","loaded_at":"2026-09-11T00:00:00.000000Z","licence":{"name":"Open Government Licence v3.0","url":"https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/","attribution":"Contains public sector information licensed under the Open Government Licence v3.0. HMRC does not endorse Tradaro."}}],"meta":{"count":1}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-export-columns":[{"name":"reporter","type":"Nullable(String)"},{"name":"name","type":"Nullable(String)"},{"name":"source","type":"Nullable(String)"},{"name":"latest_period","type":"Nullable(String)"},{"name":"generation","type":"Nullable(String)"},{"name":"loaded_at","type":"Nullable(String)"},{"name":"licence","type":"Nullable(String)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/releases":{"get":{"operationId":"listReleases","tags":["Catalogue"],"summary":"List published releases","description":"Newest month first. Pagination is bound to the reporter filter. Each row carries its generation, publication times and counts for the five difference kinds; meta has no selected release object. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/ReleaseReporter"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/ReleaseCursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasesResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previous_period":"2026-05","history_start":"2026-01","summary":{"new_operator":0,"operator_returned":0,"new_operator_commodity":0,"new_partner_for_commodity":0,"commodity_value_change":0},"loaded_at":"2026-09-11T00:00:00.000000Z","diff_computed_at":"2026-09-11T00:00:00.000000Z","observed_at":"2026-09-11T00:00:00.000000Z"}],"meta":{"count":1,"limit":100,"next_cursor":null}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"reporter","type":"Nullable(String)"},{"name":"period","type":"Nullable(String)"},{"name":"previous_period","type":"Nullable(String)"},{"name":"history_start","type":"Nullable(String)"},{"name":"generation","type":"Nullable(String)"},{"name":"summary","type":"Nullable(String)"},{"name":"loaded_at","type":"Nullable(String)"},{"name":"diff_computed_at","type":"Nullable(String)"},{"name":"observed_at","type":"Nullable(String)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/operators":{"get":{"operationId":"searchOperators","tags":["Operators"],"summary":"Search declared operators","description":"Case-insensitive name search within published trader-directory appearances. Totals describe distinct published links and months, not company trade values. Up to six source commodity codes accompany each result. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Reporter"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperatorsResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","reporter":"GB","operator_ref":"000123","name":"Example Foods Ltd","commodities":1,"months":1,"first_period":"2026-06","last_period":"2026-06","flows":["import"],"lineage":{"method":"aggregated","basis":"published_operator_links","counts":{"commodities":"distinct commodity_scheme and commodity_code","months":"distinct published period","links":"distinct published link including its lineage and revision"}},"codes":[{"commodity_scheme":"CN8","commodity_code":"02071410"}],"codes_truncated":false}],"meta":{"count":1,"limit":100,"next_cursor":null,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"reporter","type":"Nullable(String)"},{"name":"operator_ref","type":"Nullable(String)"},{"name":"name","type":"Nullable(String)"},{"name":"commodities","type":"Nullable(Int64)"},{"name":"months","type":"Nullable(Int64)"},{"name":"first_period","type":"Nullable(String)"},{"name":"last_period","type":"Nullable(String)"},{"name":"flows","type":"Nullable(String)"},{"name":"codes","type":"Nullable(String)"},{"name":"codes_truncated","type":"Nullable(Bool)"},{"name":"method","type":"Nullable(String)"},{"name":"basis","type":"Nullable(String)"},{"name":"counts","type":"Nullable(String)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/operators/{source}/{ref}":{"get":{"operationId":"getOperator","tags":["Operators"],"summary":"Get a declared operator","description":"Returns latest published directory attributes and aggregate counts over loaded months. The composite identity is source plus ref. Country and address are verbatim directory strings, not verified registry identities. No query parameters or body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/SourcePath"},{"$ref":"#/components/parameters/RefPath"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperatorResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":{"source":"hmrc_uktradeinfo","reporter":"GB","operator_ref":"000123","name":"Example Foods Ltd","commodities":1,"months":1,"first_period":"2026-06","last_period":"2026-06","flows":["import"],"lineage":{"method":"aggregated","basis":"published_operator_links","counts":{"commodities":"distinct commodity_scheme and commodity_code","months":"distinct published period","links":"distinct published link including its lineage and revision"}},"address_lines":["1 Example Road"],"postal_code":"AB1 2CD","country":"United Kingdom","attributes_period":"2026-06","links":1},"meta":{"count":1,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/operators/{source}/{ref}/links":{"get":{"operationId":"listOperatorLinks","tags":["Operators"],"summary":"List an operator’s declared links","description":"Distinct published directory appearances ordered by month descending and source dimensions. Value is always null; no company monetary values are inferred. Defaults to the entire published history. from and to must both name published months and be ordered; unlike /flows, this endpoint has no 120-month range cap. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/SourcePath"},{"$ref":"#/components/parameters/RefPath"},{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/To"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinksResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","reporter_geo_scheme":"iso3166-1:alpha2","reporter_geo_code":"GB","period":"2026-06","flow":"import","commodity_scheme":"CN8","commodity_code":"02071410","currency":"GBP","tier":"T1","method":"declared","confidence":"A","revision":1,"operator_ref":"000123","value":null}],"meta":{"count":1,"limit":100,"next_cursor":null,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"reporter_geo_scheme","type":"Nullable(String)"},{"name":"reporter_geo_code","type":"Nullable(String)"},{"name":"period","type":"Nullable(String)"},{"name":"flow","type":"Nullable(String)"},{"name":"commodity_scheme","type":"Nullable(String)"},{"name":"commodity_code","type":"Nullable(String)"},{"name":"operator_ref","type":"Nullable(String)"},{"name":"value","type":"Nullable(Float64)"},{"name":"currency","type":"Nullable(String)"},{"name":"tier","type":"Nullable(String)"},{"name":"method","type":"Nullable(String)"},{"name":"confidence","type":"Nullable(String)"},{"name":"revision","type":"Nullable(Int64)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/commodities/{scheme}/{code}":{"get":{"operationId":"getCommodity","tags":["Trade"],"summary":"Get a nomenclature entry","description":"Reads the loaded reference independently of trade activity. Supports actual CN8, HS6 and residual HS2 entries; does not synthesize an HS6 from a prefix. period selects effective crosswalk validity and must be published. parent_codes preserve original forms such as 02----. Unknown entries return 404. meta.reference_revision fingerprints the reference version. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/SchemePath"},{"$ref":"#/components/parameters/CodePath"},{"$ref":"#/components/parameters/Reporter"},{"$ref":"#/components/parameters/Period"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommodityResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":{"source":"hmrc_uktradeinfo","commodity_scheme":"CN8","commodity_code":"02071410","description":"Example frozen poultry cuts","parent_codes":["020714","0207","02"],"reference_batch":"ref","alt_scheme":null,"alt_code":null,"hs6":"020714","hs6_mappings":[{"source":"hmrc_uktradeinfo","reference_batch":"ref","hs6":"020714","hs_version":"2022","valid_from":null,"valid_to":null}]},"meta":{"count":1,"period":"2026-06","reference_revision":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/flows":{"get":{"operationId":"listFlows","tags":["Trade"],"summary":"List published trade cells","description":"Reads source cells without aggregation, including duplicate components and suppressed nulls. Defaults to CN8 in the latest published month; from defaults to to. Inclusive range is at most 120 calendar months and both endpoints must be published. Only published months inside the range are read. partner alone means ISO alpha-2, resolved separately for each month; partner_scheme plus partner means an exact original code. ISO filtering adds meta.reference_revision. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/Reporter"},{"$ref":"#/components/parameters/Commodity"},{"$ref":"#/components/parameters/CommodityScheme"},{"$ref":"#/components/parameters/Partner"},{"$ref":"#/components/parameters/PartnerScheme"},{"$ref":"#/components/parameters/Flow"},{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/To"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowsResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","batch_key":"2026-06","reporter_geo_scheme":"iso3166-1:alpha2","reporter_geo_code":"GB","period":"2026-06","flow":"import","commodity_scheme":"CN8","commodity_code":"02071410","partner_geo_scheme":"uktradeinfo:CountryId","partner_geo_code":"001","location_code":"","currency":"GBP","tier":"T1","method":"declared","confidence":"A","revision":1,"component":1,"suppressed":false,"value":1250.5,"net_mass_kg":100,"supplementary_unit":null}],"meta":{"count":1,"limit":100,"next_cursor":null,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"from":"2026-06","to":"2026-06","periods":["2026-06"]}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"batch_key","type":"Nullable(String)"},{"name":"reporter_geo_scheme","type":"Nullable(String)"},{"name":"reporter_geo_code","type":"Nullable(String)"},{"name":"period","type":"Nullable(String)"},{"name":"flow","type":"Nullable(String)"},{"name":"commodity_scheme","type":"Nullable(String)"},{"name":"commodity_code","type":"Nullable(String)"},{"name":"partner_geo_scheme","type":"Nullable(String)"},{"name":"partner_geo_code","type":"Nullable(String)"},{"name":"location_code","type":"Nullable(String)"},{"name":"currency","type":"Nullable(String)"},{"name":"tier","type":"Nullable(String)"},{"name":"method","type":"Nullable(String)"},{"name":"confidence","type":"Nullable(String)"},{"name":"revision","type":"Nullable(Int64)"},{"name":"component","type":"Nullable(Int64)"},{"name":"suppressed","type":"Nullable(Bool)"},{"name":"value","type":"Nullable(Float64)"},{"name":"net_mass_kg","type":"Nullable(Float64)"},{"name":"supplementary_unit","type":"Nullable(Float64)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/partners":{"get":{"operationId":"listPartners","tags":["Trade"],"summary":"List published partner codes","description":"Returns partner identities actually present in the selected month across supported commodity schemes. Labels and optional ISO identities come from effective geographic references. Residual or unmapped codes are retained. Ordered by original scheme and code. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/Reporter"},{"$ref":"#/components/parameters/Period"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnersResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","partner_geo_scheme":"uktradeinfo:CountryId","partner_geo_code":"001","name":"France","iso_alpha2":"FR","reference_batch":"ref","valid_from":null,"valid_to":null}],"meta":{"count":1,"limit":100,"next_cursor":null,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"period":"2026-06","reference_revision":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"partner_geo_scheme","type":"Nullable(String)"},{"name":"partner_geo_code","type":"Nullable(String)"},{"name":"name","type":"Nullable(String)"},{"name":"iso_alpha2","type":"Nullable(String)"},{"name":"reference_batch","type":"Nullable(String)"},{"name":"valid_from","type":"Nullable(String)"},{"name":"valid_to","type":"Nullable(String)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/diffs":{"get":{"operationId":"listDiffs","tags":["Catalogue"],"summary":"List release differences","description":"Requires both read scope and the organisation’s differences/alerts entitlement. Reads one immutable release generation, ordered by kind and subject. The five categories compare declared monthly CN8 data; decimal value changes remain strings. meta.total is the selected category count before pagination. No request body.","x-required-scope":"read","parameters":[{"$ref":"#/components/parameters/Reporter"},{"$ref":"#/components/parameters/Period"},{"$ref":"#/components/parameters/Kind"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffsResponse"},"examples":{"publishedFixture":{"summary":"Synthetic published fixture","value":{"data":[{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","kind":"new_operator","subject":"000123","detail":{"operator_ref":"000123","operator_name":"Example Foods Ltd"},"tier":null,"method":"derived","confidence":null,"revision":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","basis":"monthly-declared-cn8-v1"}],"meta":{"count":1,"limit":100,"next_cursor":null,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"total":1}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-pagination":{"limit":"limit","cursor":"cursor","nextCursor":"meta.next_cursor","defaultLimit":100,"maximumLimit":500},"x-export-columns":[{"name":"source","type":"Nullable(String)"},{"name":"reporter","type":"Nullable(String)"},{"name":"period","type":"Nullable(String)"},{"name":"generation","type":"Nullable(String)"},{"name":"kind","type":"Nullable(String)"},{"name":"subject","type":"Nullable(String)"},{"name":"detail","type":"Nullable(String)"},{"name":"tier","type":"Nullable(String)"},{"name":"method","type":"Nullable(String)"},{"name":"confidence","type":"Nullable(String)"},{"name":"revision","type":"Nullable(String)"},{"name":"basis","type":"Nullable(String)"},{"name":"release_source","type":"Nullable(String)"},{"name":"release_period","type":"Nullable(String)"},{"name":"release_generation","type":"Nullable(String)"},{"name":"reference_revision","type":"Nullable(String)"}]}},"/exports":{"post":{"operationId":"createExport","tags":["Exports"],"summary":"Create an asynchronous export","description":"Creates an asynchronous CSV or Parquet export of one supported list endpoint. Requires bulk scope and an effective export allowance; read scope is not additionally required. params is a JSON object of the endpoint’s string filters; omit limit and cursor. No URL query parameters. JSON body is at most 4096 bytes. row_limit defaults to 100000 and is capped by current organisation rights. At most five active exports per organisation, shared with web exports. Data and references are pinned during generation; changes fail the job rather than mix versions. The creating key alone may poll or download; revocation and changed entitlements apply immediately. Jobs expire after 24 hours, with a 30-minute processing deadline. CSV is UTF-8 with BOM, a header and quoted fields; null is empty, booleans are true/false, arrays and objects are JSON text. Potential formula strings receive an apostrophe prefix; Parquet retains raw strings, native nullable numbers/booleans and nulls. Source codes remain text. Fixed columns are listed in each exportable operation’s x-export-columns; each row includes release_source, release_period, release_generation and nullable reference_revision. Files are bounded to 256 MiB; empty results produce a valid file with the fixed schema. Poll according to Retry-After; failed/expired states report error_code.","x-required-scope":"bulk","parameters":[],"responses":{"202":{"description":"Accepted; process asynchronously and poll the Location URL.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Location":{"$ref":"#/components/headers/Location"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportResponse"},"examples":{"pending":{"value":{"data":{"id":"11111111-1111-4111-8111-111111111111","status":"pending","format":"csv","endpoint":"/flows","cap":2,"rows":0,"bytes":0,"truncated":false,"created_at":"2026-09-11T00:00:00.000000Z","expires_at":"2026-09-12T00:00:00Z","finished_at":null,"error_code":null,"status_url":"/v1/exports/11111111-1111-4111-8111-111111111111","download_url":null},"meta":{"count":1,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"description":"A supported list path, its string filter object, output format and optional row cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"},"examples":{"flowsCsv":{"summary":"Export two published commodity cells","value":{"endpoint":"/flows","params":{"commodity":"02071410"},"format":"csv","row_limit":2}},"reportersParquet":{"summary":"Export loaded reporters","value":{"endpoint":"/reporters","params":{},"format":"parquet","row_limit":10}}}}}}}},"/exports/{id}":{"get":{"operationId":"getExport","tags":["Exports"],"summary":"Get export status","description":"Poll with the creating key. Status is pending, running, completed, failed or expired. A completed response contains download_url. Error details are sanitised in error_code. No query parameters or body.","x-required-scope":"bulk","parameters":[{"$ref":"#/components/parameters/IdPath"}],"responses":{"200":{"description":"Successful response.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportResponse"},"examples":{"completed":{"value":{"data":{"id":"11111111-1111-4111-8111-111111111111","status":"completed","format":"csv","endpoint":"/flows","cap":2,"rows":2,"bytes":2048,"truncated":true,"created_at":"2026-09-11T00:00:00.000000Z","expires_at":"2026-09-12T00:00:00Z","finished_at":"2026-09-11T00:01:00Z","error_code":null,"status_url":"/v1/exports/11111111-1111-4111-8111-111111111111","download_url":"/v1/exports/11111111-1111-4111-8111-111111111111/download"},"meta":{"count":1,"release":{"source":"hmrc_uktradeinfo","reporter":"GB","period":"2026-06","generation":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/exports/{id}/download":{"get":{"operationId":"downloadExport","tags":["Exports"],"summary":"Download an export","description":"Download the retained snapshot with its creating key. Requires a completed, unexpired export and current entitlement; otherwise 409 or 403. Another key, including one in the same organisation, receives 404. Returns file bytes, not a JSON envelope or signed URL. X-Tradaro-Content-SHA256 verifies the exact bytes. No query parameters or body.","x-required-scope":"bulk","parameters":[{"$ref":"#/components/parameters/IdPath"}],"responses":{"200":{"description":"UTF-8 CSV or typed Parquet file, at most 256 MiB. Content-Disposition supplies the filename.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"X-Tradaro-Release":{"$ref":"#/components/headers/Release"},"X-Tradaro-Quota-Limit":{"$ref":"#/components/headers/QuotaLimit"},"X-Tradaro-Quota-Remaining":{"$ref":"#/components/headers/QuotaRemaining"},"X-Tradaro-Quota-Reset":{"$ref":"#/components/headers/QuotaReset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateReset"},"X-Content-Type-Options":{"$ref":"#/components/headers/NoSniff"},"Content-Disposition":{"$ref":"#/components/headers/Disposition"},"X-Tradaro-Content-SHA256":{"$ref":"#/components/headers/ContentHash"}},"content":{"text/csv":{"schema":{"type":"string"}},"application/vnd.apache.parquet":{}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"trd_live_ followed by 48 alphanumeric characters","description":"Send Authorization: Bearer <API_KEY>. read and bulk are key permissions, not OAuth scopes. Public data routes require read; export routes require bulk. Keys are disclosed once at creation."}},"parameters":{"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum rows per page, 1–500 (default 100). Send one canonical decimal value, without a leading zero; array values are refused.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"example":100},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque token from meta.next_cursor. Keep all filters unchanged; null means the end. Do not decode or construct tokens.","schema":{"$ref":"#/components/schemas/Cursor"}},"ReleaseCursor":{"name":"cursor","in":"query","required":false,"description":"Opaque token from meta.next_cursor, bound to the reporter filter. Releases are ordered by descending month.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":256}},"Reporter":{"name":"reporter","in":"query","required":false,"description":"Reporter market; defaults to GB. Entitlements are enforced before warehouse reads.","schema":{"$ref":"#/components/schemas/Reporter","default":"GB"},"example":"GB"},"ReleaseReporter":{"name":"reporter","in":"query","required":false,"description":"Optional reporter filter. Without it, returns loaded markets within your entitlement. An entitled but unloaded market gives an empty list.","schema":{"$ref":"#/components/schemas/Reporter"},"example":"GB"},"Period":{"name":"period","in":"query","required":false,"description":"Published month; defaults to the latest release. An absent release is not inferred from another month.","schema":{"$ref":"#/components/schemas/Period"},"example":"2026-06"},"From":{"name":"from","in":"query","required":false,"description":"Inclusive published lower month. For flows, defaults to to; for operator links, defaults to the earliest published month.","schema":{"$ref":"#/components/schemas/Period"}},"To":{"name":"to","in":"query","required":false,"description":"Inclusive published upper month; defaults to the latest release.","schema":{"$ref":"#/components/schemas/Period"}},"SourcePath":{"name":"source","in":"path","required":true,"description":"Published source identifier. Other sources return 404.","schema":{"$ref":"#/components/schemas/Source"},"example":"hmrc_uktradeinfo"},"RefPath":{"name":"ref","in":"path","required":true,"description":"Trader-directory source identifier, not a company registration number.","schema":{"$ref":"#/components/schemas/OperatorRef"},"example":"000123"},"SchemePath":{"name":"scheme","in":"path","required":true,"description":"Loaded nomenclature scheme; no implicit conversion.","schema":{"$ref":"#/components/schemas/CommodityScheme"},"example":"CN8"},"CodePath":{"name":"code","in":"path","required":true,"description":"Eight digits for CN8, six for HS6, or two digits with optional six hyphens for HS2. Keep leading zeroes.","schema":{"$ref":"#/components/schemas/CommodityCode"},"example":"02071410"},"IdPath":{"name":"id","in":"path","required":true,"description":"Export UUID returned by creation; only its creating key can access it.","schema":{"type":"string","format":"uuid"},"example":"11111111-1111-4111-8111-111111111111"},"Query":{"name":"q","in":"query","required":true,"description":"Case-insensitive substring of the operator name. Trimmed length must be 2–80 Unicode characters; control characters are refused. Prefix matches rank first, then months descending, name and source reference.","schema":{"type":"string","minLength":2,"maxLength":80},"example":"foods"},"Commodity":{"name":"commodity","in":"query","required":false,"description":"Exact commodity code in commodity_scheme; omit for every loaded code in that scheme.","schema":{"$ref":"#/components/schemas/CommodityCode"},"example":"02071410"},"CommodityScheme":{"name":"commodity_scheme","in":"query","required":false,"description":"Scheme to read, even when commodity is omitted. Only actual loaded rows are returned.","schema":{"$ref":"#/components/schemas/CommodityScheme","default":"CN8"}},"Partner":{"name":"partner","in":"query","required":false,"description":"Without partner_scheme, an uppercase ISO alpha-2 code matched through the effective geographic reference for each month. With partner_scheme, an exact original source code, including residual codes.","schema":{"$ref":"#/components/schemas/GeoCode"},"example":"FR"},"PartnerScheme":{"name":"partner_scheme","in":"query","required":false,"description":"Requires partner. Selects its original source scheme instead of ISO lookup; use the scheme returned by /partners.","schema":{"$ref":"#/components/schemas/GeoScheme"},"example":"uktradeinfo:CountryId"},"Flow":{"name":"flow","in":"query","required":false,"description":"Exact trade direction; omitted returns both.","schema":{"$ref":"#/components/schemas/Flow"},"example":"import"},"Kind":{"name":"kind","in":"query","required":false,"description":"Restrict to one difference category; omitted returns all five categories.","schema":{"$ref":"#/components/schemas/DiffKind"},"example":"new_operator"}},"headers":{"RequestId":{"description":"Server-generated request UUID. Include it when reporting an error.","required":true,"schema":{"type":"string","format":"uuid"}},"CacheControl":{"description":"Contains no-store and private. Proxies may append another no-store field; combine field values as HTTP directives.","required":true,"schema":{"type":"string"},"example":"no-store, private"},"Release":{"description":"Source and selected release month, for example hmrc_uktradeinfo=2026-06. Catalogue lists use the latest month present in this page and return an empty value for an empty page. Data and export responses match meta.release.","required":true,"schema":{"type":"string","pattern":"^(?:hmrc_uktradeinfo=[1-9][0-9]{3}-(?:0[1-9]|1[0-2]))?$"},"example":"hmrc_uktradeinfo=2026-06"},"QuotaLimit":{"description":"Daily request allowance for the key; unlimited when the effective offer has no daily cap.","required":true,"schema":{"type":"string","pattern":"^(?:[0-9]+|unlimited)$"},"example":"5000"},"QuotaRemaining":{"description":"Remaining daily requests after this authenticated request, or unlimited. Quotas belong to each key; effective organisation rights are revalidated.","required":true,"schema":{"type":"string","pattern":"^(?:[0-9]+|unlimited)$"},"example":"4999"},"QuotaReset":{"description":"UTC instant at the next daily request-window reset.","required":true,"schema":{"$ref":"#/components/schemas/Instant"}},"RateLimit":{"description":"Maximum authenticated requests per key in a minute.","required":true,"schema":{"type":"string","const":"60"},"example":"60"},"RateRemaining":{"description":"Requests left in the key’s current minute after this call.","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"example":"59"},"RateReset":{"description":"UTC instant when the current minute window resets.","required":true,"schema":{"$ref":"#/components/schemas/Instant"}},"NoSniff":{"description":"Disables MIME sniffing.","required":true,"schema":{"type":"string","const":"nosniff"}},"RetryAfter":{"description":"Seconds to wait before retrying. For accepted exports, poll after 5 seconds. On 429, wait for the denied window to reset.","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"},"example":"5"},"Authenticate":{"description":"Bearer authentication is required.","required":true,"schema":{"type":"string","const":"Bearer"}},"Location":{"description":"Relative URL of the newly created export status resource.","required":true,"schema":{"type":"string","pattern":"^/v1/exports/[a-f0-9-]{36}$"}},"ContentHash":{"description":"SHA-256 of the exact downloaded bytes.","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"Disposition":{"description":"Attachment filename tradaro-{export UUID}.csv or .parquet.","required":true,"schema":{"type":"string"},"example":"attachment; filename=\"tradaro-11111111-1111-4111-8111-111111111111.csv\""}},"responses":{"BadRequest":{"description":"Invalid parameters or cursor. Unknown query fields, arrays, empty values where disallowed, and GET bodies are refused.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"The request parameters are invalid.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"Unauthorized":{"description":"Missing, malformed, unknown or revoked Bearer key.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"WWW-Authenticate":{"$ref":"#/components/headers/Authenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"A valid Bearer credential is required.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"Forbidden":{"description":"Effective API rights, required key scope, market entitlement or differences entitlement deny this request.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"scope_denied","message":"The API key does not have the required permission.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"NotFound":{"description":"Resource or requested published month not found. Foreign export keys also receive 404.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"The requested resource was not found.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"MethodNotAllowed":{"description":"The path does not support this method.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Allow":{"description":"Supported methods.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"method_not_allowed","message":"This HTTP method is not supported.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"Conflict":{"description":"Publication changed, organisation already has five active exports, or export is not downloadable. Restart data pagination after publication_changed.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"publication_changed","message":"The publication changed during this request. Restart pagination.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"TooLarge":{"description":"Request body exceeds 4096 bytes, or export exceeds its bound.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"The request body is too large.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"UnsupportedMediaType":{"description":"Export creation requires application/json.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsupported_media_type","message":"Use application/json for this request.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"RateLimited":{"description":"Daily request quota or per-minute rate exceeded. Retry after the response delay. Denied requests do not consume additional quota.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"api_rate_limited","message":"The API request rate limit has been reached.","request_id":"11111111-1111-4111-8111-111111111111"}}}}},"Unavailable":{"description":"Data publication, reference version, warehouse or storage is temporarily unavailable; no partial response is returned.","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"api_unavailable","message":"The API is temporarily unavailable.","request_id":"11111111-1111-4111-8111-111111111111"}}}}}},"schemas":{"Source":{"type":"string","const":"hmrc_uktradeinfo"},"Reporter":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 reporter. GB is the currently published market."},"Period":{"type":"string","pattern":"^[1-9][0-9]{3}-(0[1-9]|1[0-2])$","examples":["2026-06"]},"Generation":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of the published release generation."},"ReferenceRevision":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 fingerprint of the loaded reference versions used by this response. Separate from the trade release generation."},"OperatorRef":{"type":"string","pattern":"^[0-9]{1,12}$","description":"Source-scoped trader directory identifier, kept as text, including leading zeroes. Not a company registration number."},"Flow":{"type":"string","enum":["import","export"]},"CommodityScheme":{"type":"string","enum":["CN8","HS6","HS2"]},"CommodityCode":{"type":"string","pattern":"^(?:[0-9]{8}|[0-9]{6}|[0-9]{2}(?:------)?)$","description":"CN8: eight digits; HS6: six digits; HS2: two digits, optionally followed by six hyphens. Codes are never converted implicitly."},"GeoScheme":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$"},"GeoCode":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$","description":"Original source code, including residual or aggregate codes. Does not imply an ISO identity."},"Cursor":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":4096,"description":"Opaque continuation token. Reuse unchanged with the same endpoint and filters. Data cursors are bound to the publication and relevant references; restart pagination after a change."},"Instant":{"type":"string","format":"date-time"},"Count":{"type":"integer","minimum":0,"maximum":9007199254740991},"UInt32":{"type":"integer","minimum":0,"maximum":4294967295},"ReleaseIdentity":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"}},"required":["source","reporter","period","generation"],"additionalProperties":false},"DiffKind":{"type":"string","enum":["new_operator","operator_returned","new_operator_commodity","new_partner_for_commodity","commodity_value_change"]},"ReleaseSummary":{"type":"object","properties":{"new_operator":{"$ref":"#/components/schemas/Count"},"operator_returned":{"$ref":"#/components/schemas/Count"},"new_operator_commodity":{"$ref":"#/components/schemas/Count"},"new_partner_for_commodity":{"$ref":"#/components/schemas/Count"},"commodity_value_change":{"$ref":"#/components/schemas/Count"}},"required":["new_operator","operator_returned","new_operator_commodity","new_partner_for_commodity","commodity_value_change"],"additionalProperties":false},"Licence":{"type":"object","properties":{"name":{"type":"string","const":"Open Government Licence v3.0"},"url":{"type":"string","const":"https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"},"attribution":{"type":"string","const":"Contains public sector information licensed under the Open Government Licence v3.0. HMRC does not endorse Tradaro."}},"required":["name","url","attribution"],"additionalProperties":false},"ReporterRecord":{"type":"object","properties":{"reporter":{"$ref":"#/components/schemas/Reporter"},"name":{"type":"string"},"source":{"$ref":"#/components/schemas/Source"},"latest_period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"loaded_at":{"$ref":"#/components/schemas/Instant"},"licence":{"$ref":"#/components/schemas/Licence"}},"required":["reporter","name","source","latest_period","generation","loaded_at","licence"],"additionalProperties":false},"ReleaseRecord":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"previous_period":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"history_start":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"summary":{"$ref":"#/components/schemas/ReleaseSummary"},"loaded_at":{"$ref":"#/components/schemas/Instant"},"diff_computed_at":{"$ref":"#/components/schemas/Instant"},"observed_at":{"$ref":"#/components/schemas/Instant"}},"required":["source","reporter","period","previous_period","history_start","generation","summary","loaded_at","diff_computed_at","observed_at"],"additionalProperties":false},"CountMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"}},"required":["count"],"additionalProperties":false},"PageMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"limit":{"type":"integer","minimum":1,"maximum":500},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}]}},"required":["count","limit","next_cursor"],"additionalProperties":false},"PublishedMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","release"],"additionalProperties":false},"PublishedPageMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"limit":{"type":"integer","minimum":1,"maximum":500},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}]},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","limit","next_cursor","release"],"additionalProperties":false},"FlowMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"limit":{"type":"integer","minimum":1,"maximum":500},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}]},"from":{"$ref":"#/components/schemas/Period"},"to":{"$ref":"#/components/schemas/Period"},"periods":{"type":"array","items":{"$ref":"#/components/schemas/Period"},"minItems":1,"maxItems":120},"reference_revision":{"$ref":"#/components/schemas/ReferenceRevision"},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","limit","next_cursor","from","to","periods","release"],"additionalProperties":false},"ReferenceMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"period":{"$ref":"#/components/schemas/Period"},"reference_revision":{"$ref":"#/components/schemas/ReferenceRevision"},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","period","reference_revision","release"],"additionalProperties":false},"PartnerMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"limit":{"type":"integer","minimum":1,"maximum":500},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}]},"period":{"$ref":"#/components/schemas/Period"},"reference_revision":{"$ref":"#/components/schemas/ReferenceRevision"},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","limit","next_cursor","period","reference_revision","release"],"additionalProperties":false},"DiffMeta":{"type":"object","properties":{"count":{"$ref":"#/components/schemas/Count"},"limit":{"type":"integer","minimum":1,"maximum":500},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}]},"total":{"$ref":"#/components/schemas/Count"},"release":{"$ref":"#/components/schemas/ReleaseIdentity"}},"required":["count","limit","next_cursor","total","release"],"additionalProperties":false},"OperatorSearchRecord":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"name":{"type":"string","maxLength":1024},"commodities":{"type":"integer","minimum":1,"maximum":4294967295},"months":{"type":"integer","minimum":1,"maximum":2000},"first_period":{"$ref":"#/components/schemas/Period"},"last_period":{"$ref":"#/components/schemas/Period"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/Flow"},"minItems":1,"maxItems":2,"uniqueItems":true},"lineage":{"type":"object","properties":{"method":{"type":"string","const":"aggregated"},"basis":{"type":"string","const":"published_operator_links"},"counts":{"type":"object","properties":{"commodities":{"type":"string","const":"distinct commodity_scheme and commodity_code"},"months":{"type":"string","const":"distinct published period"},"links":{"type":"string","const":"distinct published link including its lineage and revision"}},"required":["commodities","months","links"],"additionalProperties":false}},"required":["method","basis","counts"],"additionalProperties":false},"codes":{"type":"array","items":{"type":"object","properties":{"commodity_scheme":{"type":"string","enum":["CN8","HS2"]},"commodity_code":{"$ref":"#/components/schemas/CommodityCode"}},"required":["commodity_scheme","commodity_code"],"additionalProperties":false,"description":"Only the published trader-directory schemes CN8 and residual HS2 are returned.","allOf":[{"if":{"properties":{"commodity_scheme":{"const":"CN8"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS6"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{6}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS2"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{2}(?:------)?$"}}}}]},"minItems":1,"maxItems":6},"codes_truncated":{"type":"boolean"}},"required":["source","reporter","operator_ref","name","commodities","months","first_period","last_period","flows","lineage","codes","codes_truncated"],"additionalProperties":false},"OperatorProfile":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"name":{"type":"string","maxLength":1024},"commodities":{"type":"integer","minimum":1,"maximum":4294967295},"months":{"type":"integer","minimum":1,"maximum":2000},"first_period":{"$ref":"#/components/schemas/Period"},"last_period":{"$ref":"#/components/schemas/Period"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/Flow"},"minItems":1,"maxItems":2,"uniqueItems":true},"lineage":{"type":"object","properties":{"method":{"type":"string","const":"aggregated"},"basis":{"type":"string","const":"published_operator_links"},"counts":{"type":"object","properties":{"commodities":{"type":"string","const":"distinct commodity_scheme and commodity_code"},"months":{"type":"string","const":"distinct published period"},"links":{"type":"string","const":"distinct published link including its lineage and revision"}},"required":["commodities","months","links"],"additionalProperties":false}},"required":["method","basis","counts"],"additionalProperties":false},"address_lines":{"type":"array","items":{"type":"string","maxLength":1024}},"postal_code":{"type":"string","maxLength":1024},"country":{"type":"string","maxLength":1024},"attributes_period":{"$ref":"#/components/schemas/Period"},"links":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["source","reporter","operator_ref","name","commodities","months","first_period","last_period","flows","lineage","address_lines","postal_code","country","attributes_period","links"],"additionalProperties":false,"description":"Declared directory attributes from attributes_period. No inferred registry match, company turnover or shipment values."},"OperatorLink":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter_geo_scheme":{"type":"string","const":"iso3166-1:alpha2"},"reporter_geo_code":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"flow":{"$ref":"#/components/schemas/Flow"},"commodity_scheme":{"type":"string","enum":["CN8","HS2"]},"commodity_code":{"$ref":"#/components/schemas/CommodityCode"},"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"value":{"type":"null","description":"Directory appearance only. Company-level monetary values are not published."},"currency":{"type":"string","maxLength":16},"tier":{"type":"string","minLength":1,"maxLength":16},"method":{"type":"string","const":"declared"},"confidence":{"type":"string","minLength":1,"maxLength":16},"revision":{"$ref":"#/components/schemas/UInt32"}},"required":["source","reporter_geo_scheme","reporter_geo_code","period","flow","commodity_scheme","commodity_code","operator_ref","value","currency","tier","method","confidence","revision"],"additionalProperties":false,"allOf":[{"if":{"properties":{"commodity_scheme":{"const":"CN8"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS6"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{6}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS2"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{2}(?:------)?$"}}}}]},"TradeFlow":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"batch_key":{"$ref":"#/components/schemas/Period"},"reporter_geo_scheme":{"type":"string","const":"iso3166-1:alpha2"},"reporter_geo_code":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"flow":{"$ref":"#/components/schemas/Flow"},"commodity_scheme":{"$ref":"#/components/schemas/CommodityScheme"},"commodity_code":{"$ref":"#/components/schemas/CommodityCode"},"partner_geo_scheme":{"$ref":"#/components/schemas/GeoScheme"},"partner_geo_code":{"$ref":"#/components/schemas/GeoCode"},"location_code":{"type":"string","maxLength":128},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"tier":{"type":"string","const":"T1"},"method":{"type":"string","const":"declared"},"confidence":{"type":"string","const":"A"},"revision":{"$ref":"#/components/schemas/UInt32"},"component":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Stable ordinal within identical dimensions and revision; preserves distinct or duplicate published cells without aggregation."},"suppressed":{"type":"boolean"},"value":{"type":["number","null"]},"net_mass_kg":{"type":["number","null"]},"supplementary_unit":{"type":["number","null"]}},"required":["source","batch_key","reporter_geo_scheme","reporter_geo_code","period","flow","commodity_scheme","commodity_code","partner_geo_scheme","partner_geo_code","location_code","currency","tier","method","confidence","revision","component","suppressed","value","net_mass_kg","supplementary_unit"],"additionalProperties":false,"description":"One published source cell. Amount is in currency; mass is kilograms. Null is not zero. All measures are null for suppressed cells; non-suppressed value is a finite number. Negative adjustments and duplicate cells are preserved.","allOf":[{"if":{"properties":{"suppressed":{"const":true}}},"then":{"properties":{"value":{"type":"null"},"net_mass_kg":{"type":"null"},"supplementary_unit":{"type":"null"}}},"else":{"properties":{"value":{"type":"number"}}}},{"if":{"properties":{"commodity_scheme":{"const":"CN8"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS6"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{6}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS2"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{2}(?:------)?$"}}}}]},"Hs6Mapping":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reference_batch":{"type":"string","minLength":1,"maxLength":128},"hs6":{"anyOf":[{"type":"string","pattern":"^[0-9]{6}$"},{"type":"null"}]},"hs_version":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"valid_from":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"valid_to":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]}},"required":["source","reference_batch","hs6","hs_version","valid_from","valid_to"],"additionalProperties":false},"Commodity":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"commodity_scheme":{"$ref":"#/components/schemas/CommodityScheme"},"commodity_code":{"$ref":"#/components/schemas/CommodityCode"},"description":{"type":"string","maxLength":16384},"parent_codes":{"type":"array","items":{"type":"string","pattern":"^(?:[A-Za-z0-9-]{2}|[A-Za-z0-9-]{4}|[A-Za-z0-9-]{6})$"},"maxItems":16},"reference_batch":{"type":"string","minLength":1,"maxLength":128},"alt_scheme":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"alt_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"hs6":{"anyOf":[{"type":"string","pattern":"^[0-9]{6}$"},{"type":"null"}]},"hs6_mappings":{"type":"array","items":{"$ref":"#/components/schemas/Hs6Mapping"},"maxItems":500}},"required":["source","commodity_scheme","commodity_code","description","parent_codes","reference_batch","alt_scheme","alt_code","hs6","hs6_mappings"],"additionalProperties":false,"description":"Loaded nomenclature entry independent of trade activity. Parent and residual codes remain verbatim; a parent is not implicitly an HS6. hs6 is null when no unique mapping exists, except a loaded HS6 entry identifies itself. Validity boundaries are inclusive; null means an open boundary.","allOf":[{"if":{"properties":{"commodity_scheme":{"const":"CN8"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS6"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{6}$"}}}},{"if":{"properties":{"commodity_scheme":{"const":"HS2"}}},"then":{"properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{2}(?:------)?$"}}}}]},"Partner":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"partner_geo_scheme":{"$ref":"#/components/schemas/GeoScheme"},"partner_geo_code":{"$ref":"#/components/schemas/GeoCode"},"name":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"iso_alpha2":{"anyOf":[{"$ref":"#/components/schemas/Reporter"},{"type":"null"}]},"reference_batch":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"valid_from":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]},"valid_to":{"anyOf":[{"$ref":"#/components/schemas/Period"},{"type":"null"}]}},"required":["source","partner_geo_scheme","partner_geo_code","name","iso_alpha2","reference_batch","valid_from","valid_to"],"additionalProperties":false,"description":"A partner code present in the selected month, enriched only by the effective loaded mapping. Unmapped and residual codes remain present with null labels or ISO codes. Null validity boundaries are open."},"NewOperatorDiff":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"kind":{"type":"string","const":"new_operator"},"subject":{"type":"string","minLength":1,"maxLength":4096},"detail":{"type":"object","properties":{"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"operator_name":{"type":"string","maxLength":1024}},"required":["operator_ref","operator_name"],"additionalProperties":false},"tier":{"type":"null"},"method":{"type":"string","const":"derived"},"confidence":{"type":"null"},"revision":{"$ref":"#/components/schemas/Generation"},"basis":{"type":"string","const":"monthly-declared-cn8-v1"}},"required":["source","reporter","period","generation","kind","subject","detail","tier","method","confidence","revision","basis"],"additionalProperties":false},"OperatorReturnedDiff":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"kind":{"type":"string","const":"operator_returned"},"subject":{"type":"string","minLength":1,"maxLength":4096},"detail":{"type":"object","properties":{"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"operator_name":{"type":"string","maxLength":1024}},"required":["operator_ref","operator_name"],"additionalProperties":false},"tier":{"type":"null"},"method":{"type":"string","const":"derived"},"confidence":{"type":"null"},"revision":{"$ref":"#/components/schemas/Generation"},"basis":{"type":"string","const":"monthly-declared-cn8-v1"}},"required":["source","reporter","period","generation","kind","subject","detail","tier","method","confidence","revision","basis"],"additionalProperties":false},"NewOperatorCommodityDiff":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"kind":{"type":"string","const":"new_operator_commodity"},"subject":{"type":"string","minLength":1,"maxLength":4096},"detail":{"type":"object","properties":{"operator_ref":{"$ref":"#/components/schemas/OperatorRef"},"operator_name":{"type":"string","maxLength":1024},"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"},"commodity_scheme":{"type":"string","const":"CN8"},"flow":{"$ref":"#/components/schemas/Flow"}},"required":["operator_ref","operator_name","commodity_code","commodity_scheme","flow"],"additionalProperties":false},"tier":{"type":"null"},"method":{"type":"string","const":"derived"},"confidence":{"type":"null"},"revision":{"$ref":"#/components/schemas/Generation"},"basis":{"type":"string","const":"monthly-declared-cn8-v1"}},"required":["source","reporter","period","generation","kind","subject","detail","tier","method","confidence","revision","basis"],"additionalProperties":false},"NewPartnerForCommodityDiff":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"kind":{"type":"string","const":"new_partner_for_commodity"},"subject":{"type":"string","minLength":1,"maxLength":4096},"detail":{"type":"object","properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"},"commodity_scheme":{"type":"string","const":"CN8"},"flow":{"$ref":"#/components/schemas/Flow"},"partner_geo_scheme":{"type":"string","minLength":1,"maxLength":1024},"partner_geo_code":{"type":"string","minLength":1,"maxLength":1024}},"required":["commodity_code","commodity_scheme","flow","partner_geo_scheme","partner_geo_code"],"additionalProperties":false},"tier":{"type":"null"},"method":{"type":"string","const":"derived"},"confidence":{"type":"null"},"revision":{"$ref":"#/components/schemas/Generation"},"basis":{"type":"string","const":"monthly-declared-cn8-v1"}},"required":["source","reporter","period","generation","kind","subject","detail","tier","method","confidence","revision","basis"],"additionalProperties":false},"CommodityValueChangeDiff":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/Source"},"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"generation":{"$ref":"#/components/schemas/Generation"},"kind":{"type":"string","const":"commodity_value_change"},"subject":{"type":"string","minLength":1,"maxLength":4096},"detail":{"type":"object","properties":{"commodity_code":{"type":"string","pattern":"^[0-9]{8}$"},"commodity_scheme":{"type":"string","const":"CN8"},"flow":{"$ref":"#/components/schemas/Flow"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"previous_value":{"type":"string","description":"Finite numeric amount encoded as text; preserve decimal representation.","maxLength":1024,"pattern":"^ *[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)? *$"},"current_value":{"type":"string","description":"Finite numeric amount encoded as text; preserve decimal representation.","maxLength":1024,"pattern":"^ *[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)? *$"}},"required":["commodity_code","commodity_scheme","flow","currency","previous_value","current_value"],"additionalProperties":false},"tier":{"type":"null"},"method":{"type":"string","const":"derived"},"confidence":{"type":"null"},"revision":{"$ref":"#/components/schemas/Generation"},"basis":{"type":"string","const":"monthly-declared-cn8-v1"}},"required":["source","reporter","period","generation","kind","subject","detail","tier","method","confidence","revision","basis"],"additionalProperties":false},"ReleaseDiff":{"oneOf":[{"$ref":"#/components/schemas/NewOperatorDiff"},{"$ref":"#/components/schemas/OperatorReturnedDiff"},{"$ref":"#/components/schemas/NewOperatorCommodityDiff"},{"$ref":"#/components/schemas/NewPartnerForCommodityDiff"},{"$ref":"#/components/schemas/CommodityValueChangeDiff"}],"description":"Derived comparison of published monthly CN8 declarations. revision is the generation hash, not an integer. tier and confidence are null rather than inferred source scores."},"ExportJob":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","running","completed","failed","expired"]},"format":{"type":"string","enum":["csv","parquet"]},"endpoint":{"type":"string","pattern":"^/(?:reporters|releases|operators|flows|partners|diffs|operators/hmrc_uktradeinfo/[0-9]{1,12}/links)$"},"cap":{"type":"integer","minimum":1,"maximum":100000},"rows":{"type":"integer","minimum":0,"maximum":100000},"bytes":{"type":"integer","minimum":0,"maximum":268435456},"truncated":{"type":"boolean","description":"True when further rows existed after the cap; false for a complete result, including an empty one."},"created_at":{"$ref":"#/components/schemas/Instant"},"expires_at":{"$ref":"#/components/schemas/Instant"},"finished_at":{"anyOf":[{"$ref":"#/components/schemas/Instant"},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string","enum":["invalid_request","publication_changed","api_unavailable","export_expired","export_access_denied","export_too_large","export_failed","storage_unavailable"]},{"type":"null"}]},"status_url":{"type":"string","pattern":"^/v1/exports/[a-f0-9-]{36}$"},"download_url":{"anyOf":[{"type":"string","pattern":"^/v1/exports/[a-f0-9-]{36}/download$"},{"type":"null"}]}},"required":["id","status","format","endpoint","cap","rows","bytes","truncated","created_at","expires_at","finished_at","error_code","status_url","download_url"],"additionalProperties":false,"description":"Private to the creating API key and organisation. cap is the minimum of row_limit, the organisation allowance and 100000. download_url is non-null only for completed jobs; the property is always returned. Files expire 24 hours after creation; queue deadline is 30 minutes."},"ReportersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReporterRecord"}},"meta":{"$ref":"#/components/schemas/CountMeta"}},"required":["data","meta"],"additionalProperties":false},"ReleasesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseRecord"},"maxItems":500},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"],"additionalProperties":false},"OperatorsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorSearchRecord"},"maxItems":500},"meta":{"$ref":"#/components/schemas/PublishedPageMeta"}},"required":["data","meta"],"additionalProperties":false},"OperatorResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorProfile"},"meta":{"$ref":"#/components/schemas/PublishedMeta"}},"required":["data","meta"],"additionalProperties":false},"LinksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorLink"},"maxItems":500},"meta":{"$ref":"#/components/schemas/PublishedPageMeta"}},"required":["data","meta"],"additionalProperties":false},"FlowsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TradeFlow"},"maxItems":500},"meta":{"$ref":"#/components/schemas/FlowMeta"}},"required":["data","meta"],"additionalProperties":false},"CommodityResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Commodity"},"meta":{"$ref":"#/components/schemas/ReferenceMeta"}},"required":["data","meta"],"additionalProperties":false},"PartnersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Partner"},"maxItems":500},"meta":{"$ref":"#/components/schemas/PartnerMeta"}},"required":["data","meta"],"additionalProperties":false},"DiffsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseDiff"},"maxItems":500},"meta":{"$ref":"#/components/schemas/DiffMeta"}},"required":["data","meta"],"additionalProperties":false},"ExportResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExportJob"},"meta":{"$ref":"#/components/schemas/PublishedMeta"}},"required":["data","meta"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","invalid_cursor","invalid_api_key","api_access_denied","scope_denied","market_denied","diffs_denied","not_found","method_not_allowed","publication_changed","export_limit","export_unavailable","export_expired","export_access_denied","export_too_large","unsupported_media_type","payload_too_large","api_quota_exhausted","api_rate_limited","api_unavailable"]},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"ReportersExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/reporters"},"params":{"type":"object","properties":{},"required":[],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"ReleasesExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/releases"},"params":{"type":"object","properties":{"reporter":{"$ref":"#/components/schemas/Reporter"}},"required":[],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"OperatorsExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/operators"},"params":{"type":"object","properties":{"q":{"type":"string","minLength":2,"maxLength":80},"reporter":{"$ref":"#/components/schemas/Reporter"}},"required":["q"],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"LinksExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","pattern":"^/operators/hmrc_uktradeinfo/[0-9]{1,12}/links$"},"params":{"type":"object","properties":{"from":{"$ref":"#/components/schemas/Period"},"to":{"$ref":"#/components/schemas/Period"}},"required":[],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"FlowsExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/flows"},"params":{"type":"object","properties":{"reporter":{"$ref":"#/components/schemas/Reporter"},"commodity":{"$ref":"#/components/schemas/CommodityCode"},"commodity_scheme":{"$ref":"#/components/schemas/CommodityScheme","default":"CN8"},"partner":{"$ref":"#/components/schemas/GeoCode"},"partner_scheme":{"$ref":"#/components/schemas/GeoScheme"},"flow":{"$ref":"#/components/schemas/Flow"},"from":{"$ref":"#/components/schemas/Period"},"to":{"$ref":"#/components/schemas/Period"}},"required":[],"additionalProperties":false,"dependentRequired":{"partner_scheme":["partner"]},"allOf":[{"if":{"required":["commodity","commodity_scheme"],"properties":{"commodity_scheme":{"const":"CN8"}}},"then":{"properties":{"commodity":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"required":["commodity","commodity_scheme"],"properties":{"commodity_scheme":{"const":"HS6"}}},"then":{"properties":{"commodity":{"type":"string","pattern":"^[0-9]{6}$"}}}},{"if":{"required":["commodity","commodity_scheme"],"properties":{"commodity_scheme":{"const":"HS2"}}},"then":{"properties":{"commodity":{"type":"string","pattern":"^[0-9]{2}(?:------)?$"}}}},{"if":{"required":["commodity"],"not":{"required":["commodity_scheme"]}},"then":{"properties":{"commodity":{"type":"string","pattern":"^[0-9]{8}$"}}}},{"if":{"required":["partner"],"not":{"required":["partner_scheme"]}},"then":{"properties":{"partner":{"type":"string","pattern":"^[A-Z]{2}$"}}}}]},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"PartnersExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/partners"},"params":{"type":"object","properties":{"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"}},"required":[],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"DiffsExportRequest":{"type":"object","properties":{"endpoint":{"type":"string","const":"/diffs"},"params":{"type":"object","properties":{"reporter":{"$ref":"#/components/schemas/Reporter"},"period":{"$ref":"#/components/schemas/Period"},"kind":{"$ref":"#/components/schemas/DiffKind"}},"required":[],"additionalProperties":false},"format":{"type":"string","enum":["csv","parquet"]},"row_limit":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"required":["endpoint","params","format"],"additionalProperties":false},"ExportRequest":{"oneOf":[{"$ref":"#/components/schemas/ReportersExportRequest"},{"$ref":"#/components/schemas/ReleasesExportRequest"},{"$ref":"#/components/schemas/OperatorsExportRequest"},{"$ref":"#/components/schemas/LinksExportRequest"},{"$ref":"#/components/schemas/FlowsExportRequest"},{"$ref":"#/components/schemas/PartnersExportRequest"},{"$ref":"#/components/schemas/DiffsExportRequest"}]}}}}