{"openapi":"3.1.0","info":{"title":"border.bot API (v1)","version":"1.6.0","description":"Classify products to HS/HTS codes and calculate duties, taxes, fees and landed cost for cross-border parcels.\n\n**Versions**: This is **v1**, the current version. Within a version, changes are only additive (new endpoints, new optional fields, new enum values). Breaking changes ship as a new version; every version and its dates: https://staging-api.border.bot/versions\n\n**Authentication**: send a workspace API key: `Authorization: Bearer bb_live_…`. Create keys in the dashboard.\n\n**Credits**: billable requests use prepaid credits (see `GET /v1/pricing`). Prices are set server-side; failed requests are refunded automatically. Every response includes `X-Request-Id` (a UUID; quote it to support) and `API-Version`; billable responses include `X-Credits-Charged` and `X-Credits-Remaining`.\n\n**Retries**: send an `Idempotency-Key` header on POST requests; repeating it returns the original result without charging again.\n\n**Rate limits**: 120 requests per 60 seconds per API key, and per IP address for public endpoints. Responses carry the IETF `RateLimit-Policy` header (`\"key\";q=120;w=60` with a key, `\"ip\";q=120;w=60` without). Over the limit you get 429 `rate_limited` with `RateLimit: \"key\";r=0;t=60` and `Retry-After` in seconds; wait that long before retrying.\n\n**Errors**: `{ \"error\": { \"code\", \"message\", \"details\"? } }` with a stable `code` (e.g. 402 `insufficient_credits`, 429 `rate_limited`).\n\n**MCP**: use border.bot from Claude, ChatGPT, Codex, Cursor, VS Code and other MCP clients at `https://staging-mcp.border.bot/mcp` (OAuth, no API key). Setup guides: https://staging.border.bot/mcp","contact":{"name":"border.bot","email":"info@border.bot","url":"https://staging.border.bot"},"termsOfService":"https://staging.border.bot/legal/terms"},"servers":[{"url":"https://staging-api.border.bot","description":"Development"}],"tags":[{"name":"Classification","description":"HS/HTS codes."},{"name":"Landed cost","description":"Duties, taxes and fees."},{"name":"Products","description":"Product pages and country of origin."},{"name":"Compliance","description":"Restricted and prohibited goods (free)."},{"name":"Account","description":"Your workspace, credits and usage."},{"name":"Reference","description":"Public reference data (no key needed)."}],"externalDocs":{"description":"Docs and guides: quickstart, endpoint reference and MCP setup","url":"https://staging.border.bot/docs"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"bb_live_…","description":"Workspace API key. Create and revoke keys in the dashboard (Developers → API keys). Keys are shown once and stored only as a hash."}},"schemas":{"ClassifyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClassificationResult"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"ClassificationResult":{"type":"object","properties":{"hsCode":{"type":"string","description":"Digits only.","example":"6109100012"},"hsCodeFormatted":{"type":"string","example":"6109.10.00.12"},"nomenclature":{"type":"string","enum":["us","ca","eu","gb","global","national"],"description":"The tariff the code comes from: a national one (`us`, `ca`, `eu`, `gb`, or `national` for any other country, named by `schedule`), or the 6-digit `global` HS."},"destinationCountry":{"type":"string"},"description":{"type":"string","description":"Most specific official description for the code, in the tariff’s own language (the legal text)."},"englishDescription":{"type":"string","description":"The line in English, when the tariff’s own text isn’t: border.bot’s rendering for reading, not the legal text.","example":"T-shirts, singlets and other vests, knitted: of cotton"},"hierarchy":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["chapter","heading","subheading","tariff"]},"code":{"type":"string"},"description":{"type":"string"}},"required":["level","code","description"]}},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"abbreviation":{"type":["string","null"]},"label":{"type":["string","null"]},"unit":{"type":["string","null"]},"direction":{"type":"string","enum":["both","import"]},"origins":{"type":["array","null"],"items":{"type":"string"}}},"required":["code","abbreviation","label","unit","direction","origins"]},"description":"The quantities the line is declared in besides the net mass (the EU’s CN supplementary units: `p/st` number of items, `l` litres, `kg/net eda` drained net weight), with the publisher’s code, the unit border.bot counts, and whether it applies to imports only or to some origins only. Absent when the tariff sets none."},"confidence":{"type":"string","enum":["high","medium","low"]},"score":{"type":["number","null"]},"probability":{"type":["number","null"]},"needsReview":{"type":"boolean","description":"The engine recommends a human review before filing."},"reasoning":{"type":["string","null"]},"customsDescription":{"type":["string","null"]},"alternatives":{"type":"array","items":{"type":"object","properties":{"hsCode":{"type":"string"},"hsCodeFormatted":{"type":"string"},"description":{"type":"string"},"englishDescription":{"type":"string"},"score":{"type":["number","null"]},"confidence":{"type":"string","enum":["high","medium","low"]},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"abbreviation":{"type":["string","null"]},"label":{"type":["string","null"]},"unit":{"type":["string","null"]},"direction":{"type":"string","enum":["both","import"]},"origins":{"type":["array","null"],"items":{"type":"string"}}},"required":["code","abbreviation","label","unit","direction","origins"]}}},"required":["hsCode","hsCodeFormatted","description","score","confidence"]}},"mode":{"type":"string","description":"The mode asked for (or the default mode).","example":"pro"},"modesRun":{"type":"array","items":{"type":"string"},"description":"The modes that ran, the one asked for first: a later one ran because the answer before it was not confident enough (escalation). You are charged the mode you asked for only."},"upstreamRequestId":{"type":["string","null"]},"schedule":{"type":"string","description":"Tariff schedule that answered, e.g. `US`, or `EU` for an EU member destination."},"readFromUrl":{"type":["string","null"],"description":"What the engine read from the product URL, when it read one."},"readFromImage":{"type":["string","null"],"description":"What the engine saw in the product photo, when one was classified."},"rulings":{"type":"array","items":{"type":"object","properties":{"rulingNumber":{"type":"string"},"code":{"type":["string","null"]},"subject":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["rulingNumber","code","subject","url"]},"description":"Precedent rulings consulted (e.g. CBP CROSS), when the mode uses them."},"dataSource":{"$ref":"#/components/schemas/TariffDataSource"},"engine":{"type":"string","enum":["borderbot"],"description":"The engine that answered."},"identifiedAs":{"type":"string","description":"What a web search identified the product as, when the listing didn’t say (brand names, model numbers, titles)."},"webSources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://www.example.com/products/sn99"},"title":{"type":["string","null"],"example":"Out of Office SN99 sneaker"}},"required":["url","title"]},"description":"The pages that identification relied on, to show with it. Empty when the model answered without searching."},"materialUncertain":{"type":"boolean","description":"The code rests on a material the description never stated: confirm it before filing."},"valueUncertain":{"type":"boolean","description":"The code sits in a unit-value band no price confirmed: send `price`."},"product":{"$ref":"#/components/schemas/ProductExtraction"},"origin":{"$ref":"#/components/schemas/OriginInference"}},"required":["hsCode","hsCodeFormatted","nomenclature","destinationCountry","description","hierarchy","confidence","score","probability","needsReview","reasoning","customsDescription","alternatives","mode","upstreamRequestId"]},"TariffDataSource":{"type":["object","null"],"properties":{"version":{"type":["string","null"],"description":"The tariff edition (its release’s version label)."},"importedAt":{"type":["string","null"],"description":"When that edition went live."},"datasets":{"type":"array","items":{"type":"object","properties":{"dataset":{"type":"string","example":"US:rates"},"seq":{"type":"integer"},"releaseId":{"type":["string","null"],"format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"version":{"type":["string","null"]},"liveSince":{"type":["string","null"]}},"required":["dataset","seq","releaseId","version","liveSince"]},"description":"border.bot’s own engine: every dataset the answer read (rates, measures, taxes, fees…), at its release."}},"required":["version","importedAt"],"description":"Tariff data that answered."},"ProductExtraction":{"type":"object","properties":{"url":{"type":"string"},"finalUrl":{"type":"string"},"siteName":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"brand":{"type":["string","null"]},"sku":{"type":["string","null"]},"gtin":{"type":["string","null"]},"mpn":{"type":["string","null"]},"category":{"type":["string","null"]},"material":{"type":["string","null"]},"color":{"type":["string","null"]},"price":{"type":["number","null"]},"currency":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"countryOfOrigin":{"type":["string","null"],"description":"ISO-2 when the page states where the product is made."},"originEvidence":{"type":["string","null"]},"sources":{"type":"array","items":{"type":"string","enum":["json-ld","microdata","open-graph","meta","text"]}},"summary":{"type":"string","description":"Compact text used as the classification description."}},"required":["url","finalUrl","siteName","title","description","brand","sku","gtin","mpn","category","material","color","price","currency","images","countryOfOrigin","originEvidence","sources","summary"]},"OriginInference":{"type":"object","properties":{"country":{"type":["string","null"],"description":"Most likely country of origin (ISO-2); null when nothing points anywhere."},"confidence":{"type":"string","enum":["high","medium","low","none"],"description":"`high` ≥ 0.8 (a direct statement nothing contradicts), `medium` ≥ 0.55, `low` below. An AI estimate alone is never high."},"source":{"type":"string","enum":["user","structured_data","page_text","image","ai","ship_from","barcode","none"],"description":"What the answer rests on most."},"evidence":{"type":["string","null"]},"candidates":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"score":{"type":"number"}},"required":["country","score"]},"description":"The most likely countries with their probability; the first is `country`."},"probability":{"type":"number","description":"Probability that `country` is right (0–1)."},"alternates":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"probability":{"type":"number"}},"required":["country","probability"]},"description":"The next most likely countries."},"signals":{"type":"array","items":{"$ref":"#/components/schemas/OriginSignal"}},"needsReview":{"type":"boolean","description":"Have a person confirm it: the probability is below `reviewThreshold`, nothing points anywhere, or strong evidence disagrees."},"reviewReason":{"type":["string","null"],"description":"Why it needs review, in words; null when it doesn’t."},"reviewThreshold":{"type":"number","description":"The threshold applied: the request’s `reviewThreshold`, else the workspace’s setting, else the platform default."},"reasoning":{"type":["string","null"],"description":"The AI estimate’s reasoning, when one was made."}},"required":["country","confidence","source","evidence","candidates"]},"OriginSignal":{"type":"object","properties":{"kind":{"type":"string","enum":["user","structured_data","page_text","image","ai","ship_from","barcode"]},"country":{"type":"string"},"weight":{"type":"number","description":"How much this evidence counts (0–1)."},"evidence":{"type":"string"}},"required":["kind","country","weight","evidence"],"description":"One piece of evidence: the page’s product data (0.95), “Made in …” text (0.55–0.97), a label in the photo (0.85), an AI estimate (at most 0.7), the ship-from country (0.2), the barcode’s GS1 prefix (0.1)."},"CreditsCharged":{"type":"object","properties":{"charged":{"type":"integer","description":"Credits charged for this request (0 when replayed or free)."},"remaining":{"type":"integer","description":"Workspace balance after this request."},"usageId":{"type":["string","null"],"description":"Usage event id (see `GET /v1/usage`)."}},"required":["charged","remaining","usageId"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_input","unauthorized","forbidden","not_found","conflict","insufficient_credits","quota_exceeded","rate_limited","turnstile_failed","network_blocked","action_disabled","org_suspended","unsupported_country","upstream_error","upstream_timeout","version_retired","payload_too_large","internal"],"description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"details":{"description":"Extra context, e.g. `{ required, balance }` for `insufficient_credits` or `{ retryAfterSeconds }` for `rate_limited`."}},"required":["code","message"]},"requestId":{"type":"string","format":"uuid","description":"Echoes the `X-Request-Id` response header: a UUIDv7, lowercase.","example":"0199c8d2-5b1e-7c3a-9f4e-2d6b8a1c3e5f"}},"required":["error"],"example":{"error":{"code":"insufficient_credits","message":"This needs 1 credit but the workspace has 0. Top up to continue.","details":{"required":1,"balance":0}},"requestId":"0199c8d2-5b1e-7c3a-9f4e-2d6b8a1c3e5f"}},"ClassifyRequest":{"type":"object","properties":{"description":{"type":"string","minLength":2,"maxLength":2000,"description":"What the product is: type, material/composition, intended use and user. Required unless `productUrl` or `imageUrl` is given.","example":"Men's short-sleeve t-shirt, 100% cotton, knitted"},"productUrl":{"type":"string","maxLength":2048,"description":"Product page URL. border.bot reads the listing (title, brand, materials, price and any stated country of origin) and classifies from it, with your description when you give one.","example":"https://shop.example.com/products/organic-tee"},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}],"description":"A product photo, classified with vision (in the modes that read photos: see `GET /v1/classify/modes`): a public URL, or the picture itself as a `data:image/jpeg;base64,…` URL (up to 6 MB). When given, the photo is classified instead of the listing URL.","example":"https://cdn.example.com/images/organic-tee.jpg"},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Where the parcel is going: selects the tariff (the national one where border.bot has it, else the 6-digit HS). ISO 3166-1 alpha-2, case-insensitive.","example":"US"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Where the product was made (context only). ISO 3166-1 alpha-2, case-insensitive.","example":"PT"},"mode":{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,30}$","description":"The classification mode: one of the modes `GET /v1/classify/modes` lists (each with its price and what it reads). Omitted: the default mode. An unknown or unavailable mode is refused (`invalid_input`, with `details.availableModes`).","example":"pro"},"title":{"type":"string","maxLength":300,"description":"Product title (optional extra context)."},"brand":{"type":"string","maxLength":120,"description":"Brand (optional extra context)."},"sku":{"type":"string","maxLength":120,"description":"Your SKU (stored with the usage record)."},"price":{"type":"number","minimum":0,"maximum":10000000,"description":"Unit price (optional context)."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 currency of `price`.","example":"USD"},"hsCodeHint":{"type":"string","pattern":"^\\d[\\d.]{1,12}$","description":"An HS code you believe is close (2–10 digits) — used as a hint, not trusted blindly."}},"required":["destinationCountry"],"example":{"description":"Men's short-sleeve t-shirt, 100% cotton, knitted","destinationCountry":"US","originCountry":"PT"}},"ClassifyBatchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"classification":{"$ref":"#/components/schemas/ClassificationResult"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","ok"]}}},"required":["results"]},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"remaining":{"type":["integer","null"]}},"required":["charged","remaining"]}},"required":["data","credits"]},"ClassifyBatchRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClassifyRequest"},"minItems":1,"maxItems":25}},"required":["items"],"description":"Up to 25 products, each a classify request. Each is charged as one classification (by its own mode) and refunded on its own if it fails.","example":{"items":[{"description":"Men's short-sleeve t-shirt, 100% cotton, knitted","destinationCountry":"US"},{"description":"Stainless steel water bottle, 750 ml","destinationCountry":"GB"}]}},"RegulatorClassifyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RegulatorClassification"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"RegulatorClassification":{"type":"object","properties":{"agency":{"type":"string","description":"The import agency’s short name.","example":"FDA"},"agencyName":{"type":"string","example":"U.S. Food and Drug Administration"},"scheme":{"type":"string","description":"The agency coding scheme’s id.","example":"us-fda"},"codeName":{"type":"string","description":"What the agency’s codes are called.","example":"FDA product code"},"destinationCountry":{"type":"string"},"productCode":{"type":"string","description":"The assembled code, as the agency expects it on the entry.","example":"16AYN07"},"validated":{"type":"boolean","description":"The agency’s own check accepted the code."},"checked":{"type":"boolean","description":"Whether the agency’s check was asked (false: the code is assembled but unchecked)."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/AgencyCodePart"},"description":"The code’s parts in order (for FDA: industry, class, subclass, process and product group; an unstated subclass or process is the N.E.C. value)."},"product":{"type":["object","null"],"properties":{"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description"],"description":"The agency’s product the code was built from."},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning":{"type":["string","null"]}},"required":["agency","agencyName","scheme","codeName","destinationCountry","productCode","validated","checked","parts","product","confidence","reasoning"]},"AgencyCodePart":{"type":"object","properties":{"level":{"type":"string","description":"Which part, stable within the scheme.","example":"industry"},"label":{"type":"string","description":"The part’s name in the agency’s terms.","example":"Industry"},"code":{"type":"string","example":"16"},"description":{"type":"string","example":"Fishery/Seafood Products"}},"required":["level","label","code","description"]},"RegulatorClassifyRequest":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":2000,"description":"What the product is, what it is made of, and how it is processed or packed (frozen, smoked, canned…).","example":"Smoked Atlantic salmon fillets, vacuum packed"},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Where the goods are imported. Its import agency and coding scheme follow from it (for `US`, FDA’s import product codes).","example":"US"},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]{4,16}$","description":"The goods’ tariff code, when known: a hint for the product pick.","example":"0305.41"}},"required":["description","destinationCountry"]},"ClassifyModesResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"destination":{"type":["string","null"]},"engine":{"type":["string","null"],"enum":["borderbot",null],"description":"The engine that classifies for the destination (null: no destination given, or border.bot doesn’t classify there yet)."},"defaultMode":{"type":["string","null"],"description":"The mode a request without `mode` runs."},"modes":{"type":"array","items":{"type":"object","properties":{"mode":{"type":"string","example":"pro"},"label":{"type":"string"},"description":{"type":["string","null"]},"available":{"type":"boolean"},"credits":{"type":["number","null"],"description":"Credits per classification; null when switched off."},"photos":{"type":"boolean","description":"Reads a product photo (`imageUrl`)."},"inlinePhotos":{"type":"boolean","description":"Reads a photo sent inline as a base64 data URL in `imageUrl`."}},"required":["mode","label","description","available","credits","photos","inlinePhotos"]}}},"required":["destination","engine","defaultMode","modes"]}},"required":["data"]},"BlockedCodesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlockedCode"}}},"required":["data"]},"BlockedCode":{"type":"object","properties":{"code":{"type":"string"},"codeFormatted":{"type":"string"},"destination":{"type":"string","description":"ISO-2, or `*` for every destination."},"reason":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["code","codeFormatted","destination","reason","createdBy","createdAt"]},"BlockedCodeResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BlockedCode"}},"required":["data"]},"BlockedCodeRequest":{"type":"object","properties":{"code":{"type":"string","pattern":"^[\\d.\\s-]+$"},"destination":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z]{2}$"}],"default":"*"},"reason":{"type":"string","maxLength":300}},"required":["code"],"description":"A code your classifications must never suggest: the line, or a heading (every line under it). For one destination, or `*` for all.","example":{"code":"6109.10","destination":"US","reason":"Our broker files these under 6109.90"}},"BlockedCodesImportResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"added":{"type":"integer"},"updated":{"type":"integer","description":"Already blocked; the reason is updated when one is given."},"removed":{"type":"integer","description":"Unblocked because a replacing import left them out."},"total":{"type":"integer","description":"Blocked codes after the import."}},"required":["added","updated","removed","total"]}},"required":["data"]},"BlockedCodesImportRequest":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[\\d.\\s-]+$"},"destination":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z]{2}$"}],"default":"*"},"reason":{"type":"string","maxLength":300}},"required":["code"]},"minItems":1,"maxItems":5000},"replace":{"type":"boolean","default":false}},"required":["codes"],"description":"Codes to block in one go (up to 5,000), each for one destination or `*`. With `replace: true` the list becomes exactly these codes.","example":{"codes":[{"code":"6109.10","destination":"US","reason":"Our broker files these under 6109.90"},{"code":"9503"}],"replace":false}},"BlockedCodeRemoveResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean"}},"required":["removed"]}},"required":["data"]},"ClassifyFeedbackResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60","description":"The feedback’s id."},"replaced":{"type":"boolean","description":"Feedback on this `usageId` was already recorded and this replaced it (until it is reviewed, the latest stands)."},"kept":{"type":"boolean","description":"Feedback on this `usageId` was already reviewed, so it stands and this one was not recorded."}},"required":["id","replaced","kept"]}},"required":["data"]},"ClassifyFeedbackRequest":{"type":"object","properties":{"usageId":{"type":"string","maxLength":100},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":{"type":"string","minLength":2,"maxLength":2000},"predictedCode":{"type":"string","pattern":"^[\\d.\\s-]+$"},"verdict":{"type":"string","enum":["right","wrong"]},"correctCode":{"type":"string","pattern":"^[\\d.\\s-]+$"},"reason":{"type":"string","maxLength":1000},"mode":{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,30}$"},"productUrl":{"type":"string","maxLength":2000,"format":"uri"}},"required":["destinationCountry","description","predictedCode","verdict"],"description":"Whether a classification was right, or what it should have been. Reviewed by border.bot; corrections become test cases the classifier must pass.","example":{"usageId":"use_01J9ZK8Q7X4N2M","destinationCountry":"US","description":"Yoga mat, 6 mm, TPE","predictedCode":"3926909985","verdict":"wrong","correctCode":"9506910030","reason":"Exercise equipment, not an article of plastics"}},"CalculateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LandedCostResult"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"LandedCostResult":{"type":"object","properties":{"hsCode":{"type":"string"},"hsCodeFormatted":{"type":"string"},"originCountry":{"type":"string"},"destinationCountry":{"type":"string"},"currency":{"type":"string","description":"Currency of every amount (the destination currency)."},"exchangeRate":{"type":["number","null"]},"transportMode":{"type":["string","null"]},"shipmentChannel":{"type":["string","null"],"description":"The channel the shipment was priced for: the request’s `shipmentChannel`, or the one its `transportMode` implies (air → courier; sea, road, rail → freight)."},"shippingTerms":{"type":["string","null"]},"deMinimis":{"type":["object","null"],"properties":{"threshold":{"type":["number","null"],"description":"Duty de minimis threshold."},"exempt":{"type":"boolean"},"taxThreshold":{"type":["number","null"],"description":"Separate tax (VAT/GST) threshold, where the destination has one."},"taxExempt":{"type":"boolean"}},"required":["threshold","exempt"]},"customsValue":{"type":["number","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/LandedCostLine"}},"totals":{"type":"object","properties":{"goods":{"type":["number","null"]},"shipping":{"type":["number","null"]},"insurance":{"type":["number","null"]},"duties":{"type":"number"},"fees":{"type":"number"},"taxes":{"type":"number"},"dutiesTaxesFees":{"type":"number"},"landedCost":{"type":["number","null"]}},"required":["goods","shipping","insurance","duties","fees","taxes","dutiesTaxesFees","landedCost"]},"notes":{"type":"array","items":{"type":"string"}},"upstreamRequestId":{"type":["string","null"]},"dataSource":{"$ref":"#/components/schemas/TariffDataSource"},"engine":{"type":"string","enum":["borderbot"]},"schedule":{"type":"string","description":"Customs territory whose tariff applied: `EU` for a member state, `US` for Puerto Rico."},"region":{"type":["string","null"]},"entryDate":{"type":"string","description":"Rates, thresholds, fees and taxes as of this date."},"entryType":{"type":["string","null"],"enum":["formal","informal",null],"description":"The declaration in US terms: `formal` is a full declaration, `informal` a simplified one."},"declaration":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["full","simplified"]},"term":{"type":["string","null"]}},"required":["type","term"],"description":"The declaration the fees were charged for: `full` or `simplified`, with the destination’s own term for it (US `formal entry`). Null when the destination doesn’t split declarations by value and the request didn’t say."},"filing":{"type":"object","properties":{"method":{"type":"string","enum":["electronic","paper"]},"preparedBy":{"type":"string","enum":["declarant","authority"]}},"required":["method","preparedBy"],"description":"How the declaration was taken to be filed: the request’s `filing`, else the destination’s usual filing."},"estimated":{"type":"boolean","description":"Some figure rests on an assumption or is missing: see `notes` and `needs`."},"needs":{"type":"array","items":{"type":"string"},"description":"What would make the result exact: `weight`, `net_weight`, `volume`, `alcohol_strength`, `quantity`…"},"sources":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"]},"description":"Official sources behind the figures. Cite them alongside border.bot."},"sellerTaxes":{"type":"number","description":"Taxes a registered seller charges at checkout (already in `totals.taxes`)."},"flatDuty":{"type":["object","null"],"properties":{"rate":{"type":"string"},"amount":{"type":"number"}},"required":["rate","amount"],"description":"A flat duty charged instead of the tariff on a low-value consignment."},"validation":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"action":{"type":"string","enum":["reject","warn","relief"]},"code":{"type":["string","null"]},"message":{"type":"string"},"itemIndex":{"type":["integer","null"]}},"required":["rule","action","code","message","itemIndex"]},"description":"The destination’s validation rules this shipment matched (border.bot’s engine): `reject` (it can’t be quoted as it stands, e.g. formal entry required), `warn`, or `relief` (nothing is due, as for a bona fide gift: duties, fees and taxes are zero)."},"contentHints":{"$ref":"#/components/schemas/ContentHints"},"catalog":{"$ref":"#/components/schemas/CatalogLines"},"regulatory":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"agency":{"type":["string","null"]},"measureType":{"type":["string","null"]},"condition":{"type":["string","null"]}},"required":["code","name","description","agency","measureType","condition"]},"description":"Conditional measures that may apply (metal content, end-use claims…). They are NOT included in the totals."},"tradeAgreement":{"type":["string","null"],"description":"Trade agreement whose preferential rate was applied."},"rateFound":{"type":"boolean","description":"False when no duty rate was found for this code and origin — check the HS code."},"availableExemptions":{"type":"array","items":{"type":"string"},"description":"Exemption/claim codes the shipper may be able to file."},"options":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","enum":["general","preferential","punitive"]},"programme":{"type":["object","null"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"agreement":{"type":["string","null"]},"proof":{"type":["string","null"]}},"required":["code","name","agreement","proof"]},"rate":{"type":"string"},"amount":{"type":["number","null"]},"estimated":{"type":"boolean"},"applied":{"type":"boolean"},"condition":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["pharmaceutical","end_use","certificate","company","quality","listed_goods","reimport","route","content","quota","residual","other"]},"code":{"type":["string","null"]},"label":{"type":["string","null"]}},"required":["kind","code","label"],"description":"What the rate is reserved for (harmonised `kind`, the publisher’s `code` and wording). An option with a condition that wasn’t applied is a rate the line could claim with `conditions`."},"quota":{"type":["string","null"],"description":"A tariff quota’s order number: an in-quota rate. It is applied only when the order number is in `claims` (and the quota still has balance); otherwise it is listed, never charged."},"relief":{"type":["object","null"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"kind":{"type":["string","null"],"enum":["autonomous_suspension","preferential_suspension","end_use","airworthiness","certificate","entry_provision","preference_entry","free_preference_entry","full_value","other",null]}},"required":["code","name","kind"],"description":"The relief this option is: an autonomous suspension (applied on its own) or an end-use or airworthiness relief (claimed with its `code` in `claims`, the authorisation or certificate it names)."}},"required":["tier","programme","rate","amount","estimated","applied"]},"description":"Every duty option: the general rate, each preference the origin qualifies for (with the proof it needs), rates reserved for a condition, and which one was applied."},"claims":{"type":"object","properties":{"available":{"type":"array","items":{"$ref":"#/components/schemas/AvailableClaim"},"description":"Potential exemptions: claims that would remove a charged line."},"applied":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"application":{"type":"string","enum":["automatic","claim"],"description":"`automatic`: applied on the facts, without a claim; `claim`: applied because `claims` named it."}},"required":["code","name","application"]},"description":"Exemptions applied to the item, automatically or as claimed."}},"required":["available","applied"]},"entryCodes":{"$ref":"#/components/schemas/EntryCodes"},"entryCodeOrder":{"type":["object","null"],"properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"],"description":"The authority’s rule `entryCodes` are in filing order by (US: CBP CSMS #69668138); null when the destination has no rule loaded and the list is unordered."}},"required":["hsCode","hsCodeFormatted","originCountry","destinationCountry","currency","exchangeRate","transportMode","shippingTerms","deMinimis","customsValue","lines","totals","notes","upstreamRequestId","regulatory","tradeAgreement"]},"LandedCostLine":{"type":"object","properties":{"kind":{"type":"string","enum":["duty","fee","tax"]},"name":{"type":"string"},"type":{"type":["string","null"]},"code":{"type":["string","null"]},"rate":{"type":["string","null"]},"amount":{"type":"number"},"agreement":{"type":["string","null"]},"category":{"type":"string","description":"Fees and taxes: the harmonised kind, the same in every country. Fees: `customs_processing`, `port_harbour`, `inspection`, `statistical`, `handling_clearance`, `documentation`, `environmental`, `agricultural_promotion`, `infrastructure`, `regional_levy`, `security`, `carrier_collection`, `other`. Taxes: `vat_gst`, `sales`, `excise_alcohol`, `excise_tobacco`, `excise_fuel`, `excise_other`, `environmental`, `surcharge`, `social_contribution`, `levy`, `other`.","example":"customs_processing"},"publisher":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":["string","null"]}},"required":["code","label"],"description":"Fees and taxes: the publisher’s own code and name for it (US `MPF` “Merchandise processing fee”; Norway `MV` for VAT)."},"collectedBy":{"type":"string","enum":["border","carrier","seller"],"description":"Fees and taxes: paid at the border, collected by the carrier on delivery, or charged by a registered seller at checkout."},"estimated":{"type":"boolean","description":"The amount couldn’t be priced: a figure is missing (see `needs`)."},"exemptedBy":{"type":"string","description":"Duties: zeroed by this exemption code. The same as `exemption.code`, kept for clients written before `exemption`.","example":"9903.05.86"},"legalBasis":{"type":["string","null"],"description":"Duties: the instrument that imposes it (proclamation, notice, tariff note), when the data names it.","example":"Section 301 (failure to prohibit imports made with forced labour, 60 economies); USTR notice 91 FR 47318 (FR 2026-15181); CBP CSMS 69326983; HTSUS ch. 99 subch. III U.S. note 52"},"sourceUrl":{"type":["string","null"],"description":"Duties: the official page for it.","example":"https://www.federalregister.gov/d/2026-15181"},"exemption":{"$ref":"#/components/schemas/LineExemption"}},"required":["kind","name","type","code","rate","amount","agreement"]},"LineExemption":{"type":"object","properties":{"code":{"type":"string","description":"The exemption’s code: a filing code (US chapter 99 exemption heading, TARIC additional code) or, when the publisher gives it none, the note that provides it (`US note 33(f)`).","example":"9903.05.86"},"name":{"type":["string","null"],"example":"Products listed in U.S. note 52(b)"},"application":{"type":["string","null"],"enum":["automatic","claim",null],"description":"`automatic`: it applies on the facts (the goods, origin or another duty); `claim`: it applies because the request claimed it in `claims`."},"kind":{"type":["string","null"],"description":"What relieves the goods, harmonised (`free_preference_entry`, `preference_entry`, `certificate`, `entry_provision`…); null when the data doesn’t say."},"legalBasis":{"type":["string","null"],"description":"The provision that grants it, when the data names one.","example":"U.S. note 52(b)"},"sourceUrl":{"type":["string","null"],"example":"https://www.federalregister.gov/d/2026-15181"},"proof":{"type":["string","null"],"description":"The evidence the importer must hold for it, when known (an exemption that follows a preference needs that preference’s proof of origin).","example":null},"alternatives":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"The exemption’s code: a filing code (US chapter 99 exemption heading, TARIC additional code) or, when the publisher gives it none, the note that provides it (`US note 33(f)`).","example":"9903.05.86"},"name":{"type":["string","null"],"example":"Products listed in U.S. note 52(b)"},"application":{"type":["string","null"],"enum":["automatic","claim",null],"description":"`automatic`: it applies on the facts (the goods, origin or another duty); `claim`: it applies because the request claimed it in `claims`."},"kind":{"type":["string","null"],"description":"What relieves the goods, harmonised (`free_preference_entry`, `preference_entry`, `certificate`, `entry_provision`…); null when the data doesn’t say."},"legalBasis":{"type":["string","null"],"description":"The provision that grants it, when the data names one.","example":"U.S. note 52(b)"},"sourceUrl":{"type":["string","null"],"example":"https://www.federalregister.gov/d/2026-15181"}},"required":["code","name","application","kind","legalBasis","sourceUrl"]},"description":"Other exemptions that lift the same duty. The publisher sets no precedence between them (CBP: the importer “may enter the good under either applicable chapter 99 heading”), so any one may be relied on and reported in place of `code`. The engine applies the one the data gives precedence (US: the Section 232 exception 9903.05.90 over a note 52(b) listing, reported with the 232 heading it pairs with), else one naming the goods or the duty before one triggered by another duty.","example":[{"code":"9903.05.86","name":"Products listed in U.S. note 52(b)","application":"automatic","kind":null,"legalBasis":"U.S. note 52(b)","sourceUrl":"https://www.federalregister.gov/d/2026-15181"}]}},"required":["code","name","application","kind","legalBasis","sourceUrl","proof","alternatives"],"description":"What lifted this duty line: the exemption applied, how (automatic or claimed), its legal basis and source, the proof it needs, and any other exemption that also lifts it."},"ContentHints":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"9903.82.06"},"name":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"What to declare, as request fields.","example":["materials[steel].weightKg","materials[steel].origins.melt_pour"]},"note":{"type":"string"}},"required":["code","name","fields","note"]},"description":"Content facts that would lower the duty when declared: a measure reserved for declared content (85% U.S. metal) or charged on a content value, that the line didn’t give. Without them the full rate was charged."},"CatalogLines":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"productId":{"type":"string"},"itemId":{"type":"string"},"sku":{"type":["string","null"]},"title":{"type":"string"},"schedule":{"type":"string"},"classificationId":{"type":["string","null"],"description":"The approved code used; null when the line gave its own."},"code":{"type":"string"},"filled":{"type":"array","items":{"type":"string"},"description":"Fields filled from the catalogue."}},"required":["index","productId","itemId","sku","title","schedule","classificationId","code","filled"]},"description":"Lines that named catalogue products, as they resolved."},"AvailableClaim":{"type":"object","properties":{"code":{"type":"string","description":"The code to send in `claims`.","example":"9903.94.06"},"name":{"type":["string","null"]},"affects":{"type":"string","description":"The duty line it would remove (its name)."},"affectsCode":{"type":["string","null"],"description":"That duty line’s code; null for a relief of the base duty or a tariff quota.","example":"9903.94.05"},"kind":{"type":["string","null"],"description":"What it is, harmonised, when the data says."},"legalBasis":{"type":["string","null"],"example":"U.S. note 33(h)"},"sourceUrl":{"type":["string","null"]},"proof":{"type":["string","null"],"description":"The evidence needed to claim it, when known. Claim only what the goods qualify for."},"condition":{"type":["string","null"],"description":"What the goods must be for the claim to hold, when no codes limit it: offered on any line with this caveat (US 9903.05.92, informational materials: CBP publishes no HTS list for it). A claim made still applies.","example":null}},"required":["code","name","affects","affectsCode","kind","legalBasis","sourceUrl","proof","condition"],"description":"An exemption, relief or quota the importer could claim to remove a charged duty line: what it removes and what it needs. Not applied until it is in `claims`."},"EntryCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"9903.05.90"},"role":{"type":"string","enum":["provision","tariff","additional","exemption","claim"],"description":"`provision`: the special entry provision (US chapter 98); `tariff`: the tariff line the goods are classified in (the statistical line when the request gave one); `additional`: an additional duty’s filing code that applies (charged or at no amount); `exemption`: an exemption’s filing code reported in place of the duty it lifted on the facts; `claim`: the same, for an exemption the request claimed."},"name":{"type":["string","null"]},"type":{"type":"string","description":"The duty line’s type, as on `lines`: what a filing order sorts by.","example":"S301_FORCED_LABOUR"},"lines":{"type":"array","items":{"type":"string"},"description":"The codes of the duty lines it relates to: for an exemption, the duties it lifted; otherwise its own line.","example":["9903.05.31"]}},"required":["code","role","name","type","lines"]},"description":"The codes to report on the item’s declaration line: the tariff line, every additional duty filing code that applies, and each exemption filing code in place of the duty it lifts (US chapter 99 headings; other countries’ additional codes, such as TARIC additional codes, take the same shape). In filing order only when `entryCodeOrder` cites the rule: for the US, CBP CSMS #69326983 (https://content.govdelivery.com/accounts/USDHSCBP/bulletins/421d887) and CSMS #69668138 (https://content.govdelivery.com/bulletins/gd/USDHSCBP-4270d2a) set chapter 98, then the chapter 99 numbers for Section 301, 122/338, 232 and 201 duties, then replacement duties, then the chapter 1–97 number last, carrying the entered value; an exemption heading takes the slot of the duty it lifts. Otherwise the list is unordered.","example":[{"code":"9903.05.90","role":"exemption","name":"Goods under Section 232 aren’t subject to the forced-labour duties (U.S. note 52(f))","type":"S301_FORCED_LABOUR","lines":["9903.05.31"]},{"code":"9903.94.05","role":"additional","name":"Section 232 automobile parts (25%)","type":"S232_AUTO_PARTS","lines":["9903.94.05"]},{"code":"8471300100","role":"tariff","name":"General rate","type":"CUSTOMS_DUTY","lines":["84713001"]}]},"CalculateRequest":{"type":"object","properties":{"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Destination: one `GET /countries` marks `landedCost`. ISO 3166-1 alpha-2, case-insensitive.","example":"US"},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","default":"USD","description":"ISO 4217 currency of `value`, `shippingCost` and `insuranceCost`.","example":"USD"},"shippingCost":{"type":"number","minimum":0,"maximum":10000000,"description":"Shipping cost (affects CIF-based duty/VAT bases)."},"insuranceCost":{"type":"number","minimum":0,"maximum":10000000,"description":"Insurance cost."},"transportMode":{"type":"string","enum":["air","sea","road","rail"],"default":"air","description":"Transport mode (fees such as HMF apply to sea freight)."},"shippingTerms":{"type":"string","enum":["EXW","FCA","FAS","FOB","CFR","CIF","CPT","CIP","DAP","DPU","DDP"],"description":"Incoterm of the price (Incoterms 2020). Under C and D terms (CFR, CIF, CPT, CIP, DAP, DPU, DDP) the price already carries the goods to the destination, so `shippingCost` isn’t added to the customs value again."},"shipmentChannel":{"type":"string","enum":["courier","postal","freight"],"description":"How the goods travel and clear: `courier` (an express consignment: DHL, UPS, FedEx…), `postal` (national post) or `freight` (cargo on its own entry). Omitted: from `transportMode` — air is `courier`, sea, road and rail are `freight` (sea cargo is never an express consignment, so `courier` by sea is priced as freight). Affects de minimis and fees (US: the informal-entry MPF, 19 CFR 24.23(b)(2), is charged on freight; express consignments pay the carrier’s per-waybill fee, 24.23(b)(4)). The result’s `shipmentChannel` says which was used."},"entryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calculate with the rates in force on this date (YYYY-MM-DD). Default: today.","example":"2026-10-07"},"tradeAgreement":{"type":"string","maxLength":40,"deprecated":true,"description":"Ignored. Preferential rates are applied automatically from the origin and destination; the agreement used is returned as `tradeAgreement`."},"region":{"type":"string","pattern":"^[A-Z0-9-]{1,6}$","description":"State, province or territory, where import taxes differ inside the country. Canada needs one (`ON`, `QC`, `BC`…).","example":"ON"},"purpose":{"type":"string","enum":["sale","gift","sample","return"],"description":"Why the goods are sent: some thresholds differ for gifts, samples and returns. Default: `sale`. A `gift` is a personal gift, not something bought: a free gift with a purchase is `sale` (or set `giftInConjunctionWithPurchase`)."},"sender":{"type":"string","enum":["person","business"],"description":"Who sends the goods: a private `person` or a `business`. Gift exemptions are usually for gifts from a person (US: up to $100 per recipient per day, 19 CFR 10.152); a gift from a business qualifies only on the declaration the destination accepts, claimed in `claims` (US: `gift_statement`, the parcel clearly marked as a gift with a statement enclosed, 19 CFR 10.153(c)). Left out, a gift exemption limited to some senders is applied and the result is `estimated`."},"giftInConjunctionWithPurchase":{"type":"boolean","description":"The gift is given in conjunction with a purchase (a bonus or free article with an order). It isn’t a gift for customs (US 19 CFR 10.153(a)): gift exemptions don’t apply and the goods are treated as sold."},"businessBuyer":{"type":"boolean","description":"The buyer is a business: some taxes are reverse-charged or apply differently."},"sellerRegistrations":{"type":"array","items":{"type":"string","pattern":"^[A-Z][A-Z0-9_]{1,20}$"},"maxItems":10,"description":"Tax schemes the seller is registered for (`EU_IOSS`, `GB_VAT`, `AU_GST`, `NZ_GST`, `NO_VOEC`…). Taxes the seller collects at checkout are returned with `collectedBy: \"seller\"`.","example":["EU_IOSS"]},"preference":{"type":"string","minLength":1,"maxLength":20,"description":"`best` (default): the lowest preferential rate the origin qualifies for. `none`: the general rate only. Or a programme code (`S` for USMCA into the US). Every option is returned in `options`."},"claims":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"maxItems":20,"description":"Exemption, relief and quota codes being claimed (US Chapter 99 exclusions such as `9903.88.69`; an end-use authorisation such as TARIC document `N990`; a tariff quota order number such as `050331`). Codes you could claim are returned in `claims.available`."},"enforceValidation":{"type":"boolean","description":"Refuse a shipment that matches one of the destination’s `reject` validation rules (400 `invalid_input`, `details.reason: \"validation_failed\"`, refunded) instead of reporting it in `validation`."},"declarationType":{"type":"string","enum":["full","simplified"],"description":"The declaration the goods are entered on, when known: `full` (US formal entry) or `simplified` (US informal entry). Default: what the destination’s value rules require. A full declaration may always be chosen; a simplified one the value rules out is ignored (see `notes`). Fees differ by declaration (US MPF, the cotton assessment)."},"filing":{"type":"object","properties":{"method":{"type":"string","enum":["electronic","paper"]},"preparedBy":{"type":"string","enum":["declarant","authority"]}},"description":"How the declaration is filed, when known: `method` `electronic` or `paper`, `preparedBy` `declarant` or `authority` (a customs officer). Default: the destination’s usual filing (electronic, by the declarant). The US informal-entry MPF differs by both.","example":{"method":"electronic","preparedBy":"declarant"}},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS/HTS code (4–10 digits). With `sku` or `productId`, leave it out to use the product’s approved code for the destination.","example":"6109.10.00.12"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country of origin. With `sku` or `productId`, the catalogue’s origin is used when left out.","example":"CN"},"value":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Total customs value of the line, in `currency`. With `sku` or `productId`: the item’s unit value × `quantity` when left out (it must be in the request’s currency).","example":120},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":1000000,"default":1,"description":"Number of units."},"weight":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"description":"Shipment weight (needed for weight-based duties). Requires `weightUnit`."},"weightUnit":{"type":"string","enum":["kg","lb"],"description":"Unit of `weight`."},"volumeLiters":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Volume of the goods in litres, for duties charged per litre (wine, spirits, fuel)."},"alcoholPercent":{"type":"number","minimum":0,"maximum":100,"description":"Alcohol by volume (%), for duties charged per litre of pure alcohol."},"components":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","minLength":2,"maxLength":40},"value":{"type":"number","minimum":0,"maximum":100000000}},"required":["material","value"]},"maxItems":10,"description":"Metal content by value (line totals in `currency`), for duties charged on it: US Section 232 steel, aluminum and copper derivatives. Without it, those duties come back as `regulatory` (conditional).","example":[{"material":"steel","value":40}]},"metalWeightPercent":{"type":"number","minimum":0,"maximum":100,"description":"Share of the product’s weight that is metal (0–100), for content-based exemptions."},"materials":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"weight":{"type":"number","minimum":0,"maximum":10000000},"weightUnit":{"type":"string","enum":["kg","lb"]},"sharePercent":{"type":"number","minimum":0,"maximum":100},"value":{"type":"number","minimum":0,"maximum":100000000},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["kind","country"]},"maxItems":6}},"required":["material"]},"maxItems":20,"description":"What the goods are made of (line totals): harmonised `material` codes (`steel`, `aluminium`, `copper`, `wood`, `component`…; `GET /catalog/terms`) with their weight or share of the weight, value, and where each was produced by stage (`melt_pour`, `smelt`, `cast`, `harvest`, `production`). Measures reserved for declared content apply from them on their own (US Section 232: at least 85% of the aluminium, steel and copper by weight smelted and cast / melted and poured in the United States, Proclamation 11032), and duties charged on content read their value (the non-U.S. content of USMCA goods: the line’s value less the parts produced in the United States). Without them the full rate is charged, never less, and `contentHints` says what would lower it.","example":[{"material":"steel","weight":3,"weightUnit":"kg","value":60,"origins":[{"kind":"melt_pour","country":"US"}]}]},"conditions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,19}$"},"maxItems":10,"description":"Rate conditions the goods meet, when the destination reserves a rate for them: a harmonised kind (`pharmaceutical`, `end_use`, `certificate`, `company`, `quality`, `route`) or the publisher’s own code (EU TARIC additional code `2500`). Without it the default rate is charged (the unconditional one, or the highest when every rate has a condition); the rates you could claim are returned in `options` with their `condition`. The importer must hold what justifies a claimed condition.","example":["pharmaceutical"]},"declaredPrice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":100000000},"per":{"type":"string","minLength":1,"maxLength":40}},"required":["amount","per"],"description":"The price of the goods per unit, in `currency` (`per`: `100 kg`, `t`, `hl`, `kg`…), for duties set by the price: the EU’s entry prices for fruit and vegetables and minimum import prices (TARIC price conditions). Without it the price is the line’s value over its weight or volume; when that isn’t known either, the highest duty the condition can charge is used and `needs` lists `price`.","example":{"amount":85,"per":"100 kg"}},"salePrice":{"type":"number","minimum":0,"maximum":100000000,"description":"The price the importer (or domestic seller) sells the line for, line total in `currency`, for taxes charged on the sale price rather than the customs value (US large cigars, 27 CFR 41.39). Without it the customs value stands in, the result is `estimated` and `needs` lists `sale_price`.","example":260},"entryProvision":{"type":"object","properties":{"kind":{"type":"string","enum":["repair_abroad","processing_abroad","assembled_abroad","agreement_provision","returned","other"]},"code":{"type":"string","pattern":"^[\\d.]{4,14}$"},"dutiableValue":{"type":"number","minimum":0,"maximum":100000000}},"required":["kind"],"description":"The special provision the line is entered under, when not its classification alone (US chapter 98): `kind` is `repair_abroad` (9802.00.40/.50), `processing_abroad` (9802.00.60), `assembled_abroad` (9802.00.80), `agreement_provision` (USMCA subchapter XXIII), `returned` (9801.00.10) or `other`, with the provision’s `code`. Duties the provision is outside of are left out (US Section 301, 338, forced-labour, Brazil, Nicaragua and Russia duties, except for 9802 repairs, processing and assembly); repairs and processing pay on `dutiableValue` (the value of the repairs or processing, line total in `currency`), assembly abroad on the value less the U.S. components (`dutiableValue`, or worked out from `materials`). Section 232 stays charged, on the full value under 9802.00.60.","example":{"kind":"repair_abroad","code":"9802.00.50","dutiableValue":120}},"sku":{"type":"string","minLength":1,"maxLength":120,"description":"A SKU in your catalogue: its approved code for the destination, origin, value, weight and content components are used (what the line gives wins). A product without an approved code for the destination is refused without charging (`invalid_input`, `details.reason: \"missing_classification\"`).","example":"BOTTLE-750"},"productId":{"type":"string","format":"uuid","description":"A catalogue product’s id (its first active item), instead of `sku`."}},"required":["destinationCountry"],"example":{"hsCode":"6109.10.00.12","originCountry":"CN","destinationCountry":"US","value":120,"currency":"USD","shippingCost":15}},"CalculateShipmentResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShipmentLandedCost"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"ShipmentLandedCost":{"type":"object","properties":{"destinationCountry":{"type":"string"},"currency":{"type":"string","description":"Currency of every amount (the destination currency)."},"exchangeRate":{"type":["number","null"]},"transportMode":{"type":["string","null"]},"shipmentChannel":{"type":["string","null"],"description":"The channel the shipment was priced for: the request’s `shipmentChannel`, or the one its `transportMode` implies (air → courier; sea, road, rail → freight)."},"shippingTerms":{"type":["string","null"]},"deMinimis":{"type":["object","null"],"properties":{"threshold":{"type":["number","null"],"description":"Duty de minimis threshold."},"exempt":{"type":"boolean"},"taxThreshold":{"type":["number","null"],"description":"Separate tax (VAT/GST) threshold, where the destination has one."},"taxExempt":{"type":"boolean"}},"required":["threshold","exempt"]},"customsValue":{"type":["number","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/LandedCostLine"}},"totals":{"type":"object","properties":{"goods":{"type":["number","null"]},"shipping":{"type":["number","null"]},"insurance":{"type":["number","null"]},"duties":{"type":"number"},"fees":{"type":"number"},"taxes":{"type":"number"},"dutiesTaxesFees":{"type":"number"},"landedCost":{"type":["number","null"]}},"required":["goods","shipping","insurance","duties","fees","taxes","dutiesTaxesFees","landedCost"]},"notes":{"type":"array","items":{"type":"string"}},"upstreamRequestId":{"type":["string","null"]},"dataSource":{"$ref":"#/components/schemas/TariffDataSource"},"engine":{"type":"string","enum":["borderbot"]},"schedule":{"type":"string","description":"Customs territory whose tariff applied: `EU` for a member state, `US` for Puerto Rico."},"region":{"type":["string","null"]},"entryDate":{"type":"string","description":"Rates, thresholds, fees and taxes as of this date."},"entryType":{"type":["string","null"],"enum":["formal","informal",null],"description":"The declaration in US terms: `formal` is a full declaration, `informal` a simplified one."},"declaration":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["full","simplified"]},"term":{"type":["string","null"]}},"required":["type","term"],"description":"The declaration the fees were charged for: `full` or `simplified`, with the destination’s own term for it (US `formal entry`). Null when the destination doesn’t split declarations by value and the request didn’t say."},"filing":{"type":"object","properties":{"method":{"type":"string","enum":["electronic","paper"]},"preparedBy":{"type":"string","enum":["declarant","authority"]}},"required":["method","preparedBy"],"description":"How the declaration was taken to be filed: the request’s `filing`, else the destination’s usual filing."},"estimated":{"type":"boolean","description":"Some figure rests on an assumption or is missing: see `notes` and `needs`."},"needs":{"type":"array","items":{"type":"string"},"description":"What would make the result exact: `weight`, `net_weight`, `volume`, `alcohol_strength`, `quantity`…"},"sources":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"]},"description":"Official sources behind the figures. Cite them alongside border.bot."},"sellerTaxes":{"type":"number","description":"Taxes a registered seller charges at checkout (already in `totals.taxes`)."},"flatDuty":{"type":["object","null"],"properties":{"rate":{"type":"string"},"amount":{"type":"number"}},"required":["rate","amount"],"description":"A flat duty charged instead of the tariff on a low-value consignment."},"validation":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"action":{"type":"string","enum":["reject","warn","relief"]},"code":{"type":["string","null"]},"message":{"type":"string"},"itemIndex":{"type":["integer","null"]}},"required":["rule","action","code","message","itemIndex"]},"description":"The destination’s validation rules this shipment matched (border.bot’s engine): `reject` (it can’t be quoted as it stands, e.g. formal entry required), `warn`, or `relief` (nothing is due, as for a bona fide gift: duties, fees and taxes are zero)."},"catalog":{"$ref":"#/components/schemas/CatalogLines"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentLine"}}},"required":["destinationCountry","currency","exchangeRate","transportMode","shippingTerms","deMinimis","customsValue","lines","totals","notes","upstreamRequestId","items"],"description":"A whole shipment: each line’s duties (`items`), the fees and taxes charged once for the shipment, and its totals. `lines` lists every duty, fee and tax."},"ShipmentLine":{"type":"object","properties":{"index":{"type":"integer","description":"The line’s position in the request."},"hsCode":{"type":"string"},"hsCodeFormatted":{"type":"string"},"originCountry":{"type":"string"},"customsValue":{"type":"number","description":"The line’s value, plus its share of the freight where that is added."},"duty":{"type":["number","null"],"description":"The line’s duty; null when a rate or a figure it needs is missing."},"rateFound":{"type":"boolean","description":"False when no duty rate was found for this code and origin — check the HS code."},"tradeAgreement":{"type":["string","null"],"description":"Trade agreement whose preferential rate was applied."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/LandedCostLine"},"description":"The line’s duties."},"regulatory":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"agency":{"type":["string","null"]},"measureType":{"type":["string","null"]},"condition":{"type":["string","null"]}},"required":["code","name","description","agency","measureType","condition"]},"description":"Conditional measures that may apply (metal content, end-use claims…). They are NOT included in the totals."},"options":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","enum":["general","preferential","punitive"]},"programme":{"type":["object","null"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"agreement":{"type":["string","null"]},"proof":{"type":["string","null"]}},"required":["code","name","agreement","proof"]},"rate":{"type":"string"},"amount":{"type":["number","null"]},"estimated":{"type":"boolean"},"applied":{"type":"boolean"},"condition":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["pharmaceutical","end_use","certificate","company","quality","listed_goods","reimport","route","content","quota","residual","other"]},"code":{"type":["string","null"]},"label":{"type":["string","null"]}},"required":["kind","code","label"],"description":"What the rate is reserved for (harmonised `kind`, the publisher’s `code` and wording). An option with a condition that wasn’t applied is a rate the line could claim with `conditions`."},"quota":{"type":["string","null"],"description":"A tariff quota’s order number: an in-quota rate. It is applied only when the order number is in `claims` (and the quota still has balance); otherwise it is listed, never charged."},"relief":{"type":["object","null"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"kind":{"type":["string","null"],"enum":["autonomous_suspension","preferential_suspension","end_use","airworthiness","certificate","entry_provision","preference_entry","free_preference_entry","full_value","other",null]}},"required":["code","name","kind"],"description":"The relief this option is: an autonomous suspension (applied on its own) or an end-use or airworthiness relief (claimed with its `code` in `claims`, the authorisation or certificate it names)."}},"required":["tier","programme","rate","amount","estimated","applied"]},"description":"Every duty option: the general rate, each preference the origin qualifies for (with the proof it needs), rates reserved for a condition, and which one was applied."},"claims":{"type":"object","properties":{"available":{"type":"array","items":{"$ref":"#/components/schemas/AvailableClaim"},"description":"Potential exemptions: claims that would remove a charged line."},"applied":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"application":{"type":"string","enum":["automatic","claim"],"description":"`automatic`: applied on the facts, without a claim; `claim`: applied because `claims` named it."}},"required":["code","name","application"]},"description":"Exemptions applied to the item, automatically or as claimed."}},"required":["available","applied"]},"availableExemptions":{"type":"array","items":{"type":"string"},"description":"Exemption/claim codes the shipper may be able to file."},"contentHints":{"$ref":"#/components/schemas/ContentHints"},"entryCodes":{"$ref":"#/components/schemas/EntryCodes"},"entryCodeOrder":{"type":["object","null"],"properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"],"description":"The authority’s rule `entryCodes` are in filing order by (US: CBP CSMS #69668138); null when the destination has no rule loaded and the list is unordered."}},"required":["index","hsCode","hsCodeFormatted","originCountry","customsValue","duty","rateFound","tradeAgreement","lines","regulatory","options","claims","availableExemptions","entryCodes","entryCodeOrder"]},"CalculateShipmentRequest":{"type":"object","properties":{"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Destination: one `GET /countries` marks `landedCost`. ISO 3166-1 alpha-2, case-insensitive.","example":"US"},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","default":"USD","description":"ISO 4217 currency of `value`, `shippingCost` and `insuranceCost`.","example":"USD"},"shippingCost":{"type":"number","minimum":0,"maximum":10000000,"description":"Shipping cost (affects CIF-based duty/VAT bases)."},"insuranceCost":{"type":"number","minimum":0,"maximum":10000000,"description":"Insurance cost."},"transportMode":{"type":"string","enum":["air","sea","road","rail"],"default":"air","description":"Transport mode (fees such as HMF apply to sea freight)."},"shippingTerms":{"type":"string","enum":["EXW","FCA","FAS","FOB","CFR","CIF","CPT","CIP","DAP","DPU","DDP"],"description":"Incoterm of the price (Incoterms 2020). Under C and D terms (CFR, CIF, CPT, CIP, DAP, DPU, DDP) the price already carries the goods to the destination, so `shippingCost` isn’t added to the customs value again."},"shipmentChannel":{"type":"string","enum":["courier","postal","freight"],"description":"How the goods travel and clear: `courier` (an express consignment: DHL, UPS, FedEx…), `postal` (national post) or `freight` (cargo on its own entry). Omitted: from `transportMode` — air is `courier`, sea, road and rail are `freight` (sea cargo is never an express consignment, so `courier` by sea is priced as freight). Affects de minimis and fees (US: the informal-entry MPF, 19 CFR 24.23(b)(2), is charged on freight; express consignments pay the carrier’s per-waybill fee, 24.23(b)(4)). The result’s `shipmentChannel` says which was used."},"entryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calculate with the rates in force on this date (YYYY-MM-DD). Default: today.","example":"2026-10-07"},"tradeAgreement":{"type":"string","maxLength":40,"deprecated":true,"description":"Ignored. Preferential rates are applied automatically from the origin and destination; the agreement used is returned as `tradeAgreement`."},"region":{"type":"string","pattern":"^[A-Z0-9-]{1,6}$","description":"State, province or territory, where import taxes differ inside the country. Canada needs one (`ON`, `QC`, `BC`…).","example":"ON"},"purpose":{"type":"string","enum":["sale","gift","sample","return"],"description":"Why the goods are sent: some thresholds differ for gifts, samples and returns. Default: `sale`. A `gift` is a personal gift, not something bought: a free gift with a purchase is `sale` (or set `giftInConjunctionWithPurchase`)."},"sender":{"type":"string","enum":["person","business"],"description":"Who sends the goods: a private `person` or a `business`. Gift exemptions are usually for gifts from a person (US: up to $100 per recipient per day, 19 CFR 10.152); a gift from a business qualifies only on the declaration the destination accepts, claimed in `claims` (US: `gift_statement`, the parcel clearly marked as a gift with a statement enclosed, 19 CFR 10.153(c)). Left out, a gift exemption limited to some senders is applied and the result is `estimated`."},"giftInConjunctionWithPurchase":{"type":"boolean","description":"The gift is given in conjunction with a purchase (a bonus or free article with an order). It isn’t a gift for customs (US 19 CFR 10.153(a)): gift exemptions don’t apply and the goods are treated as sold."},"businessBuyer":{"type":"boolean","description":"The buyer is a business: some taxes are reverse-charged or apply differently."},"sellerRegistrations":{"type":"array","items":{"type":"string","pattern":"^[A-Z][A-Z0-9_]{1,20}$"},"maxItems":10,"description":"Tax schemes the seller is registered for (`EU_IOSS`, `GB_VAT`, `AU_GST`, `NZ_GST`, `NO_VOEC`…). Taxes the seller collects at checkout are returned with `collectedBy: \"seller\"`.","example":["EU_IOSS"]},"preference":{"type":"string","minLength":1,"maxLength":20,"description":"`best` (default): the lowest preferential rate the origin qualifies for. `none`: the general rate only. Or a programme code (`S` for USMCA into the US). Every option is returned in `options`."},"claims":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"maxItems":20,"description":"Exemption, relief and quota codes being claimed (US Chapter 99 exclusions such as `9903.88.69`; an end-use authorisation such as TARIC document `N990`; a tariff quota order number such as `050331`). Codes you could claim are returned in `claims.available`."},"enforceValidation":{"type":"boolean","description":"Refuse a shipment that matches one of the destination’s `reject` validation rules (400 `invalid_input`, `details.reason: \"validation_failed\"`, refunded) instead of reporting it in `validation`."},"declarationType":{"type":"string","enum":["full","simplified"],"description":"The declaration the goods are entered on, when known: `full` (US formal entry) or `simplified` (US informal entry). Default: what the destination’s value rules require. A full declaration may always be chosen; a simplified one the value rules out is ignored (see `notes`). Fees differ by declaration (US MPF, the cotton assessment)."},"filing":{"type":"object","properties":{"method":{"type":"string","enum":["electronic","paper"]},"preparedBy":{"type":"string","enum":["declarant","authority"]}},"description":"How the declaration is filed, when known: `method` `electronic` or `paper`, `preparedBy` `declarant` or `authority` (a customs officer). Default: the destination’s usual filing (electronic, by the declarant). The US informal-entry MPF differs by both.","example":{"method":"electronic","preparedBy":"declarant"}},"items":{"type":"array","items":{"type":"object","properties":{"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS/HTS code (4–10 digits). With `sku` or `productId`, leave it out to use the product’s approved code for the destination.","example":"6109.10.00.12"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country of origin. With `sku` or `productId`, the catalogue’s origin is used when left out.","example":"CN"},"value":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Total customs value of the line, in `currency`. With `sku` or `productId`: the item’s unit value × `quantity` when left out (it must be in the request’s currency).","example":120},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":1000000,"default":1,"description":"Number of units."},"weight":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"description":"Shipment weight (needed for weight-based duties). Requires `weightUnit`."},"weightUnit":{"type":"string","enum":["kg","lb"],"description":"Unit of `weight`."},"volumeLiters":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Volume of the goods in litres, for duties charged per litre (wine, spirits, fuel)."},"alcoholPercent":{"type":"number","minimum":0,"maximum":100,"description":"Alcohol by volume (%), for duties charged per litre of pure alcohol."},"components":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","minLength":2,"maxLength":40},"value":{"type":"number","minimum":0,"maximum":100000000}},"required":["material","value"]},"maxItems":10,"description":"Metal content by value (line totals in `currency`), for duties charged on it: US Section 232 steel, aluminum and copper derivatives. Without it, those duties come back as `regulatory` (conditional).","example":[{"material":"steel","value":40}]},"metalWeightPercent":{"type":"number","minimum":0,"maximum":100,"description":"Share of the product’s weight that is metal (0–100), for content-based exemptions."},"materials":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"weight":{"type":"number","minimum":0,"maximum":10000000},"weightUnit":{"type":"string","enum":["kg","lb"]},"sharePercent":{"type":"number","minimum":0,"maximum":100},"value":{"type":"number","minimum":0,"maximum":100000000},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["kind","country"]},"maxItems":6}},"required":["material"]},"maxItems":20,"description":"What the goods are made of (line totals): harmonised `material` codes (`steel`, `aluminium`, `copper`, `wood`, `component`…; `GET /catalog/terms`) with their weight or share of the weight, value, and where each was produced by stage (`melt_pour`, `smelt`, `cast`, `harvest`, `production`). Measures reserved for declared content apply from them on their own (US Section 232: at least 85% of the aluminium, steel and copper by weight smelted and cast / melted and poured in the United States, Proclamation 11032), and duties charged on content read their value (the non-U.S. content of USMCA goods: the line’s value less the parts produced in the United States). Without them the full rate is charged, never less, and `contentHints` says what would lower it.","example":[{"material":"steel","weight":3,"weightUnit":"kg","value":60,"origins":[{"kind":"melt_pour","country":"US"}]}]},"conditions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,19}$"},"maxItems":10,"description":"Rate conditions the goods meet, when the destination reserves a rate for them: a harmonised kind (`pharmaceutical`, `end_use`, `certificate`, `company`, `quality`, `route`) or the publisher’s own code (EU TARIC additional code `2500`). Without it the default rate is charged (the unconditional one, or the highest when every rate has a condition); the rates you could claim are returned in `options` with their `condition`. The importer must hold what justifies a claimed condition.","example":["pharmaceutical"]},"declaredPrice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":100000000},"per":{"type":"string","minLength":1,"maxLength":40}},"required":["amount","per"],"description":"The price of the goods per unit, in `currency` (`per`: `100 kg`, `t`, `hl`, `kg`…), for duties set by the price: the EU’s entry prices for fruit and vegetables and minimum import prices (TARIC price conditions). Without it the price is the line’s value over its weight or volume; when that isn’t known either, the highest duty the condition can charge is used and `needs` lists `price`.","example":{"amount":85,"per":"100 kg"}},"salePrice":{"type":"number","minimum":0,"maximum":100000000,"description":"The price the importer (or domestic seller) sells the line for, line total in `currency`, for taxes charged on the sale price rather than the customs value (US large cigars, 27 CFR 41.39). Without it the customs value stands in, the result is `estimated` and `needs` lists `sale_price`.","example":260},"entryProvision":{"type":"object","properties":{"kind":{"type":"string","enum":["repair_abroad","processing_abroad","assembled_abroad","agreement_provision","returned","other"]},"code":{"type":"string","pattern":"^[\\d.]{4,14}$"},"dutiableValue":{"type":"number","minimum":0,"maximum":100000000}},"required":["kind"],"description":"The special provision the line is entered under, when not its classification alone (US chapter 98): `kind` is `repair_abroad` (9802.00.40/.50), `processing_abroad` (9802.00.60), `assembled_abroad` (9802.00.80), `agreement_provision` (USMCA subchapter XXIII), `returned` (9801.00.10) or `other`, with the provision’s `code`. Duties the provision is outside of are left out (US Section 301, 338, forced-labour, Brazil, Nicaragua and Russia duties, except for 9802 repairs, processing and assembly); repairs and processing pay on `dutiableValue` (the value of the repairs or processing, line total in `currency`), assembly abroad on the value less the U.S. components (`dutiableValue`, or worked out from `materials`). Section 232 stays charged, on the full value under 9802.00.60.","example":{"kind":"repair_abroad","code":"9802.00.50","dutiableValue":120}},"sku":{"type":"string","minLength":1,"maxLength":120,"description":"A SKU in your catalogue: its approved code for the destination, origin, value, weight and content components are used (what the line gives wins). A product without an approved code for the destination is refused without charging (`invalid_input`, `details.reason: \"missing_classification\"`).","example":"BOTTLE-750"},"productId":{"type":"string","format":"uuid","description":"A catalogue product’s id (its first active item), instead of `sku`."}}},"minItems":1,"maxItems":50,"description":"The shipment’s lines (up to 50), each with its code, origin and line value, or a catalogue `sku` (or `productId`) and `quantity`. Freight and insurance are shared out by value."}},"required":["destinationCountry","items"],"example":{"destinationCountry":"GB","currency":"USD","shippingCost":12,"items":[{"hsCode":"6109.10","originCountry":"CN","value":60,"quantity":3},{"hsCode":"6204.62","originCountry":"BD","value":45}]}},"StackingResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StackingResult"}}},"required":["results"]},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"StackingResult":{"type":"object","properties":{"index":{"type":"integer"},"ref":{"type":["string","null"]},"hsCode":{"type":"string"},"hsCodeFormatted":{"type":"string"},"originCountry":{"type":"string"},"destinationCountry":{"type":"string"},"schedule":{"type":"string"},"entryDate":{"type":"string"},"rateFound":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["base","additional"]},"type":{"type":"string","description":"`general`, `preferential`, `section_301`, `section_232`, `reciprocal`…"},"name":{"type":"string"},"code":{"type":"string","description":"The tariff line or filing code (HTS Chapter 99)."},"rate":{"type":"string"},"exemptedBy":{"type":["string","null"],"description":"The exemption code that removes this line (`exemption.code`)."},"exemption":{"allOf":[{"$ref":"#/components/schemas/LineExemption"},{"type":["object","null"]}]},"legalBasis":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]}},"required":["kind","type","name","code","rate","exemptedBy","exemption","legalBasis","sourceUrl"]}},"conditional":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"rate":{"type":"string"},"condition":{"type":"string"}},"required":["name","code","rate","condition"]},"description":"Measures that need facts a stack doesn’t carry (metal content, a claim)."},"claimable":{"type":"array","items":{"$ref":"#/components/schemas/AvailableClaim"},"description":"Claim codes the importer could file to remove a line."},"entryCodes":{"allOf":[{"$ref":"#/components/schemas/EntryCodes"},{"description":"The codes the declaration line reports (types as on `lines`: `section_301`…)."}]},"entryCodeOrder":{"type":["object","null"],"properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"],"description":"The authority’s rule `entryCodes` are in filing order by (US: CBP CSMS #69668138); null when the destination has no rule loaded and the list is unordered."},"notes":{"type":"array","items":{"type":"string"}}},"required":["index","ref","hsCode","hsCodeFormatted","originCountry","destinationCountry","schedule","entryDate","rateFound","lines","conditional","claimable","entryCodes","entryCodeOrder","notes"]},"StackingRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS/HTS code (4–10 digits).","example":"8479.89.94"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country of origin. ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Destination. ISO 3166-1 alpha-2, case-insensitive.","example":"US"},"entryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Rates in force on this date (YYYY-MM-DD). Default: today."},"ref":{"type":"string","maxLength":100,"description":"Your reference for the line, echoed back."}},"required":["hsCode","originCountry","destinationCountry"]},"minItems":1,"maxItems":100}},"required":["items"],"example":{"items":[{"hsCode":"8479.89.94","originCountry":"CN","destinationCountry":"US"}]}},"ExtractProductResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductExtraction"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"ExtractProductRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Product page URL (http/https).","example":"https://shop.example.com/products/organic-tee"}},"required":["url"]},"InferOriginResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OriginInference"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"InferOriginRequest":{"type":"object","properties":{"productUrl":{"type":"string","maxLength":2048,"description":"Product page URL: its structured data and “Made in …” text are read first."},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}],"description":"Product photo (JPEG, PNG, WebP or GIF, up to 6 MB), as an http(s) URL or a base64 data URL: a visible “Made in …” label is strong evidence."},"description":{"type":"string","maxLength":2000,"description":"Product description."},"title":{"type":"string","maxLength":300,"description":"Product name."},"brand":{"type":"string","maxLength":120,"description":"Brand."},"sku":{"type":"string","maxLength":120,"description":"Your SKU (kept with the result)."},"gtin":{"type":"string","pattern":"^\\d{8,14}$","description":"Barcode (GTIN, UPC, EAN). Its GS1 prefix shows where the brand registered: a weak hint, never proof.","example":"0036000291452"},"material":{"type":"string","maxLength":300,"description":"Main materials."},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"description":"Category path, broadest first."},"price":{"type":"number","minimum":0,"maximum":10000000,"description":"Selling price, in `currency`."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 currency of `price`."},"shipFromCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country the goods ship from (often, not always, where they are made). ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"reviewThreshold":{"type":"number","minimum":0,"maximum":1,"description":"When `needsReview` is set (0–1). Inferring: an answer below this probability. Validating: a declaration whose `probabilityOfMisrepresentation` is at or above it. Without it, the workspace’s setting (dashboard → Settings → Origin review) applies, then the platform default (0.8 to infer, 0.3 to validate).","example":0.9}},"example":{"title":"Organic cotton tee","brand":"Example","productUrl":"https://shop.example.com/products/organic-tee"}},"ValidateOriginResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OriginValidation"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"OriginValidation":{"type":"object","properties":{"declared":{"type":"string"},"verdict":{"type":"string","enum":["consistent","plausible","questionable","unlikely","unknown"],"description":"`consistent`: the evidence agrees. `unlikely`: most of it points elsewhere. `unknown`: nothing says where it was made."},"probabilityOfMisrepresentation":{"type":["number","null"],"description":"Share of the evidence that points to another country (0–1); null with no evidence either way."},"probability":{"type":["number","null"],"description":"Probability of the declared country itself."},"likelyOrigin":{"type":["string","null"]},"alternates":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"probability":{"type":"number"}},"required":["country","probability"]}},"reasons":{"type":"array","items":{"type":"string"},"description":"What supports or contradicts the declaration, in words."},"signals":{"type":"array","items":{"$ref":"#/components/schemas/OriginSignal"}},"needsReview":{"type":"boolean","description":"Flag it for a person: `probabilityOfMisrepresentation` is at or above `reviewThreshold`, or there is no evidence either way."},"reviewReason":{"type":["string","null"],"description":"Why it is flagged, in words; null when it isn’t."},"reviewThreshold":{"type":"number","description":"The threshold applied: the request’s `reviewThreshold`, else the workspace’s setting, else the platform default."}},"required":["declared","verdict","probabilityOfMisrepresentation","probability","likelyOrigin","alternates","reasons","signals"]},"ValidateOriginRequest":{"type":"object","properties":{"productUrl":{"type":"string","maxLength":2048,"description":"Product page URL: its structured data and “Made in …” text are read first."},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}],"description":"Product photo (JPEG, PNG, WebP or GIF, up to 6 MB), as an http(s) URL or a base64 data URL: a visible “Made in …” label is strong evidence."},"description":{"type":"string","maxLength":2000,"description":"Product description."},"title":{"type":"string","maxLength":300,"description":"Product name."},"brand":{"type":"string","maxLength":120,"description":"Brand."},"sku":{"type":"string","maxLength":120,"description":"Your SKU (kept with the result)."},"gtin":{"type":"string","pattern":"^\\d{8,14}$","description":"Barcode (GTIN, UPC, EAN). Its GS1 prefix shows where the brand registered: a weak hint, never proof.","example":"0036000291452"},"material":{"type":"string","maxLength":300,"description":"Main materials."},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"description":"Category path, broadest first."},"price":{"type":"number","minimum":0,"maximum":10000000,"description":"Selling price, in `currency`."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 currency of `price`."},"shipFromCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country the goods ship from (often, not always, where they are made). ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"reviewThreshold":{"type":"number","minimum":0,"maximum":1,"description":"When `needsReview` is set (0–1). Inferring: an answer below this probability. Validating: a declaration whose `probabilityOfMisrepresentation` is at or above it. Without it, the workspace’s setting (dashboard → Settings → Origin review) applies, then the platform default (0.8 to infer, 0.3 to validate).","example":0.9},"declaredOrigin":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"The country of origin declared (by a supplier, a listing, a customs entry). ISO 3166-1 alpha-2, case-insensitive.","example":"US"}},"required":["declaredOrigin"],"example":{"declaredOrigin":"US","title":"Wireless earbuds","description":"Bluetooth 5.3. Made in China."}},"OriginBatchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"inference":{"$ref":"#/components/schemas/OriginInference"},"validation":{"$ref":"#/components/schemas/OriginValidation"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","ok"]}}},"required":["results"]},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"remaining":{"type":["integer","null"]}},"required":["charged","remaining"]}},"required":["data","credits"]},"OriginBatchRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"productUrl":{"type":"string","maxLength":2048},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}]},"description":{"type":"string","maxLength":2000},"title":{"type":"string","maxLength":300},"brand":{"type":"string","maxLength":120},"sku":{"type":"string","maxLength":120},"gtin":{"type":"string","pattern":"^\\d{8,14}$"},"material":{"type":"string","maxLength":300},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10},"price":{"type":"number","minimum":0,"maximum":10000000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"shipFromCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"reviewThreshold":{"type":"number","minimum":0,"maximum":1},"declaredOrigin":{"type":"string","pattern":"^[A-Za-z]{2}$"}}},"minItems":1,"maxItems":50},"reviewThreshold":{"type":"number","minimum":0,"maximum":1,"description":"The review threshold for every item that doesn’t set its own `reviewThreshold` (see `POST /v1/origin`)."}},"required":["items"],"description":"Up to 50 products. Each is inferred, or validated when it has `declaredOrigin`. Each is charged as one origin call; one failing never stops the others.","example":{"items":[{"title":"Organic cotton tee","brand":"Example"},{"title":"Wireless earbuds","declaredOrigin":"US","gtin":"6901234567892"}]}},"RestrictionsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestrictionCheckResult"}},"required":["data"]},"RestrictionCheckResult":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":["string","null"]},"title":{"type":["string","null"]},"hsCode":{"type":["string","null"]},"restrictions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","description":"`platform` rule, or `org` for a custom rule."},"hsCode":{"type":["string","null"],"description":"The rule’s HS prefix (null for keyword/origin rules)."},"imposingCountry":{"type":["string","null"]},"direction":{"type":["string","null"],"description":"`IMPORT` or `EXPORT`."},"ruleType":{"type":"string","description":"`prohibition`, `restriction` or `observation`."},"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"agency":{"type":["string","null"],"description":"Regulating agency, e.g. FDA."},"requirement":{"type":["string","null"],"description":"`required`, `may_be_required` or null."},"sourceUrl":{"type":["string","null"]},"confidence":{"type":["string","null"],"description":"`HIGH` or `MEDIUM`."},"probability":{"type":["number","null"],"description":"For a match by keywords alone: how likely (0–1) the item really falls under the rule, from a model check. Matches below 0.1 are left out. Null for HS-code and origin matches, and when the check didn’t run."}},"required":["id","source","hsCode","imposingCountry","direction","ruleType","title","summary","agency","requirement","sourceUrl","confidence"]},"description":"Matches for this item (empty when clean)."}},"required":["sku","title","hsCode","restrictions"]}},"matchCount":{"type":"integer"},"hasProhibitions":{"type":"boolean"},"hasRestrictions":{"type":"boolean"},"engine":{"type":"string","enum":["borderbot"],"description":"The engine that answered."},"upstreamRequestId":{"type":["string","null"]},"checkId":{"type":["string","null"],"format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60","description":"The check’s id: the evidence that these goods were checked (`GET /restrictions/checks`)."}},"required":["items","matchCount","hasProhibitions","hasRestrictions","upstreamRequestId","checkId"]},"RestrictionsRequest":{"type":"object","properties":{"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Ship-to country — its import rules are checked. ISO 3166-1 alpha-2, case-insensitive.","example":"US"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Ship-from country — its export rules are checked when given. ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"items":{"type":"array","items":{"$ref":"#/components/schemas/RestrictionItem"},"minItems":1,"maxItems":100,"description":"1–100 items."},"reference":{"type":"string","maxLength":200,"description":"Your reference (an order or customer id), kept with the check as evidence.","example":"order-10442"}},"required":["destinationCountry","items"],"example":{"destinationCountry":"US","originCountry":"CN","items":[{"sku":"LAMP-01","title":"Lithium battery desk lamp","hsCode":"9405.21"}]}},"RestrictionItem":{"type":"object","properties":{"sku":{"type":"string","minLength":1,"maxLength":100,"description":"Your line reference (echoed back).","example":"TEE-ORG-M"},"title":{"type":"string","minLength":1,"maxLength":500,"example":"Organic cotton t-shirt"},"description":{"type":"string","minLength":1,"maxLength":2000,"description":"What the item is (keyword rules match text)."},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS code (4–10 digits) — needed for HS-prefix rules.","example":"6109.10"},"countryOfOrigin":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Where the item was made — drives origin-based rules (e.g. sanctions). ISO 3166-1 alpha-2, case-insensitive.","example":"PT"},"materials":{"type":"string","minLength":1,"maxLength":500,"example":"100% cotton"},"category":{"type":"string","minLength":1,"maxLength":200,"example":"Apparel"},"brand":{"type":"string","minLength":1,"maxLength":200,"example":"Acme"}},"description":"One item. Every field is optional, but give an HS code or some text."},"RestrictionChecksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"actor":{"type":["string","null"]},"source":{"type":"string","description":"`api`, `mcp` or `dashboard`."},"reference":{"type":["string","null"]},"destination":{"type":"string"},"origin":{"type":["string","null"]},"itemCount":{"type":"integer"},"matchCount":{"type":"integer"},"hasProhibitions":{"type":"boolean"},"hasRestrictions":{"type":"boolean"},"engine":{"type":["string","null"]},"result":{"type":["object","null"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"sku":{"type":["string","null"]},"title":{"type":["string","null"]},"hsCode":{"type":["string","null"]},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"ruleType":{"type":"string"},"title":{"type":["string","null"]},"imposingCountry":{"type":["string","null"]},"direction":{"type":["string","null"]},"agency":{"type":["string","null"]}},"required":["id","source","ruleType","title","imposingCountry","direction","agency"]}}},"required":["index","sku","title","hsCode","matches"]}}},"required":["items"],"description":"What the check kept: each item and the rules it matched."},"createdAt":{"type":"string"}},"required":["id","actor","source","reference","destination","origin","itemCount","matchCount","hasProhibitions","hasRestrictions","engine","result","createdAt"]}}},"required":["data"]},"RestrictionRulesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RestrictionRule"}}},"required":["data"]},"RestrictionRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"country":{"type":"string","description":"The imposing country, or `*` for every one."},"direction":{"type":"string"},"ruleType":{"type":"string"},"code":{"type":"string"},"keywords":{"type":["array","null"],"items":{"type":"string"}},"origins":{"type":["array","null"],"items":{"type":"string"}},"title":{"type":"string"},"summary":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","country","direction","ruleType","code","keywords","origins","title","summary","createdAt"]},"RestrictionRuleResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestrictionRule"}},"required":["data"]},"RestrictionRuleRequest":{"type":"object","properties":{"country":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z]{2}$"}],"default":"*"},"direction":{"type":"string","enum":["import","export"],"default":"import"},"ruleType":{"type":"string","enum":["prohibition","restriction","observation"]},"code":{"type":"string","pattern":"^[\\d.\\s-]*$","default":""},"keywords":{"type":"array","items":{"type":"string","minLength":2,"maxLength":100},"maxItems":100,"default":[]},"origins":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":300,"default":[]},"title":{"type":"string","minLength":2,"maxLength":200},"summary":{"type":"string","maxLength":5000}},"required":["ruleType","title"],"description":"A rule your checks apply on top of border.bot’s: an HS code (and everything under it), words, or origins.","example":{"country":"US","ruleType":"prohibition","code":"9304","keywords":["airsoft"],"title":"No airsoft or air guns (company policy)"}},"RestrictionRuleRemoveResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean"}},"required":["removed"]}},"required":["data"]},"ScreenResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"checkId":{"type":["string","null"],"format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60","description":"The check’s id: your evidence that the name was screened (see `GET /screen/checks`)."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/ScreenMatch"}},"matchCount":{"type":"integer"},"searched":{"type":"array","items":{"type":"object","properties":{"dataset":{"type":"string"},"seq":{"type":"integer"}},"required":["dataset","seq"]},"description":"Every list screened, with the release it was at."},"screenedAt":{"type":"string"}},"required":["checkId","matches","matchCount","searched","screenedAt"]}},"required":["data"]},"ScreenMatch":{"type":"object","properties":{"score":{"type":"number","description":"0–1: 1 is an exact match of the name or an alias. Matches start at 0.7."},"matchedName":{"type":"string","description":"The name or alias that matched."},"query":{"type":"string","enum":["name","company"]},"list":{"type":"string","description":"The list that names the party (`SDN`, `Entity List`, `UN Security Council Consolidated List`, `UK Sanctions List`…)."},"listKind":{"type":["string","null"],"enum":["sanctions","export_control","debarment","other",null],"description":"The kind of list: sanctions, export controls or a debarment."},"issuer":{"type":["string","null"],"description":"Who issued the list (`US Treasury (OFAC)`, `UN Security Council`, `UK Government (FCDO)`…)."},"dataset":{"type":"string","description":"Where it came from: `US:parties` (the US lists), `GLOBAL:parties` (the UN), `EU:parties`, `GB:parties`…"},"countryMatch":{"type":"boolean"},"party":{"type":"object","properties":{"name":{"type":"string"},"altNames":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["individual","entity","vessel","aircraft","unknown"]},"programs":{"type":"array","items":{"type":"string"}},"addresses":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"country":{"type":["string","null"]}},"required":["address","country"]}},"sourceRef":{"type":["string","null"]},"startDate":{"type":["string","null"]},"endDate":{"type":["string","null"]},"remarks":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"identifiers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"country":{"type":["string","null"]},"label":{"type":["string","null"]}},"required":["type","value","country","label"]},"description":"Identity documents and registry numbers (`passport`, `national_id`, `tax_id`, `registration`, `imo`, `swift_bic`, `crypto`…), to tell a namesake from the party."},"countries":{"type":"array","items":{"type":"string"},"description":"Nationalities, citizenships, a vessel’s flag (ISO-2)."},"birthDates":{"type":"array","items":{"type":"string"},"description":"Dates of birth or build years, as precise as published (YYYY, YYYY-MM, YYYY-MM-DD)."}},"required":["name","altNames","type","programs","addresses","sourceRef","startDate","endDate","remarks","sourceUrl","identifiers","countries","birthDates"]}},"required":["score","matchedName","query","list","listKind","issuer","dataset","countryMatch","party"]},"ScreenRequest":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":500,"description":"The person’s or company’s name, as you have it.","example":"Northwind Maritime Holdings"},"company":{"type":"string","minLength":2,"maxLength":500,"description":"A company to screen too (a buyer and their employer, say)."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"The party’s country (ISO-2): matches with an address, nationality or flag there are flagged `countryMatch`.","example":"AE"},"type":{"type":"string","enum":["individual","entity"],"description":"Only parties of this type. Vessels, aircraft and parties of unknown type are always screened."},"reference":{"type":"string","maxLength":200,"description":"Your reference (an order or customer id), kept with the check as evidence.","example":"order-1001"}},"required":["name"]},"ScreeningChecksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"name":{"type":"string"},"company":{"type":["string","null"]},"country":{"type":["string","null"]},"reference":{"type":["string","null"]},"matchCount":{"type":"integer"},"topScore":{"type":["number","null"]},"actor":{"type":["string","null"]},"result":{"type":["object","null"],"properties":{"matches":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"matchedName":{"type":"string"},"list":{"type":"string"},"listKind":{"type":["string","null"]},"issuer":{"type":["string","null"]},"dataset":{"type":"string"},"name":{"type":"string"},"sourceRef":{"type":["string","null"]}},"required":["score","matchedName","list","dataset","name","sourceRef"]}},"searched":{"type":"array","items":{"type":"object","properties":{"dataset":{"type":"string"},"seq":{"type":"integer"}},"required":["dataset","seq"]}}},"required":["matches","searched"],"description":"What the check kept: each match and every list screened, at its release."},"createdAt":{"type":"string"}},"required":["id","name","company","country","reference","matchCount","topScore","actor","result","createdAt"]}}},"required":["data"]},"AirWaybillResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AirWaybill"},"credits":{"$ref":"#/components/schemas/CreditsCharged"},"replayed":{"type":"boolean","description":"True when this response was replayed from an earlier request with the same `Idempotency-Key` (no new charge)."}},"required":["data","credits","replayed"]},"AirWaybill":{"type":"object","properties":{"number":{"type":"string","description":"The waybill number as printed.","example":"125-1234 5675"},"filename":{"type":"string","example":"AWB-125-12345675.pdf"},"pages":{"type":"integer","description":"Copies, each followed by the conditions when asked.","example":6},"contentType":{"type":"string","enum":["application/pdf"]},"pdf":{"type":"string","format":"byte","description":"The PDF, base64."}},"required":["number","filename","pages","contentType","pdf"]},"AirWaybillRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["master","house"],"default":"master"},"prefix":{"type":"string","pattern":"^\\d{3}$"},"number":{"type":"string","minLength":1,"maxLength":20},"masterNumber":{"type":"string","maxLength":14},"shipper":{"type":"object","properties":{"name":{"type":"string","maxLength":70},"address":{"type":"string","maxLength":140},"city":{"type":"string","maxLength":40},"postcode":{"type":"string","maxLength":12},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"phone":{"type":"string","maxLength":25},"account":{"type":"string","maxLength":14}},"required":["name","address","city","country"]},"consignee":{"type":"object","properties":{"name":{"type":"string","maxLength":70},"address":{"type":"string","maxLength":140},"city":{"type":"string","maxLength":40},"postcode":{"type":"string","maxLength":12},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"phone":{"type":"string","maxLength":25},"account":{"type":"string","maxLength":14}},"required":["name","address","city","country"]},"issuer":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"address":{"type":"string","maxLength":120}},"required":["name"]},"agent":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"city":{"type":"string","maxLength":40},"iataCode":{"type":"string","maxLength":14},"account":{"type":"string","maxLength":14}},"default":{}},"accountingInformation":{"type":"string","maxLength":160},"departure":{"type":"string","pattern":"^[A-Z]{3}$"},"departureName":{"type":"string","maxLength":40},"destination":{"type":"string","pattern":"^[A-Z]{3}$"},"destinationName":{"type":"string","maxLength":30},"routing":{"type":"array","items":{"type":"object","properties":{"to":{"type":"string","pattern":"^[A-Z]{3}$"},"by":{"type":"string","pattern":"^[A-Z0-9]{2}$"}},"required":["to","by"]},"maxItems":3,"default":[]},"firstCarrierName":{"type":"string","maxLength":40},"flights":{"type":"array","items":{"type":"string","maxLength":14},"maxItems":2,"default":[]},"referenceNumber":{"type":"string","maxLength":20},"optionalShippingInformation":{"type":"string","maxLength":30},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"weightValuation":{"type":"string","enum":["PP","CC"],"default":"PP"},"otherChargesPaid":{"type":"string","enum":["PP","CC"],"default":"PP"},"declaredValueCarriage":{"type":"number","minimum":0,"maximum":99999999},"declaredValueCustoms":{"type":"number","minimum":0,"maximum":99999999},"insurance":{"type":"number","minimum":0,"maximum":99999999},"handlingInformation":{"type":"string","maxLength":240},"sci":{"type":"string","maxLength":4},"weightUnit":{"type":"string","enum":["kg","lb"],"default":"kg"},"dimensionUnit":{"type":"string","enum":["cm","in"],"default":"cm"},"volumeDivisor":{"type":"integer","minimum":1000,"maximum":10000,"default":6000},"lines":{"type":"array","items":{"type":"object","properties":{"pieces":{"type":"integer","exclusiveMinimum":0,"maximum":99999},"rcp":{"type":"string","pattern":"^[A-Z]{3}$"},"grossWeight":{"type":"number","exclusiveMinimum":0,"maximum":999999},"rateClass":{"type":"string","enum":["M","N","Q","B","K","C","R","S","U","E","X","Y","W"]},"commodityItem":{"type":"string","maxLength":7},"chargeableWeight":{"type":"number","exclusiveMinimum":0,"maximum":999999},"rate":{"type":"number","minimum":0,"maximum":99999999},"total":{"type":"number","minimum":0,"maximum":99999999},"description":{"type":"string","maxLength":240},"dimensions":{"type":"array","items":{"type":"object","properties":{"pieces":{"type":"integer","exclusiveMinimum":0,"maximum":9999},"length":{"type":"number","exclusiveMinimum":0,"maximum":9999},"width":{"type":"number","exclusiveMinimum":0,"maximum":9999},"height":{"type":"number","exclusiveMinimum":0,"maximum":9999}},"required":["pieces","length","width","height"]},"maxItems":20,"default":[]},"hsCodes":{"type":"array","items":{"type":"string","pattern":"^\\d{6,10}$"},"maxItems":6,"default":[]}},"required":["pieces","grossWeight","description"]},"minItems":1,"maxItems":4},"otherCharges":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$"},"dueTo":{"type":"string","enum":["A","C"]},"amount":{"type":"number","minimum":0,"maximum":99999999}},"required":["code","dueTo","amount"]},"maxItems":8,"default":[]},"valuationCharge":{"type":"number","minimum":0,"maximum":99999999},"tax":{"type":"number","minimum":0,"maximum":99999999},"shipperSignature":{"type":"string","maxLength":40},"executedOn":{"type":"string","format":"date"},"executedAt":{"type":"string","maxLength":30},"carrierSignature":{"type":"string","maxLength":40},"copies":{"type":"string","enum":["originals","full"],"default":"originals"},"conditions":{"type":"boolean","default":true}},"required":["number","shipper","consignee","issuer","departure","destination","currency","lines","executedOn","executedAt"],"description":"An air waybill as IATA Resolution 600a numbers its boxes. A master waybill needs the carrier’s prefix and an 8-digit serial whose last digit is the check digit (first seven digits mod 7); a house waybill takes the forwarder’s own number and names its master in `masterNumber`. Text is Latin script. Empty declared values print NVD and NCV, empty insurance XXX; chargeable weights and totals are worked out when left out (volume at 6000 cm³ per kg, rounded up to 0.5 kg or 1 lb).","example":{"kind":"master","prefix":"125","number":"12345675","shipper":{"name":"Northwind Apparel Ltd","address":"Unit 4, Bath Road Trading Estate","city":"Hounslow","postcode":"TW4 6HG","country":"GB","phone":"+44 20 7946 0000"},"consignee":{"name":"Harbor Street Retail Inc","address":"1200 Harbor Street, Suite 300","city":"Los Angeles","postcode":"CA 90021","country":"US","phone":"+1 213 555 0100"},"issuer":{"name":"British Airways World Cargo","address":"Heathrow Airport, Hounslow TW6 2JS"},"agent":{"name":"Skyline Forwarding Ltd","city":"London","iataCode":"91-4 7712/0010"},"accountingInformation":"FREIGHT PREPAID","departure":"LHR","departureName":"London Heathrow","destination":"LAX","destinationName":"Los Angeles","routing":[{"to":"LAX","by":"BA"}],"firstCarrierName":"British Airways","flights":["BA0283/14OCT"],"currency":"GBP","weightValuation":"PP","otherChargesPaid":"PP","handlingInformation":"NOTIFY CONSIGNEE ON ARRIVAL. COMMERCIAL INVOICE AND PACKING LIST ATTACHED.","sci":"X","lines":[{"pieces":4,"grossWeight":86.4,"rateClass":"Q","rate":3.85,"description":"Cotton knitted T-shirts and hoodies, 480 units","hsCodes":["610910","611020"],"dimensions":[{"pieces":4,"length":60,"width":40,"height":45}]}],"otherCharges":[{"code":"AW","dueTo":"A","amount":25},{"code":"MY","dueTo":"C","amount":51.84},{"code":"SC","dueTo":"C","amount":12.96}],"shipperSignature":"Skyline Forwarding Ltd","executedOn":"2026-10-13","executedAt":"London","copies":"originals","conditions":true}},"BulkRunResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkRun"}},"required":["data"]},"BulkRun":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["classify","calculate","regulator","origin"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"total":{"type":"integer"},"done":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"creditsCharged":{"type":"integer"},"reference":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","kind","status","total","done","succeeded","failed","creditsCharged","reference","error","createdAt","completedAt"]},"BulkRunRequest":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["classify"]},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":2,"maxLength":2000},"productUrl":{"type":"string","maxLength":2048},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}]},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"mode":{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,30}$"},"title":{"type":"string","maxLength":300},"brand":{"type":"string","maxLength":120},"sku":{"type":"string","maxLength":120},"price":{"type":"number","minimum":0,"maximum":10000000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"hsCodeHint":{"type":"string","pattern":"^\\d[\\d.]{1,12}$"}},"required":["destinationCountry"]},"minItems":1,"maxItems":10000},"reference":{"type":"string","maxLength":200}},"required":["kind","items"]},{"type":"object","properties":{"kind":{"type":"string","enum":["calculate"]},"items":{"type":"array","items":{"type":"object","properties":{"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","default":"USD"},"shippingCost":{"type":"number","minimum":0,"maximum":10000000},"insuranceCost":{"type":"number","minimum":0,"maximum":10000000},"transportMode":{"type":"string","enum":["air","sea","road","rail"],"default":"air"},"shippingTerms":{"type":"string","enum":["EXW","FCA","FAS","FOB","CFR","CIF","CPT","CIP","DAP","DPU","DDP"]},"shipmentChannel":{"type":"string","enum":["courier","postal","freight"]},"entryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"tradeAgreement":{"type":"string","maxLength":40},"region":{"type":"string","pattern":"^[A-Z0-9-]{1,6}$"},"purpose":{"type":"string","enum":["sale","gift","sample","return"]},"sender":{"type":"string","enum":["person","business"]},"giftInConjunctionWithPurchase":{"type":"boolean"},"businessBuyer":{"type":"boolean"},"sellerRegistrations":{"type":"array","items":{"type":"string","pattern":"^[A-Z][A-Z0-9_]{1,20}$"},"maxItems":10},"preference":{"type":"string","minLength":1,"maxLength":20},"claims":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"maxItems":20},"enforceValidation":{"type":"boolean"},"declarationType":{"type":"string","enum":["full","simplified"]},"filing":{"type":"object","properties":{"method":{"type":"string","enum":["electronic","paper"]},"preparedBy":{"type":"string","enum":["declarant","authority"]}}},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"value":{"type":"number","exclusiveMinimum":0,"maximum":100000000},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":1000000,"default":1},"weight":{"type":"number","exclusiveMinimum":0,"maximum":1000000},"weightUnit":{"type":"string","enum":["kg","lb"]},"volumeLiters":{"type":"number","exclusiveMinimum":0,"maximum":100000000},"alcoholPercent":{"type":"number","minimum":0,"maximum":100},"components":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","minLength":2,"maxLength":40},"value":{"type":"number","minimum":0,"maximum":100000000}},"required":["material","value"]},"maxItems":10},"metalWeightPercent":{"type":"number","minimum":0,"maximum":100},"materials":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"weight":{"type":"number","minimum":0,"maximum":10000000},"weightUnit":{"type":"string","enum":["kg","lb"]},"sharePercent":{"type":"number","minimum":0,"maximum":100},"value":{"type":"number","minimum":0,"maximum":100000000},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["kind","country"]},"maxItems":6}},"required":["material"]},"maxItems":20},"conditions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,19}$"},"maxItems":10},"declaredPrice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":100000000},"per":{"type":"string","minLength":1,"maxLength":40}},"required":["amount","per"]},"salePrice":{"type":"number","minimum":0,"maximum":100000000},"entryProvision":{"type":"object","properties":{"kind":{"type":"string","enum":["repair_abroad","processing_abroad","assembled_abroad","agreement_provision","returned","other"]},"code":{"type":"string","pattern":"^[\\d.]{4,14}$"},"dutiableValue":{"type":"number","minimum":0,"maximum":100000000}},"required":["kind"]}},"required":["destinationCountry","hsCode","originCountry","value"]},"minItems":1,"maxItems":10000},"reference":{"type":"string","maxLength":200}},"required":["kind","items"]},{"type":"object","properties":{"kind":{"type":"string","enum":["regulator"]},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":2000},"destinationCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]{4,16}$"}},"required":["description","destinationCountry"]},"minItems":1,"maxItems":10000},"reference":{"type":"string","maxLength":200}},"required":["kind","items"]},{"type":"object","properties":{"kind":{"type":"string","enum":["origin"]},"items":{"type":"array","items":{"type":"object","properties":{"productUrl":{"type":"string","maxLength":2048},"imageUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"string","maxLength":8400000,"pattern":"^data:image\\/(jpeg|png|webp|gif);base64,"}]},"description":{"type":"string","maxLength":2000},"title":{"type":"string","maxLength":300},"brand":{"type":"string","maxLength":120},"sku":{"type":"string","maxLength":120},"gtin":{"type":"string","pattern":"^\\d{8,14}$"},"material":{"type":"string","maxLength":300},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10},"price":{"type":"number","minimum":0,"maximum":10000000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"shipFromCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"reviewThreshold":{"type":"number","minimum":0,"maximum":1},"declaredOrigin":{"type":"string","pattern":"^[A-Za-z]{2}$"}}},"minItems":1,"maxItems":10000},"reference":{"type":"string","maxLength":200}},"required":["kind","items"]}],"description":"Up to 10,000 items of one kind, each exactly as its single endpoint takes it (`POST /classify`, `POST /calculate`, `POST /classify/regulator` or, for `origin`, an item of `POST /origin/batch`). Each item is charged when it runs, and refunded if it fails.","example":{"kind":"classify","reference":"catalogue-2026-10","items":[{"description":"Men's cotton t-shirt","destinationCountry":"US"},{"description":"Stainless steel water bottle, 750 ml","destinationCountry":"GB"}]}},"BulkRunsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkRun"}}},"required":["data"]},"BulkResultsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/BulkRun"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"result":{"description":"The item’s answer, exactly as its single endpoint returns it."},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"credits":{"type":"integer"},"usageId":{"type":["string","null"]}},"required":["index","ok","credits","usageId"]}},"next":{"type":["integer","null"],"description":"The `offset` of the next page, if any."}},"required":["run","results","next"]}},"required":["data"]},"CatalogProductsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProductSummary"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page; null on the last."}},"required":["data","nextCursor"]},"CatalogProductSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Product id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"status":{"type":"string","enum":["draft","active","archived"]},"title":{"type":"string"},"brand":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"originCountry":{"type":["string","null"]},"category":{"type":["string","null"]},"skus":{"type":"array","items":{"type":"string"}},"itemCount":{"type":"integer"},"effectiveMarkets":{"type":"array","items":{"type":"string"}},"codes":{"type":"object","additionalProperties":{"type":"string"},"description":"The approved code per schedule.","example":{"US":"7323930080","EU":"7323930010"}},"reviewMarkets":{"type":"array","items":{"type":"string"},"description":"Markets with a suggestion waiting for review."},"sourceKinds":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["id","status","title","brand","imageUrl","originCountry","category","skus","itemCount","effectiveMarkets","codes","reviewMarkets","sourceKinds","updatedAt"]},"CatalogProductResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogProduct"}},"required":["data"]},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Product id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"status":{"type":"string","enum":["draft","active","archived"]},"title":{"type":"string"},"description":{"type":["string","null"]},"brand":{"type":["string","null"]},"manufacturerName":{"type":["string","null"]},"manufacturerCountry":{"type":["string","null"]},"category":{"type":["string","null"],"description":"A `category` term."},"materialSummary":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"imageUrls":{"type":"array","items":{"type":"string"}},"productUrl":{"type":["string","null"]},"slug":{"type":["string","null"]},"originCountry":{"type":["string","null"]},"originBasis":{"type":["string","null"],"description":"An `origin_basis` term."},"originEvidence":{"type":["object","null"],"properties":{"note":{"type":["string","null"]},"documentRef":{"type":["string","null"]},"probability":{"type":["number","null"]}}},"preferentialClaims":{"type":"array","items":{"type":"object","properties":{"programme":{"type":"string"},"basis":{"type":["string","null"]},"documentRef":{"type":["string","null"]},"validFrom":{"type":["string","null"]},"validTo":{"type":["string","null"]}},"required":["programme"]}},"attributes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"note":{"type":["string","null"]}},"required":["kind"]}},"markets":{"type":["array","null"],"items":{"type":"string"},"description":"Its own markets; null: the workspace’s defaults."},"effectiveMarkets":{"type":"array","items":{"type":"string"}},"quantityUnit":{"type":["string","null"]},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"perItem":{"type":"number"}},"required":["unit","perItem"]}},"extra":{"type":"object","additionalProperties":{}},"fieldSources":{"type":"object","additionalProperties":{"type":"object","properties":{"source":{"type":"string"},"sourceId":{"type":["string","null"]},"at":{"type":"string"}},"required":["source","at"]},"description":"Which source last set each field (`manual`, `api`, `mcp`, `csv`, `shopify`…) and when. A sync leaves fields a person last set by hand as they are."},"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"components":{"type":"array","items":{"$ref":"#/components/schemas/CatalogContentComponent"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProductSource"}},"classifications":{"type":"array","items":{"$ref":"#/components/schemas/CatalogClassification"},"description":"Current codes: the approved one and any suggestion waiting for review, per schedule."},"createdBy":{"type":["string","null"]},"updatedBy":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"},"archivedAt":{"type":["string","null"]}},"required":["id","status","title","description","brand","manufacturerName","manufacturerCountry","category","materialSummary","tags","imageUrls","productUrl","slug","originCountry","originBasis","originEvidence","preferentialClaims","attributes","markets","effectiveMarkets","quantityUnit","supplementaryUnits","extra","fieldSources","items","components","sources","classifications","createdBy","updatedBy","createdAt","updatedAt","archivedAt"]},"CatalogItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Item id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"status":{"type":"string","enum":["active","archived"]},"sku":{"type":["string","null"]},"gtin":{"type":["string","null"]},"mpn":{"type":["string","null"]},"title":{"type":["string","null"]},"options":{"type":"object","additionalProperties":{"type":"string"}},"unitValue":{"type":["number","null"]},"currency":{"type":["string","null"]},"weight":{"type":["number","null"]},"weightUnit":{"type":["string","null"]},"length":{"type":["number","null"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"dimensionUnit":{"type":["string","null"]},"originCountry":{"type":["string","null"]},"position":{"type":"integer"},"fieldSources":{"type":"object","additionalProperties":{"type":"object","properties":{"source":{"type":"string"},"sourceId":{"type":["string","null"]},"at":{"type":"string"}},"required":["source","at"]},"description":"Which source last set each field (`manual`, `api`, `mcp`, `csv`, `shopify`…) and when. A sync leaves fields a person last set by hand as they are."}},"required":["id","status","sku","gtin","mpn","title","options","unitValue","currency","weight","weightUnit","length","width","height","dimensionUnit","originCountry","position","fieldSources"]},"CatalogContentComponent":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Component id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"material":{"type":"string","description":"A `material` term (`GET /catalog/terms`).","example":"steel"},"sharePercent":{"type":["number","null"]},"weight":{"type":["number","null"]},"weightUnit":{"type":["string","null"]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"country":{"type":"string"}},"required":["kind","country"]},"description":"Where the material was produced, by stage (`melt_pour`, `smelt`, `cast`, `harvest`, `production`)."},"notes":{"type":["string","null"]}},"required":["id","material","sharePercent","weight","weightUnit","value","currency","origins","notes"]},"CatalogProductSource":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Source id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"kind":{"type":"string","description":"A source kind (`GET /catalog/sources`).","example":"shopify"},"kindLabel":{"type":"string"},"connection":{"type":"string","description":"The store, account or feed (a shop domain, a store URL)."},"externalKey":{"type":"string"},"externalIds":{"type":"object","additionalProperties":{"type":"string"},"description":"The source’s identifiers, by its kind’s identifier fields."},"itemId":{"type":["string","null"]},"url":{"type":["string","null"]},"syncDirection":{"type":"string","enum":["import","export","both"]},"lastSyncedAt":{"type":["string","null"]},"status":{"type":"string","enum":["active","detached"]},"data":{"type":"object","additionalProperties":{},"description":"The source’s own data as it gave it."}},"required":["id","kind","kindLabel","connection","externalKey","externalIds","itemId","url","syncDirection","lastSyncedAt","status","data"]},"CatalogClassification":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Classification id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"market":{"type":"string","description":"The market (ISO-2) it was asked for.","example":"DE"},"schedule":{"type":"string","description":"The tariff that classifies for the market (`EU` for Germany): one approved code per schedule.","example":"EU"},"code":{"type":"string","example":"7323930010"},"codeFormatted":{"type":"string"},"hs6":{"type":"string"},"description":{"type":["string","null"]},"source":{"type":"string","enum":["manual","ai","import","sync"]},"sourceKind":{"type":["string","null"]},"status":{"type":"string","enum":["suggested","approved","rejected","superseded"]},"confidence":{"type":["string","null"]},"probability":{"type":["number","null"]},"reasoning":{"type":["string","null"]},"mode":{"type":["string","null"]},"usageId":{"type":["string","null"]},"alternatives":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"probability":{"type":["number","null"]}},"required":["code"]}},"reviewedBy":{"type":["string","null"]},"reviewedAt":{"type":["string","null"]},"reviewNote":{"type":["string","null"]},"validFrom":{"type":["string","null"],"description":"Approved: from when it applies."},"validTo":{"type":["string","null"],"description":"Superseded: until when it applied."},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["id","market","schedule","code","codeFormatted","hs6","description","source","sourceKind","status","confidence","probability","reasoning","mode","usageId","alternatives","reviewedBy","reviewedAt","reviewNote","validFrom","validTo","createdBy","createdAt"]},"CatalogProductCreate":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":["string","null"],"maxLength":10000},"brand":{"type":["string","null"],"maxLength":200},"manufacturerName":{"type":["string","null"],"maxLength":300},"manufacturerCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"category":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"materialSummary":{"type":["string","null"],"maxLength":1000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":30},"imageUrls":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10},"productUrl":{"type":["string","null"],"maxLength":2048},"slug":{"type":["string","null"],"pattern":"^[a-z0-9][a-z0-9-]{0,199}$"},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"originBasis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"originEvidence":{"type":["object","null"],"properties":{"note":{"type":["string","null"],"maxLength":1000},"documentRef":{"type":["string","null"],"maxLength":200},"probability":{"type":["number","null"],"minimum":0,"maximum":1}}},"preferentialClaims":{"type":"array","items":{"type":"object","properties":{"programme":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9_-]{0,29}$"},"basis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"documentRef":{"type":["string","null"],"maxLength":200},"validFrom":{"type":["string","null"],"format":"date"},"validTo":{"type":["string","null"],"format":"date"}},"required":["programme"]},"maxItems":10},"attributes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"note":{"type":["string","null"],"maxLength":300}},"required":["kind"]},"maxItems":20},"markets":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60},"quantityUnit":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"perItem":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["unit","perItem"]},"maxItems":5},"extra":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["draft","active"]},"sku":{"type":["string","null"],"maxLength":120},"gtin":{"type":["string","null"],"pattern":"^\\d{8,14}$"},"mpn":{"type":["string","null"],"maxLength":120},"unitValue":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":["string","null"],"maxLength":120},"gtin":{"type":["string","null"],"pattern":"^\\d{8,14}$"},"mpn":{"type":["string","null"],"maxLength":120},"title":{"type":["string","null"],"maxLength":200},"options":{"type":"object","additionalProperties":{"type":"string","maxLength":120}},"unitValue":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"length":{"type":["number","null"],"minimum":0,"maximum":100000},"width":{"type":["number","null"],"minimum":0,"maximum":100000},"height":{"type":["number","null"],"minimum":0,"maximum":100000},"dimensionUnit":{"type":["string","null"],"enum":["mm","cm","m","in",null]},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"position":{"type":"integer","minimum":0,"maximum":10000},"status":{"type":"string","enum":["active","archived"]}}},"maxItems":100},"components":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"sharePercent":{"type":["number","null"],"minimum":0,"maximum":100},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"value":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["kind","country"]},"maxItems":6},"notes":{"type":["string","null"],"maxLength":500}},"required":["material"]},"maxItems":20},"source":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"connection":{"type":"string","maxLength":300},"externalIds":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":300}},"externalKey":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2048},"data":{"type":"object","additionalProperties":{}}},"required":["kind"]},"codes":{"type":"array","items":{"type":"object","properties":{"market":{"type":"string","pattern":"^[A-Za-z]{2}$"},"code":{"type":"string","pattern":"^[\\d.\\s-]+$"}},"required":["market","code"]},"maxItems":60}},"required":["title"],"description":"A product and its items. With no `items`, the top-level `sku`, `unitValue`, `weight`… are its one item’s. `components` declare what it is made of (harmonised `material` codes with weight or share, value and where each was produced by stage: `melt_pour`, `smelt`, `cast`, `harvest`, `production`); landed cost by SKU reads them. `source` names where it comes from (a source kind and its identifiers there). `codes` are codes you already hold per market, stored approved.","example":{"title":"Stainless steel water bottle 750 ml","brand":"Acme","materialSummary":"stainless steel body, polypropylene lid","originCountry":"CN","markets":["US","GB","DE"],"sku":"BOTTLE-750","unitValue":20,"currency":"USD","weight":350,"weightUnit":"g","components":[{"material":"steel","weight":300,"weightUnit":"g","value":6,"currency":"USD","origins":[{"kind":"melt_pour","country":"US"}]},{"material":"plastic","weight":50,"weightUnit":"g"}],"source":{"kind":"api","externalIds":{"id":"erp-10023"}}}},"CatalogProductUpdate":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":["string","null"],"maxLength":10000},"brand":{"type":["string","null"],"maxLength":200},"manufacturerName":{"type":["string","null"],"maxLength":300},"manufacturerCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"category":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"materialSummary":{"type":["string","null"],"maxLength":1000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":30},"imageUrls":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10},"productUrl":{"type":["string","null"],"maxLength":2048},"slug":{"type":["string","null"],"pattern":"^[a-z0-9][a-z0-9-]{0,199}$"},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"originBasis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"originEvidence":{"type":["object","null"],"properties":{"note":{"type":["string","null"],"maxLength":1000},"documentRef":{"type":["string","null"],"maxLength":200},"probability":{"type":["number","null"],"minimum":0,"maximum":1}}},"preferentialClaims":{"type":"array","items":{"type":"object","properties":{"programme":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9_-]{0,29}$"},"basis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"documentRef":{"type":["string","null"],"maxLength":200},"validFrom":{"type":["string","null"],"format":"date"},"validTo":{"type":["string","null"],"format":"date"}},"required":["programme"]},"maxItems":10},"attributes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"note":{"type":["string","null"],"maxLength":300}},"required":["kind"]},"maxItems":20},"markets":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60},"quantityUnit":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"perItem":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["unit","perItem"]},"maxItems":5},"extra":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["draft","active"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sku":{"type":["string","null"],"maxLength":120},"gtin":{"type":["string","null"],"pattern":"^\\d{8,14}$"},"mpn":{"type":["string","null"],"maxLength":120},"title":{"type":["string","null"],"maxLength":200},"options":{"type":"object","additionalProperties":{"type":"string","maxLength":120}},"unitValue":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"length":{"type":["number","null"],"minimum":0,"maximum":100000},"width":{"type":["number","null"],"minimum":0,"maximum":100000},"height":{"type":["number","null"],"minimum":0,"maximum":100000},"dimensionUnit":{"type":["string","null"],"enum":["mm","cm","m","in",null]},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"position":{"type":"integer","minimum":0,"maximum":10000},"status":{"type":"string","enum":["active","archived"]}}},"maxItems":100},"components":{"type":"array","items":{"type":"object","properties":{"material":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"sharePercent":{"type":["number","null"],"minimum":0,"maximum":100},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"value":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"origins":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["kind","country"]},"maxItems":6},"notes":{"type":["string","null"],"maxLength":500}},"required":["material"]},"maxItems":20}},"description":"Only the fields given change (`null` clears one). `items` change items by `id` (or `sku`) and add the others; `status: \"archived\"` on an item retires it. `components` replaces the content list (the rows it replaces are kept, retired). A product that is archived changes only to be restored (`status`).","example":{"originCountry":"VN","items":[{"sku":"BOTTLE-750","unitValue":21.5}]}},"CatalogHistoryResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"table":{"type":"string","enum":["products","items","product_sources","content_components","classifications"]},"rowId":{"type":["string","null"]},"op":{"type":"string","enum":["insert","update","delete"]},"actor":{"type":["string","null"]},"changed":{"type":["array","null"],"items":{"type":"string"}},"before":{"type":["object","null"],"additionalProperties":{}},"after":{"type":["object","null"],"additionalProperties":{}},"at":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["id","table","rowId","op","actor","changed","before","after","at"]}}},"required":["data"]},"CatalogClassificationsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogClassification"}}},"required":["data"]},"CatalogClassificationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogClassification"}},"required":["data"]},"CatalogClassificationCreate":{"type":"object","properties":{"market":{"type":"string","pattern":"^[A-Za-z]{2}$"},"code":{"type":"string","pattern":"^[\\d.\\s-]+$"},"approve":{"type":"boolean","default":false},"description":{"type":["string","null"],"maxLength":1000},"note":{"type":["string","null"],"maxLength":1000}},"required":["market","code"],"description":"A code you hold for a market. Stored as a suggestion to review, or approved at once with `approve: true` (the schedule’s approved code before it is superseded and kept).","example":{"market":"US","code":"7323.93.0080","approve":true}},"CatalogSuggestResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"market":{"type":"string"},"ok":{"type":"boolean"},"classification":{"$ref":"#/components/schemas/CatalogClassification"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"credits":{"type":"number"}},"required":["market","ok","credits"]}}},"required":["results"]},"credits":{"type":"object","properties":{"charged":{"type":"number"},"remaining":{"type":["number","null"]}},"required":["charged","remaining"]}},"required":["data","credits"]},"CatalogClassificationSuggest":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"minItems":1,"maxItems":20},"mode":{"type":"string","maxLength":31}},"required":["markets"],"description":"Classify the product for these markets (one classification per market, each charged like `POST /classify`).","example":{"markets":["US","GB","DE"]}},"CatalogClassificationReview":{"type":"object","properties":{"note":{"type":["string","null"],"maxLength":1000}}},"CatalogBulkClassifyRequest":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":2000},"filter":{"type":"object","properties":{"q":{"type":"string","maxLength":200},"status":{"type":"string","enum":["draft","active","archived"]},"market":{"type":"string","pattern":"^[A-Za-z]{2}$"},"missingCodeFor":{"type":"string","pattern":"^[A-Za-z]{2}$"},"needsReview":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"origin":{"type":"string","pattern":"^[A-Za-z]{2}$"},"source":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"}}},"markets":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"minItems":1,"maxItems":20},"onlyMissing":{"type":"boolean","default":true},"mode":{"type":"string","maxLength":31}},"required":["markets"],"description":"Classify many products (by id, or every product a filter finds, up to 2,000) for markets, in the background: a bulk run whose answers are kept as suggestions to review. Each classification is charged like `POST /classify`; `onlyMissing` (default) skips markets a product already has an approved code for.","example":{"filter":{"missingCodeFor":"US"},"markets":["US"]}},"CatalogImportResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":["string","null"]},"dryRun":{"type":"boolean"},"status":{"type":"string","enum":["dry_run","completed","failed"]},"total":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"field":{"type":["string","null"]},"message":{"type":"string"}},"required":["row","message"]}},"mapping":{"type":"object","additionalProperties":{"type":"string"}},"preview":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"action":{"type":"string","enum":["create","update","unchanged","error"]},"sku":{"type":["string","null"]},"title":{"type":["string","null"]}},"required":["row","action","sku","title"]}}},"required":["id","dryRun","status","total","created","updated","unchanged","failed","errors","mapping","preview"]}},"required":["data"]},"CatalogImportRequest":{"type":"object","properties":{"csv":{"type":"string","minLength":1,"maxLength":5242880},"filename":{"type":"string","maxLength":200},"mapping":{"type":"object","properties":{"sku":{"type":"string","maxLength":200},"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":200},"brand":{"type":"string","maxLength":200},"manufacturer_name":{"type":"string","maxLength":200},"manufacturer_country":{"type":"string","maxLength":200},"category":{"type":"string","maxLength":200},"material_summary":{"type":"string","maxLength":200},"tags":{"type":"string","maxLength":200},"image_url":{"type":"string","maxLength":200},"product_url":{"type":"string","maxLength":200},"origin_country":{"type":"string","maxLength":200},"origin_basis":{"type":"string","maxLength":200},"markets":{"type":"string","maxLength":200},"gtin":{"type":"string","maxLength":200},"mpn":{"type":"string","maxLength":200},"item_title":{"type":"string","maxLength":200},"unit_value":{"type":"string","maxLength":200},"currency":{"type":"string","maxLength":200},"weight":{"type":"string","maxLength":200},"weight_unit":{"type":"string","maxLength":200},"length":{"type":"string","maxLength":200},"width":{"type":"string","maxLength":200},"height":{"type":"string","maxLength":200},"dimension_unit":{"type":"string","maxLength":200},"quantity_unit":{"type":"string","maxLength":200},"external_id":{"type":"string","maxLength":200},"product_key":{"type":"string","maxLength":200},"hs_code":{"type":"string","maxLength":200},"hs_code_market":{"type":"string","maxLength":200},"status":{"type":"string","maxLength":200}}},"dryRun":{"type":"boolean","default":true},"sourceKind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$","default":"csv"},"connection":{"type":"string","maxLength":300},"approveCodes":{"type":"boolean","default":true}},"required":["csv"],"description":"A CSV file’s text. Columns map to catalogue fields by `mapping` (field → header), else by their headers (`sku`, `title`, `origin_country`, `unit_value`, `currency`, `weight`, `weight_unit`, `gtin`, `hs_code` with `hs_code_market`, or `hs_code_<market>` columns…). A row is found again by `external_id` or `sku`, so the same file imports once; rows sharing `product_key` are one product’s items. `dryRun` (the default) reports what would change without writing.","example":{"csv":"sku,title,origin_country,unit_value,currency,hs_code_us\nBOTTLE-750,Steel water bottle,CN,20,USD,7323930080","filename":"catalogue.csv","dryRun":true}},"CatalogImportsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["dry_run","completed","failed"]},"dryRun":{"type":"boolean"},"sourceKind":{"type":"string"},"filename":{"type":["string","null"]},"total":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"field":{"type":["string","null"]},"message":{"type":"string"}},"required":["row","message"]}},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["id","status","dryRun","sourceKind","filename","total","created","updated","unchanged","failed","errors","createdBy","createdAt"]}}},"required":["data"]},"CatalogImportRecordResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["dry_run","completed","failed"]},"dryRun":{"type":"boolean"},"sourceKind":{"type":"string"},"filename":{"type":["string","null"]},"total":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"field":{"type":["string","null"]},"message":{"type":"string"}},"required":["row","message"]}},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["id","status","dryRun","sourceKind","filename","total","created","updated","unchanged","failed","errors","createdBy","createdAt"]}},"required":["data"]},"CatalogExportResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"csv":{"type":"string","description":"One row per item, with the approved code per market in `hs_code_<market>` columns."},"rows":{"type":"integer"},"truncated":{"type":"boolean","description":"More than 10,000 products matched: narrow the filter."}},"required":["csv","rows","truncated"]}},"required":["data"]},"CatalogSyncResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"removed":{"type":"integer"},"failed":{"type":"integer"},"records":{"type":"array","items":{"type":"object","properties":{"externalKey":{"type":"string"},"productId":{"type":["string","null"]},"itemId":{"type":["string","null"]},"outcome":{"type":"string","enum":["created","updated","unchanged","removed","failed"]},"error":{"type":"string"}},"required":["externalKey","productId","itemId","outcome"]}}},"required":["created","updated","unchanged","removed","failed","records"]}},"required":["data"]},"CatalogSyncRequest":{"type":"object","properties":{"sourceKind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"connection":{"type":"string","minLength":1,"maxLength":300},"records":{"type":"array","items":{"type":"object","properties":{"externalKey":{"type":"string","minLength":1,"maxLength":300},"externalIds":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":300}},"groupKey":{"type":["string","null"],"maxLength":300},"url":{"type":["string","null"],"maxLength":2048},"product":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":["string","null"],"maxLength":10000},"brand":{"type":["string","null"],"maxLength":200},"manufacturerName":{"type":["string","null"],"maxLength":300},"manufacturerCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"category":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"materialSummary":{"type":["string","null"],"maxLength":1000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":30},"imageUrls":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10},"productUrl":{"type":["string","null"],"maxLength":2048},"slug":{"type":["string","null"],"pattern":"^[a-z0-9][a-z0-9-]{0,199}$"},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"},"originBasis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"originEvidence":{"type":["object","null"],"properties":{"note":{"type":["string","null"],"maxLength":1000},"documentRef":{"type":["string","null"],"maxLength":200},"probability":{"type":["number","null"],"minimum":0,"maximum":1}}},"preferentialClaims":{"type":"array","items":{"type":"object","properties":{"programme":{"type":"string","pattern":"^[A-Z0-9][A-Z0-9_-]{0,29}$"},"basis":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"documentRef":{"type":["string","null"],"maxLength":200},"validFrom":{"type":["string","null"],"format":"date"},"validTo":{"type":["string","null"],"format":"date"}},"required":["programme"]},"maxItems":10},"attributes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"value":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"note":{"type":["string","null"],"maxLength":300}},"required":["kind"]},"maxItems":20},"markets":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60},"quantityUnit":{"type":["string","null"],"pattern":"^[a-z][a-z0-9_]{1,39}$"},"supplementaryUnits":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"perItem":{"type":"number","exclusiveMinimum":0,"maximum":1000000}},"required":["unit","perItem"]},"maxItems":5},"extra":{"type":"object","additionalProperties":{}}},"required":["title"]},"item":{"type":"object","properties":{"sku":{"type":["string","null"],"maxLength":120},"gtin":{"type":["string","null"],"pattern":"^\\d{8,14}$"},"mpn":{"type":["string","null"],"maxLength":120},"title":{"type":["string","null"],"maxLength":200},"options":{"type":"object","additionalProperties":{"type":"string","maxLength":120}},"unitValue":{"type":["number","null"],"minimum":0,"maximum":100000000},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"weight":{"type":["number","null"],"minimum":0,"maximum":1000000},"weightUnit":{"type":["string","null"],"enum":["kg","g","lb","oz",null]},"length":{"type":["number","null"],"minimum":0,"maximum":100000},"width":{"type":["number","null"],"minimum":0,"maximum":100000},"height":{"type":["number","null"],"minimum":0,"maximum":100000},"dimensionUnit":{"type":["string","null"],"enum":["mm","cm","m","in",null]},"originCountry":{"type":["string","null"],"pattern":"^[A-Za-z]{2}$"}}},"data":{"type":"object","additionalProperties":{}},"codes":{"type":"array","items":{"type":"object","properties":{"market":{"type":"string","pattern":"^[A-Za-z]{2}$"},"code":{"type":"string","pattern":"^[\\d.\\s-]+$"}},"required":["market","code"]},"maxItems":60},"removed":{"type":"boolean"}},"required":["externalKey","externalIds","product","item"]},"minItems":1,"maxItems":250}},"required":["sourceKind","connection","records"],"description":"A page of records from a source you keep in step (a store, a marketplace, a feed, an ERP): each record is one sellable item in catalogue terms. A record is found again by `externalKey` within the connection; records sharing `groupKey` are one product’s items. Fields a person last changed by hand keep their value. `codes` the source carries are kept as suggestions from it.","example":{"sourceKind":"woocommerce","connection":"https://shop.example.com","records":[{"externalKey":"1042","externalIds":{"productId":"1040","variationId":"1042"},"groupKey":"1040","product":{"title":"Merino scarf","originCountry":"NZ"},"item":{"sku":"SCARF-GREY","unitValue":49,"currency":"NZD","weight":120,"weightUnit":"g"}}]}},"CatalogSyncCodesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"externalKey":{"type":"string"},"externalIds":{"type":"object","additionalProperties":{"type":"string"}},"groupKey":{"type":["string","null"]},"productId":{"type":"string"},"market":{"type":"string"},"schedule":{"type":"string"},"code":{"type":"string"},"hs6":{"type":"string"},"originCountry":{"type":["string","null"]},"approvedAt":{"type":"string","description":"ISO 8601 timestamp.","example":"2026-10-10T09:00:00.000Z"}},"required":["externalKey","externalIds","groupKey","productId","market","schedule","code","hs6","originCountry","approvedAt"]}}},"required":["data"]},"CatalogTermsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"vocabulary":{"type":"string","description":"`material`, `material_origin`, `attribute`, `category`, `origin_basis`, `quantity_unit`"},"code":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"meta":{"type":"object","additionalProperties":{}}},"required":["vocabulary","code","label","description","meta"]}}},"required":["data"]},"CatalogSourceKindsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","description":"`manual`, `file`, `api`, `platform`, `marketplace` or `feed`."},"homepage":{"type":["string","null"]},"externalIdFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"]}},"primaryIdField":{"type":["string","null"]},"connectionLabel":{"type":["string","null"]},"connector":{"type":["string","null"]}},"required":["id","label","kind","homepage","externalIdFields","primaryIdField","connectionLabel","connector"]}}},"required":["data"]},"CatalogMarketsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"string"}}},"required":["markets"]}},"required":["data"]},"CatalogMarketsRequest":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60}},"required":["markets"],"example":{"markets":["US","GB","DE","CA"]}},"MeResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]}},"required":["id","name","status"]},"apiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":["array","null"],"items":{"type":"string","enum":["classify","calculate","origin","compliance","catalog","bulk","documents","settings","account"]},"description":"What the key may do; null is full access."},"expiresAt":{"type":["string","null"],"description":"When the key stops working (null: never)."}},"required":["id","name","prefix","scopes","expiresAt"]},"credits":{"type":"object","properties":{"balance":{"type":"integer"}},"required":["balance"]}},"required":["organization","apiKey","credits"]}},"required":["data"]},"CreditsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"type":"integer"},"lifetimePurchased":{"type":"integer"},"lifetimeGranted":{"type":"integer"},"lifetimeUsed":{"type":"integer"},"lowBalanceThreshold":{"type":"integer"},"recentLedger":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}}},"required":["balance","lifetimePurchased","lifetimeGranted","lifetimeUsed","lowBalanceThreshold","recentLedger"]}},"required":["data"]},"LedgerEntry":{"type":"object","properties":{"id":{"type":"string"},"delta":{"type":"integer","description":"Positive = added, negative = spent/removed."},"balanceAfter":{"type":"integer"},"kind":{"type":"string","enum":["purchase","usage","refund","signup_bonus","grant","adjustment","chargeback"]},"action":{"type":["string","null"]},"usageId":{"type":["string","null"]},"note":{"type":["string","null"]},"actor":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","delta","balanceAfter","kind","action","usageId","note","actor","createdAt"]},"UsageResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageItem"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next (older) page; null at the end."}},"required":["data","nextCursor"]},"UsageItem":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["classify","classify_max","classify_regulator","calculate","calculate_stacking","extract_product","infer_origin","air_waybill"]},"source":{"type":"string","enum":["dashboard","api","mcp","webmcp"]},"status":{"type":"string","enum":["pending","succeeded","failed","refunded"]},"credits":{"type":"integer"},"summary":{"type":["string","null"]},"actor":{"type":["string","null"]},"errorCode":{"type":["string","null"]},"durationMs":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","action","source","status","credits","summary","actor","errorCode","durationMs","createdAt","completedAt"]},"ApiRequestsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"requestId":{"type":"string","description":"The `X-Request-Id` the response carried: a UUIDv7 (older requests keep their `req_…` id).","example":"0199c8d2-5b1e-7c3a-9f4e-2d6b8a1c3e5f"},"apiKeyId":{"type":["string","null"]},"surface":{"type":"string","description":"Where it came in: `rest`, `mcp`, `oauth`, `public`, `webhook` (or `rpc.dashboard` by id)."},"actor":{"type":["string","null"],"description":"The user behind an MCP or dashboard request."},"clientRequestId":{"type":["string","null"],"description":"The `X-Request-Id` your client sent, if any (ours is `requestId`)."},"method":{"type":"string"},"path":{"type":"string"},"query":{"type":["string","null"]},"operation":{"type":["string","null"]},"version":{"type":["string","null"]},"status":{"type":"integer"},"errorCode":{"type":["string","null"]},"durationMs":{"type":"integer"},"ip":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"idempotencyKey":{"type":["string","null"]},"body":{"description":"The request body, for requests that change something (capped; photos sent inline are left out)."},"hasPayload":{"type":"boolean","description":"The full request and response are on record (view them in the dashboard)."},"requestBytes":{"type":["integer","null"]},"responseBytes":{"type":["integer","null"]},"createdAt":{"type":"string"},"expiredAt":{"type":["string","null"],"description":"Past the retention period: the full record, IP address and user agent were removed."}},"required":["id","requestId","apiKeyId","surface","actor","clientRequestId","method","path","query","operation","version","status","errorCode","durationMs","ip","userAgent","idempotencyKey","hasPayload","requestBytes","responseBytes","createdAt","expiredAt"]}},"next":{"type":["string","null"]}},"required":["data","next"]},"CountriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"flag":{"type":"string"},"nomenclature":{"type":"string","enum":["us","ca","eu","gb","global","national"]},"nomenclatureLabel":{"type":"string"},"landedCost":{"type":"boolean","description":"Landed-cost calculation is supported for this destination."}},"required":["code","name","flag","nomenclature","nomenclatureLabel","landedCost"]}},"popularDestinations":{"type":"array","items":{"type":"string"}},"popularOrigins":{"type":"array","items":{"type":"string"}}},"required":["data","popularDestinations","popularOrigins"]},"PricingResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"credits":{"type":"integer"},"priceCents":{"type":"integer"},"currency":{"type":"string"},"featured":{"type":"boolean"},"unitPriceCents":{"type":"number"}},"required":["id","name","description","credits","priceCents","currency","featured","unitPriceCents"]}},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"credits":{"type":"integer"}},"required":["action","label","description","credits"]}},"freeTools":{"type":"object","properties":{"limit":{"type":"integer"},"windowDays":{"type":"integer"}},"required":["limit","windowDays"]},"signupBonusCredits":{"type":"integer"},"generatedAt":{"type":"string"}},"required":["packages","actions","freeTools","signupBonusCredits","generatedAt"]}},"required":["data"]}},"parameters":{}},"paths":{"/v1/classify":{"post":{"operationId":"classifyProduct","tags":["Classification"],"summary":"Classify a product","description":"Find the HS/HTS code for a product shipped to `destinationCountry`. Give a description, a product page URL, or both. Costs the mode’s credits (`GET /v1/classify/modes` lists the modes and their prices); a weak answer may escalate to another mode at no extra charge. Failed requests are refunded automatically.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyRequest"}}}},"responses":{"200":{"description":"The classification and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/batch":{"post":{"operationId":"classifyBatch","tags":["Classification"],"summary":"Classify up to 25 products","description":"Each item is a classify request, run four at a time and charged as one classification by its own mode; one failing (an unclassifiable description, insufficient credits) never stops the others and is refunded. With an `Idempotency-Key`, each item replays on its own.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyBatchRequest"}}}},"responses":{"200":{"description":"One result per item, in order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyBatchResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/regulator":{"post":{"operationId":"classifyRegulator","tags":["Classification"],"summary":"Find an agency product code","description":"The product code the destination’s import agency asks for, in that agency’s coding scheme: for the US, FDA’s import product code (e.g. `16AYN07`) for foods, drugs, devices, cosmetics and other goods FDA regulates. The answer names the `agency` and `scheme`, lists the code’s `parts` in order, and says whether the agency’s own check accepted it. Costs 1 credit; goods the agency doesn’t regulate are refused (`details.reason: \"not_regulated\"`, with `details.agency`) and refunded.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegulatorClassifyRequest"}}}},"responses":{"200":{"description":"The agency product code and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegulatorClassifyResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"No agency product codes for this destination yet (`unsupported_country`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/modes":{"get":{"operationId":"classifyModes","tags":["Classification"],"summary":"Classification modes","description":"The classification modes you can use (admin configures them: today `mini`, `pro` and `max`), with what each costs and reads, in general or for one destination: whether it reads a product photo, and a photo sent inline, and which mode runs when a request names none. A product page URL works in every mode. No API key needed.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO-2 destination: what each mode offers there (photos sent inline need border.bot’s own classifier).","example":"US"},"required":false,"description":"ISO-2 destination: what each mode offers there (photos sent inline need border.bot’s own classifier).","name":"destination","in":"query"}],"responses":{"200":{"description":"The modes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyModesResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/blocklist":{"get":{"operationId":"listBlockedCodes","tags":["Classification"],"summary":"Blocked codes","description":"Codes your classifications never suggest: a blocked line, or every line under a blocked heading, is skipped and the next best answers. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Your blocked codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodesResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addBlockedCode","tags":["Classification"],"summary":"Block a code","description":"Never suggest this code (or any line under it) again, for one destination or all. Adding a code that is already blocked updates its reason. Free; up to 5,000 codes.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodeRequest"}}}},"responses":{"200":{"description":"The blocked code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodeResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeBlockedCode","tags":["Classification"],"summary":"Unblock a code","description":"Lets classifications suggest the code again. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[\\d.\\s-]+$"},"required":true,"name":"code","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","pattern":"^[A-Za-z]{2}$"}],"default":"*"},"required":false,"name":"destination","in":"query"}],"responses":{"200":{"description":"Whether a blocked code was removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodeRemoveResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/blocklist/import":{"post":{"operationId":"importBlockedCodes","tags":["Classification"],"summary":"Block many codes","description":"Block a list of codes at once, or with `replace: true` make the list exactly these. All or nothing: an import that would pass 5,000 codes changes nothing. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodesImportRequest"}}}},"responses":{"200":{"description":"What the import added, updated and removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockedCodesImportResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify/feedback":{"post":{"operationId":"sendClassifyFeedback","tags":["Classification"],"summary":"Say whether a classification was right","description":"Tell border.bot a code was right, or what it should have been. Corrections are reviewed and become test cases the classifier must pass. With the classification’s `usageId`, sending again replaces your earlier verdict until it is reviewed. Free; up to 1,000 a day.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyFeedbackRequest"}}}},"responses":{"200":{"description":"The feedback was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyFeedbackResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `classify` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calculate":{"post":{"operationId":"calculateLandedCost","tags":["Landed cost"],"summary":"Calculate duties, taxes and landed cost","description":"Duties, taxes, fees and the landed cost for one HS code / origin / destination (the destinations `GET /countries` marks `landedCost`), or for a catalogue product by `sku` or `productId` (its approved code for the destination, origin, value, weight and content). Costs 1 credit. Unsupported destinations return 422 `unsupported_country` without charging.\n\nAPI key scope: `calculate`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"}}}},"responses":{"200":{"description":"The landed-cost breakdown and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Destination not supported (`unsupported_country`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calculate/shipment":{"post":{"operationId":"calculateShipment","tags":["Landed cost"],"summary":"Calculate a whole shipment","description":"Duties, taxes, fees and the landed cost of a cart or order to one destination: up to 50 lines (by their facts, or catalogue products by `sku`), freight and insurance shared out by value, one de minimis check, and per-entry fees charged once. Costs 1 credit per line. Priced on border.bot’s own data: a destination it doesn’t cover yet returns 422 `unsupported_country` without charging.\n\nAPI key scope: `calculate`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateShipmentRequest"}}}},"responses":{"200":{"description":"The shipment’s landed cost, line by line, and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateShipmentResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Destination not covered by border.bot’s own data (`unsupported_country`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calculate/stacking":{"post":{"operationId":"dutyStacking","tags":["Landed cost"],"summary":"Duty stacking","description":"Which duty lines apply to a code from an origin on a date, without a shipment: the base duty, then every additional measure (Section 301, 232, reciprocal…), which exemption codes remove which, the measures that depend on metal content or a claim, and the claim codes you could file. Up to 100 lines; free unless your pricing says otherwise. Answers from border.bot’s own data: a destination it doesn’t cover returns 422 `unsupported_country`.\n\nAPI key scope: `calculate`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackingRequest"}}}},"responses":{"200":{"description":"Each line’s stack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackingResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A destination border.bot’s own data doesn’t cover yet (`unsupported_country`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/extract":{"post":{"operationId":"extractProduct","tags":["Products"],"summary":"Read a product page","description":"Fetch a product page and extract its title, brand, price, materials, images and any stated country of origin.\n\nAPI key scope: `origin`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractProductRequest"}}}},"responses":{"200":{"description":"The extracted product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractProductResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/origin":{"post":{"operationId":"inferOrigin","tags":["Origin"],"summary":"Infer country of origin","description":"Where a product is made, as a probability per country with the evidence behind each: the product page’s data, “Made in …” text, a label in the photo, an AI estimate from brand, materials and price, the ship-from country and the barcode’s GS1 prefix. An AI estimate alone is never reported as high confidence. `needsReview` (with `reviewReason`) says when a person should confirm, because origin drives duty rates: below `reviewThreshold` (the request’s, else the workspace’s setting, else the platform default of 0.8), or when strong evidence disagrees.\n\nAPI key scope: `origin`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferOriginRequest"}}}},"responses":{"200":{"description":"The most likely origin, its probability, the alternates and the evidence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferOriginResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/origin/validate":{"post":{"operationId":"validateOrigin","tags":["Origin"],"summary":"Check a declared country of origin","description":"How believable a declared origin is, given everything else known about the product: the share of the evidence pointing elsewhere (`probabilityOfMisrepresentation`), a verdict, the likely origin, and the reasons in words. With no evidence either way the verdict is `unknown`, never a guess. `needsReview` flags it when the misrepresentation probability reaches `reviewThreshold` (the request’s, else the workspace’s setting, else the platform default of 0.3), or when there is no evidence.\n\nAPI key scope: `origin`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateOriginRequest"}}}},"responses":{"200":{"description":"The verdict on the declared origin, with reasons.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateOriginResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/origin/batch":{"post":{"operationId":"originBatch","tags":["Origin"],"summary":"Infer or check the origin of up to 50 products","description":"Each item is inferred, or validated when it has `declaredOrigin`. Items run four at a time, each charged as one origin call; one failing (bad photo, insufficient credits) never stops the others. With an `Idempotency-Key`, each item replays on its own.\n\nAPI key scope: `origin`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OriginBatchRequest"}}}},"responses":{"200":{"description":"One result per item, in order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OriginBatchResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/restrictions":{"post":{"operationId":"checkRestrictedGoods","tags":["Compliance"],"summary":"Check restricted goods","description":"Check items against the destination’s import prohibitions and restrictions and, when `originCountry` is given, the origin’s export rules (sanctions, agency requirements such as FDA or APHIS), plus your own rules (`/restrictions/rules`). It uses no credits and is limited to 10 checks per minute per workspace (up to 100 items each). Destinations without coverage return 422 `unsupported_country`.\n\nAPI key scope: `compliance`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionsRequest"}}}},"responses":{"200":{"description":"Matches per item (an empty `restrictions` list means nothing matched).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `compliance` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Restricted-goods checks are not available for this destination (`unsupported_country`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/restrictions/checks":{"get":{"operationId":"listRestrictionChecks","tags":["Compliance"],"summary":"Restricted-goods checks","description":"Your restricted-goods checks, newest first (up to 200): the evidence of what was checked, for which lane, by which engine, and what matched. Free.\n\nAPI key scope: `compliance`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Your checks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionChecksResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `compliance` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/restrictions/rules":{"get":{"operationId":"listRestrictionRules","tags":["Compliance"],"summary":"Your restricted-goods rules","description":"Rules your restricted-goods checks apply on top of border.bot’s (a compliance team’s own list). Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Your rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionRulesResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addRestrictionRule","tags":["Compliance"],"summary":"Add a restricted-goods rule","description":"A rule matched by HS code (and everything under it), by words in the item, or by origin, for one country or `*`. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionRuleRequest"}}}},"responses":{"200":{"description":"The rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionRuleResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeRestrictionRule","tags":["Compliance"],"summary":"Remove a restricted-goods rule","description":"Removes one of your rules by its id. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60","description":"The rule’s id."},"required":true,"description":"The rule’s id.","name":"id","in":"query"}],"responses":{"200":{"description":"Whether a rule was removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestrictionRuleRemoveResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/screen":{"post":{"operationId":"screenParty","tags":["Compliance"],"summary":"Screen a person or company","description":"Check a name (and a company) against denied-party lists: the US Consolidated Screening List (the SDN list, the Entity List, the Denied Persons List and the other export-screening lists of Commerce, State and the Treasury). Names and aliases match exactly or fuzzily (from 0.7); each check is kept as your evidence. Free, up to 60 a minute per workspace. A match is a lead to review, not a verdict.\n\nAPI key scope: `compliance`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenRequest"}}}},"responses":{"200":{"description":"The matches, best first, and the lists screened.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `compliance` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/screen/checks":{"get":{"operationId":"listScreeningChecks","tags":["Compliance"],"summary":"Your screening checks","description":"Every screening your workspace ran, newest first: the evidence that a name was screened, when, against which lists, and what matched. Free.\n\nAPI key scope: `compliance`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Your checks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningChecksResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `compliance` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/waybill":{"post":{"operationId":"createAirWaybill","tags":["Shipping documents"],"summary":"Generate an air waybill PDF","description":"A master or house air waybill on the IATA Resolution 600a face, with the Resolution 600b conditions of contract after each copy (`conditions`), as 3 originals or the full set of 8 (`copies`). Validated before charging: a wrong check digit or non-Latin text answers 400 without a charge. The PDF is an unsigned draft until the issuing carrier or its agent executes it, and acceptance by any airline, agent or authority is not guaranteed: use is subject to the Terms’ Shipping documents section (https://border.bot/legal/terms#shipping-documents). Costs 1 credit.\n\nAPI key scope: `documents`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirWaybillRequest"}}}},"responses":{"200":{"description":"The PDF (base64) and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirWaybillResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bulk/runs":{"post":{"operationId":"startBulkRun","tags":["Bulk"],"summary":"Start a bulk run","description":"Classify, calculate, find agency product codes or find and check countries of origin for up to 10,000 items in the background. Each item is charged when it runs (as its single request would be) and refunded if it fails; a run stops when your credits run out. Follow it with `GET /bulk/status`, read its answers with `GET /bulk/results`.\n\nAPI key scope: `bulk`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunRequest"}}}},"responses":{"200":{"description":"The run, queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listBulkRuns","tags":["Bulk"],"summary":"Your bulk runs","description":"Your workspace’s bulk runs, newest first.\n\nAPI key scope: `bulk`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelBulkRun","tags":["Bulk"],"summary":"Cancel a bulk run","description":"Stops a run after the chunk it is working on. Items already done stay done (and charged).\n\nAPI key scope: `bulk`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":5,"maxLength":60},"required":true,"name":"id","in":"query"}],"responses":{"200":{"description":"The run, cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bulk/status":{"get":{"operationId":"bulkRunStatus","tags":["Bulk"],"summary":"A bulk run’s progress","description":"How far a run has got: items done, succeeded and failed, and the credits charged so far.\n\nAPI key scope: `bulk`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":5,"maxLength":60},"required":true,"name":"id","in":"query"}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bulk/results":{"get":{"operationId":"bulkResults","tags":["Bulk"],"summary":"A bulk run’s results","description":"The answers so far, in item order, up to 1,000 at a time (`next` is the following page’s `offset`). Each is exactly what its single endpoint returns, or the error it failed with.\n\nAPI key scope: `bulk`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":5,"maxLength":60},"required":true,"name":"id","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkResultsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `bulk` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products":{"get":{"operationId":"listCatalogProducts","tags":["Catalogue"],"summary":"List products","description":"Your catalogue, newest change first, a page at a time (`cursor`). Filter by words or a SKU prefix (`q`), status, market, products missing an approved code for a market (`missingCodeFor`), products with a code waiting for review (`needsReview`), origin, or source kind. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["draft","active","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"market","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"missingCodeFor","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"required":false,"name":"needsReview","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"origin","in":"query"},{"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"required":false,"name":"source","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCatalogProduct","tags":["Catalogue"],"summary":"Create a product","description":"A product with its items (each SKU unique in your catalogue), content components, source and any codes you already hold. Codes are checked against the vocabularies (`GET /catalog/terms`). Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductCreate"}}}},"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A SKU is already used by another product (`conflict`, `details.reason: \"sku_taken\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}":{"get":{"operationId":"getCatalogProduct","tags":["Catalogue"],"summary":"Get a product","description":"A product with its items, content components, sources and current codes per market. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product in your catalogue (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCatalogProduct","tags":["Catalogue"],"summary":"Update a product","description":"Changes the fields given, its items (by id or SKU, others added) and its content list. Every change is kept in the product’s history with its actor. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductUpdate"}}}},"responses":{"200":{"description":"The product as it is now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product in your catalogue (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A SKU is taken, or the product is archived (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/archive":{"post":{"operationId":"archiveCatalogProduct","tags":["Catalogue"],"summary":"Archive a product","description":"Retires a product and its items: out of lists and SKU lookups (its SKUs become free), kept with its sources, content, codes and history. Nothing in the catalogue is ever deleted. Restore it by updating its `status`. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"responses":{"200":{"description":"The archived product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProductResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/history":{"get":{"operationId":"catalogProductHistory","tags":["Catalogue"],"summary":"A product’s history","description":"Every change to the product and its items, sources, content and codes, newest first: who, when, and the values before and after. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"responses":{"200":{"description":"The changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogHistoryResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/classifications":{"get":{"operationId":"listCatalogClassifications","tags":["Catalogue"],"summary":"A product’s codes","description":"Every code the product has had, per market, newest first: suggested, approved, rejected and superseded. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"responses":{"200":{"description":"The codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCatalogClassification","tags":["Catalogue"],"summary":"Add a code","description":"A code you hold for a market: a suggestion to review, or approved at once with `approve`. Markets in a customs union share its code (Germany and France the EU’s). Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationCreate"}}}},"responses":{"200":{"description":"The code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/classifications/suggest":{"post":{"operationId":"suggestCatalogClassifications","tags":["Catalogue"],"summary":"Suggest codes","description":"Classifies the product for each market from its title, description, materials, page and photo, and keeps each answer as a suggestion to review (approve it to quote with it). Each market is charged like `POST /classify` and refunded if it fails.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"},{"schema":{"type":"string","maxLength":200,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","example":"3f0d9b1e-6c1a-4f50-9a55-1d2f8c1b7e44"},"required":false,"description":"Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationSuggest"}}}},"responses":{"200":{"description":"A suggestion (or the error) per market, and the credits charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSuggestResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (`insufficient_credits`). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The engine failed (`upstream_error`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The engine timed out (`upstream_timeout`). The credits are refunded automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/classifications/{classificationId}/approve":{"post":{"operationId":"approveCatalogClassification","tags":["Catalogue"],"summary":"Approve a code","description":"Approves a suggestion: it becomes the code quotes use for its schedule, and the code it replaces is superseded (kept, with the dates it applied). Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The classification’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The classification’s id.","name":"classificationId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationReview"}}}},"responses":{"200":{"description":"The approved code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products/{id}/classifications/{classificationId}/reject":{"post":{"operationId":"rejectCatalogClassification","tags":["Catalogue"],"summary":"Reject a code","description":"Rejects a suggestion (kept, with your note). Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The product’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The product’s id.","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"The classification’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The classification’s id.","name":"classificationId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationReview"}}}},"responses":{"200":{"description":"The rejected code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogClassificationResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/classify":{"post":{"operationId":"classifyCatalog","tags":["Catalogue"],"summary":"Classify many products","description":"A bulk run classifying products (by id or by a filter) for markets, its answers kept as suggestions. Follow it with `GET /bulk/status`; its items are charged like `POST /classify` as they run.\n\nAPI key scope: `classify`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogBulkClassifyRequest"}}}},"responses":{"200":{"description":"The bulk run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRunResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `classify` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Three bulk runs are already going (`rate_limited`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/imports":{"post":{"operationId":"importCatalog","tags":["Catalogue"],"summary":"Import a CSV file","description":"Imports (or, by default, checks: `dryRun`) a CSV file of up to 2,000 rows: columns mapped to fields, each row checked and upserted by its `external_id` or `sku`, errors reported per row. Importing the same file again changes nothing. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportRequest"}}}},"responses":{"200":{"description":"What the import did (or would do), with the errors per row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listCatalogImports","tags":["Catalogue"],"summary":"Your imports","description":"Your CSV imports and dry runs, newest first, with their counts and errors. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Your imports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportsResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/imports/{id}":{"get":{"operationId":"getCatalogImport","tags":["Catalogue"],"summary":"An import","description":"One import’s status, counts and errors per row. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"The import’s id.","example":"0199c3a2-7b4e-7d21-9f3a-2c5e8b1d4f60"},"required":true,"description":"The import’s id.","name":"id","in":"path"}],"responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportRecordResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/exports":{"get":{"operationId":"exportCatalog","tags":["Catalogue"],"summary":"Export as CSV","description":"Your catalogue (or the products a filter finds, up to 10,000) as CSV: one row per item, every field, and the approved code per market. It imports again as it is. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["draft","active","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"market","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"missingCodeFor","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"required":false,"name":"needsReview","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"required":false,"name":"origin","in":"query"},{"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"required":false,"name":"source","in":"query"}],"responses":{"200":{"description":"The CSV text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogExportResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/sync":{"post":{"operationId":"syncCatalog","tags":["Catalogue"],"summary":"Sync records from a source","description":"For connectors: a page of up to 250 records from a store, marketplace, feed or ERP (a source kind from `GET /catalog/sources`), upserted by the source’s own key. Unchanged records only update their sync time. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncRequest"}}}},"responses":{"200":{"description":"What each record did.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/sync/codes":{"get":{"operationId":"catalogSyncCodes","tags":["Catalogue"],"summary":"Approved codes to write back","description":"For connectors: the approved codes (and origins) of a connection’s records, approved after `since`, to write back to the source in its own fields. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"required":true,"name":"sourceKind","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":300},"required":true,"name":"connection","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only codes approved after this time."},"required":false,"description":"Only codes approved after this time.","name":"since","in":"query"}],"responses":{"200":{"description":"One entry per record and approved code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncCodesResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/terms":{"get":{"operationId":"listCatalogTerms","tags":["Catalogue"],"summary":"Catalogue vocabularies","description":"The harmonised codes catalogue fields take: materials, material origins (by stage), attributes (dangerous goods, restricted), categories, origin bases and quantity units. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["material","material_origin","attribute","category","origin_basis","quantity_unit"]},"required":false,"name":"vocabulary","in":"query"}],"responses":{"200":{"description":"The codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogTermsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/sources":{"get":{"operationId":"listCatalogSources","tags":["Catalogue"],"summary":"Source kinds","description":"Where products can come from (the dashboard, files, the API, commerce platforms, marketplaces, feeds), each with the identifiers its records carry. Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The source kinds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSourceKindsResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/markets":{"get":{"operationId":"getCatalogMarkets","tags":["Catalogue"],"summary":"Default target markets","description":"The markets a product without its own ships to (what bulk classification and filters use). Free.\n\nAPI key scope: `catalog`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The markets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogMarketsResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `catalog` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"setCatalogMarkets","tags":["Catalogue"],"summary":"Set default target markets","description":"Replaces the workspace’s default markets. Free.\n\nAPI key scope: `settings`.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogMarketsRequest"}}}},"responses":{"200":{"description":"The markets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogMarketsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `settings` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"operationId":"getWorkspace","tags":["Account"],"summary":"Who am I","description":"The workspace and API key behind this request, with the current credit balance.\n\nAny API key may call this.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The calling workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credits":{"get":{"operationId":"getCredits","tags":["Account"],"summary":"Credit balance","description":"Current balance, lifetime totals and the 20 most recent ledger entries (purchases, usage, refunds).\n\nAPI key scope: `account`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Balance and recent ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `account` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"listUsage","tags":["Account"],"summary":"Usage history","description":"Every billable request made by the workspace (dashboard, API and MCP), newest first, with cursor pagination.\n\nAPI key scope: `account`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Page size (1–100).","example":25},"required":false,"description":"Page size (1–100).","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Opaque cursor from a previous page."},"required":false,"description":"Opaque cursor from a previous page.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["classify","classify_max","classify_regulator","calculate","calculate_stacking","extract_product","infer_origin","air_waybill"],"description":"Only this action."},"required":false,"description":"Only this action.","name":"action","in":"query"}],"responses":{"200":{"description":"A page of usage events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `account` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/requests":{"get":{"operationId":"listApiRequests","tags":["Account"],"summary":"Request log","description":"Every request made for your workspace (API keys and MCP) within the retention period (400 days by default), newest first: what it called, how it ended (status and error code), how long it took, and, for requests that change something, the body (kept for the first 30 days). Quote a request's `requestId` (its `X-Request-Id`) to support.\n\nAPI key scope: `account`.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1–100)."},"required":false,"description":"Page size (1–100).","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":60,"description":"The `next` of the previous page."},"required":false,"description":"The `next` of the previous page.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"`true`: only requests that failed (status 400 and up)."},"required":false,"description":"`true`: only requests that failed (status 400 and up).","name":"failed","in":"query"},{"schema":{"type":"string","maxLength":100,"description":"One request, by the `X-Request-Id` its response carried (a UUID; older requests keep their `req_…` ids, which still match).","example":"0199c8d2-5b1e-7c3a-9f4e-2d6b8a1c3e5f"},"required":false,"description":"One request, by the `X-Request-Id` its response carried (a UUID; older requests keep their `req_…` ids, which still match).","name":"requestId","in":"query"}],"responses":{"200":{"description":"A page of requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRequestsResponse"}}}},"400":{"description":"Invalid input (`invalid_input`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key doesn’t have the `account` scope (`forbidden`, `details.reason: \"missing_scope\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/countries":{"get":{"operationId":"listCountries","tags":["Reference"],"summary":"Supported countries","description":"All ISO countries with the nomenclature classification answers in (a 10-digit national tariff where border.bot has one, 6-digit HS elsewhere) and whether landed-cost calculation is supported. No API key needed.","responses":{"200":{"description":"Country coverage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pricing":{"get":{"operationId":"getPricing","tags":["Reference"],"summary":"Pricing","description":"Credits per action, credit packs and free-tool limits. No API key needed.","responses":{"200":{"description":"Current pricing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"429":{"description":"Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error (`internal`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}