{"components":{"securitySchemes":{"cetaKey":{"description":"A Ceta API key, `ck_live_…:<secret>` or `ck_test_…:<secret>`.","scheme":"bearer","type":"http"}}},"info":{"description":"Products, orders and supplier intelligence from Ceta Traders, the marketplace of the EU and Canada. Authenticate with a Ceta key: `Authorization: Bearer <key_id>:<secret>`.","title":"Ceta Traders API","version":"v1"},"openapi":"3.1.0","paths":{"/api/v1/buyers":{"get":{"description":"Companies a national register observed importing a commodity. No score: an observation is not a match. `caveat` carries the register's scope. Scope: `read`.","operationId":"buyers","parameters":[{"description":"Commodity.","in":"query","name":"product","required":false,"schema":{"type":"string"}},{"description":"Importing country, ISO alpha-2.","in":"query","name":"country","required":false,"schema":{"type":"string"}},{"description":"1–100, default 25.","in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"attribution":["Canadian Importers Database (Open Government Licence – Canada)"],"caveat":"The register lists major importers; absence is not evidence that a company does not import.","count":1,"data":[{"company":{"city":"Toronto","confidence":90,"country":"CA","id":"3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a","legal_name":"Torréfaction du Port SAS","region":"CA-ON","trade_name":"Café du Port","website":"https://cafeduport.example"}}],"gaps":[],"query":{"country_iso2":"CA","product":"coffee"}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Find buyers (observed importers)","tags":["Supplier intelligence"]}},"/api/v1/orders":{"get":{"description":"Tenant-scoped: only the key's own organization's orders (none for a test key's sandbox tenant). Scope: `read`.","operationId":"orders","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"count":1,"data":[{"buyer_ref":"PO-2026-118","channel":"online","currency":"EUR","id":"9a7e1c44-3b2f-4d5e-8f60-7a1b2c3d4e5f","payment_provider":"malaleem","placed_at":"2026-11-12T09:41:07Z","status":"paid","subtotal_cents":420000,"total_cents":420000}]}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Your organization's orders","tags":["Marketplace"]}},"/api/v1/orders/{id}":{"get":{"description":"Another organization's order answers 404, never 403 — saying forbidden would confirm it exists. Scope: `read`.","operationId":"order","parameters":[{"description":"The order id.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"buyer_ref":"PO-2026-118","channel":"online","currency":"EUR","id":"9a7e1c44-3b2f-4d5e-8f60-7a1b2c3d4e5f","lines":[{"id":"1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b","line_total_cents":420000,"product_id":"6f1c2a9e-4b1d-4a43-9c55-1d2f4e8a7b10","qty":10,"title":"Arabica green coffee, 60 kg bag","unit_price_cents":42000,"vendor":{"id":"0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22","name":"Lisboa Roasters Lda"}}],"payment_provider":"malaleem","payouts":[{"commission_bps":1000,"commission_cents":42000,"currency":"EUR","gross_cents":420000,"net_cents":378000,"vendor_id":"0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22"}],"placed_at":"2026-11-12T09:41:07Z","status":"paid","subtotal_cents":420000,"total_cents":420000}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"404":{"content":{"application/json":{"example":{"error":"not_found"}}},"description":"No such order for this organization."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"One order, its lines and per-vendor payouts","tags":["Marketplace"]}},"/api/v1/products":{"get":{"description":"Search with `q`, or list published products filtered by `channel`. Amounts are integer minor units with the currency beside them. Scope: `read`.","operationId":"products","parameters":[{"description":"Full-text search.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"`b2b` or `b2c`.","in":"query","name":"channel","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"count":1,"data":[{"category":"coffee","channel":"b2b","currency":"EUR","description":"Washed, screen 16+, crop 2026.","id":"6f1c2a9e-4b1d-4a43-9c55-1d2f4e8a7b10","image_url":"https://cetatraders.com/files/ceta-uploads/products/cof-ara-60.jpg","min_order_qty":10,"price_cents":42000,"sku":"COF-ARA-60","title":"Arabica green coffee, 60 kg bag","vendor":{"id":"0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22","name":"Lisboa Roasters Lda"}}]}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Published products","tags":["Marketplace"]}},"/api/v1/reference/resolve":{"get":{"description":"Free text → canonical product → HS codes, with how it was matched and how sure. Scope: `read`.","operationId":"resolve","parameters":[{"description":"e.g. `green coffee beans`.","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"canonical_key":"coffee","confidence":95,"hs_codes":["090111"],"match":"synonym","name":"Coffee","query":"green coffee beans"}}}},"description":"OK"},"400":{"content":{"application/json":{"example":{"error":"q is required"}}},"description":"No `q`."},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Resolve a product to its classification","tags":["Reference"]}},"/api/v1/sources":{"get":{"description":"The source registry: status, tier and the permissions (store, display, redistribute, expose_api, train_ai). Scope: `read`.","operationId":"sources","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"count":1,"coverage":[],"data":[{"key":"fr_sirene","name":"INSEE Sirene","organization":"INSEE","permits":{"display":true,"expose_api":true,"redistribute":true,"store":true,"train_ai":false},"status":"verified","tier":1}]}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Data sources and what each permits","tags":["Reference"]}},"/api/v1/status":{"get":{"description":"Connectivity, and what this key is allowed to do. A test key answers its sandbox tenant's organization id and `mode: \"test\"`. Scope: `read`.","operationId":"status","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"mode":"live","name":"Ceta Traders API","organization_id":"5d0e8a3c-2f41-4b7a-9e1d-6c5b4a392817","scopes":["read"],"time":"2026-11-14T10:00:00.000000Z","version":"v1"}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Check your key","tags":["Account"]}},"/api/v1/suppliers":{"get":{"description":"Explained ranking: every signal is reported, including those that scored zero. Records whose source licence forbids redistribution through an API are withheld and counted. Scope: `read`.","operationId":"suppliers","parameters":[{"description":"Free text or a canonical key, e.g. `coffee`.","in":"query","name":"product","required":false,"schema":{"type":"string"}},{"description":"ISO 3166-1 alpha-2.","in":"query","name":"country","required":false,"schema":{"type":"string"}},{"description":"First-level division code.","in":"query","name":"region","required":false,"schema":{"type":"string"}},{"description":"City name.","in":"query","name":"city","required":false,"schema":{"type":"string"}},{"description":"e.g. `exporter`, `manufacturer`.","in":"query","name":"role","required":false,"schema":{"type":"string"}},{"description":"ISO country you sell into.","in":"query","name":"target_market","required":false,"schema":{"type":"string"}},{"description":"1–100, default 25.","in":"query","name":"limit","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"attribution":["INSEE Sirene (Licence Ouverte 2.0)"],"count":1,"data":[{"company":{"city":"Paris","confidence":90,"country":"FR","id":"3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a","legal_name":"Torréfaction du Port SAS","region":"FR-IDF","trade_name":"Café du Port","website":"https://cafeduport.example"},"gaps":[],"score":72,"signals":[{"explanation":"NAF 10.83Z maps to coffee","key":"product_match","score":36,"weight":40}]}],"gaps":[],"query":{"country_iso2":"FR","product":"coffee"},"withheld":{"api":0,"display":0}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Find suppliers","tags":["Supplier intelligence"]}},"/api/v1/suppliers/{id}":{"get":{"description":"Everything held about a company: roles, products, identifiers, trade activity. Scope: `read`.","operationId":"supplier","parameters":[{"description":"Company id.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"attribution":["INSEE Sirene (Licence Ouverte 2.0)"],"data":{"activity":[],"company":{"city":"Paris","confidence":90,"country":"FR","id":"3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a","legal_name":"Torréfaction du Port SAS","region":"FR-IDF","trade_name":"Café du Port","website":"https://cafeduport.example"},"identifiers":[{"scheme":"siren","value":"552100554"}],"products":[{"canonical_key":"coffee","hs_code":"090111","self_declared":false}],"roles":[{"confidence":90,"role":"manufacturer","self_declared":false}]}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"404":{"content":{"application/json":{"example":{"error":"not_found"}}},"description":"No such company."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"One company","tags":["Supplier intelligence"]}},"/api/v1/trade/market":{"get":{"description":"A country-level statistic — never evidence about any company. Scope: `read`.","operationId":"market","parameters":[{"description":"Commodity.","in":"query","name":"product","required":true,"schema":{"type":"string"}},{"description":"Exporting country.","in":"query","name":"country","required":true,"schema":{"type":"string"}},{"description":"Importing country.","in":"query","name":"target_market","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"attribution":["UN Comtrade"],"caveat":"Country-level trade statistics, not company data.","data":{"concept":"export_value","observations":5,"value_usd":"1250000000","years":[2021,2022,2023,2024,2025]}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"422":{"content":{"application/json":{"example":{"error":"could not resolve the product or country"}}},"description":"Unknown product or country."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Market size for a lane","tags":["Supplier intelligence"]}},"/api/v1/vendors":{"get":{"description":"The vendors on the B2B marketplace. Scope: `read`.","operationId":"vendors","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"count":1,"data":[{"country":"PT","id":"0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22","name":"Lisboa Roasters Lda","status":"active"}]}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Vendors","tags":["Marketplace"]}},"/api/v1/verification":{"get":{"description":"A key acts for the person who issued it, so it can transact only while Authpermit has that person verified (RAL3). Test keys never transact. Scope: `read`.","operationId":"verification","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"can_transact":true,"status":"verified"}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Can this key transact?","tags":["Account"]}},"/mcp":{"post":{"description":"JSON-RPC 2.0: `initialize`, `ping`, `tools/list`, `tools/call`. The same tenant scoping and permissions as the REST API; a tool error is a result with `isError: true`. Scope: `mcp`.","operationId":"mcp","parameters":[],"requestBody":{"content":{"application/json":{"example":{"id":1,"jsonrpc":"2.0","method":"tools/list"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":1,"jsonrpc":"2.0","result":{"tools":[{"description":"Full-text search across published products. Prices are integer minor units (price_cents) with the currency alongside …","inputSchema":{"required":["query"],"type":"object"},"name":"search_products","title":"Search the marketplace catalogue"}]}}}},"description":"OK"},"401":{"content":{"application/json":{"example":{"error":"invalid_api_key"}}},"description":"No key, or the key is wrong, revoked or past its rotation grace."},"403":{"content":{"application/json":{"example":{"error":"insufficient_scope"}}},"description":"The key is valid but lacks the scope this endpoint needs."},"429":{"content":{"application/json":{"example":{"error":"rate_limited"}}},"description":"More calls in a minute than the organization's limit."}},"summary":"Model Context Protocol server","tags":["Agents (MCP)"]}}},"security":[{"cetaKey":[]}],"servers":[{"url":"https://cetatraders.com"}]}