{"openapi":"3.1.0","info":{"title":"border.bot API (v1)","version":"1.3.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://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` 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://api.border.bot/mcp` (OAuth, no API key). Setup guides: https://border.bot/mcp","contact":{"name":"border.bot support","email":"support@border.bot","url":"https://border.bot"}},"servers":[{"url":"https://api.border.bot","description":"Production"}],"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://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"]}},"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"]}},"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","description":"Echoes the `X-Request-Id` response header."}},"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":"req_01j9x3k8f2q7m4t6v0w8y5z1ab"}},"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"]},"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]},"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)."},"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","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":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"affects":{"type":"string"}},"required":["code","name","affects"]}},"applied":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]}},"required":["code","name"]}}},"required":["available","applied"]}},"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"]},"collectedBy":{"type":"string","enum":["border","seller"],"description":"Taxes: paid at the border, 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":"Zeroed by this exemption code."}},"required":["kind","name","type","code","rate","amount","agreement"]},"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"],"default":"courier","description":"How the parcel travels: `courier` (express carriers, default) or `postal` — affects de minimis and channel-specific regimes."},"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`."},"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`."},"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS/HTS code (4–10 digits; dots and spaces are ignored).","example":"6109.10.00.12"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country of origin — drives preferential rates and additional duties (e.g. Section 301). ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"value":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Total customs value of the goods in the shipment (unit price × quantity), in `currency`, excluding shipping.","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."},"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"]}},"required":["destinationCountry","hsCode","originCountry","value"],"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"]},"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]},"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)."},"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","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":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"affects":{"type":"string"}},"required":["code","name","affects"]}},"applied":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]}},"required":["code","name"]}}},"required":["available","applied"]},"availableExemptions":{"type":"array","items":{"type":"string"},"description":"Exemption/claim codes the shipper may be able to file."}},"required":["index","hsCode","hsCodeFormatted","originCountry","customsValue","duty","rateFound","tradeAgreement","lines","regulatory","options","claims","availableExemptions"]},"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"],"default":"courier","description":"How the parcel travels: `courier` (express carriers, default) or `postal` — affects de minimis and channel-specific regimes."},"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`."},"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`."},"items":{"type":"array","items":{"type":"object","properties":{"hsCode":{"type":"string","pattern":"^[\\d.\\s-]+$","description":"HS/HTS code (4–10 digits; dots and spaces are ignored).","example":"6109.10.00.12"},"originCountry":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country of origin — drives preferential rates and additional duties (e.g. Section 301). ISO 3166-1 alpha-2, case-insensitive.","example":"CN"},"value":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"Total customs value of the goods in the shipment (unit price × quantity), in `currency`, excluding shipping.","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."},"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"]}},"required":["hsCode","originCountry","value"]},"minItems":1,"maxItems":50,"description":"The shipment’s lines (up to 50), each with its code, origin and line value. 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."}},"required":["kind","type","name","code","rate","exemptedBy"]}},"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":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"affects":{"type":"string"}},"required":["code","name","affects"]},"description":"Claim codes the importer could file to remove a line."},"notes":{"type":"array","items":{"type":"string"}}},"required":["index","ref","hsCode","hsCodeFormatted","originCountry","destinationCountry","schedule","entryDate","rateFound","lines","conditional","claimable","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"]},"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"],"default":"courier"},"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"]},"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"},"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},"conditions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,19}$"},"maxItems":10}},"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"]},"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","bulk","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"]},"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"},"apiKeyId":{"type":["string","null"]},"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)."},"createdAt":{"type":"string"}},"required":["id","requestId","apiKeyId","method","path","query","operation","version","status","errorCode","durationMs","ip","userAgent","idempotencyKey","createdAt"]}},"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`). 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, 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/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/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"],"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 your API keys made in the last 30 days, newest first: what it called, how it ended (status and error code), how long it took, and, for requests that change something, the body. 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."},"required":false,"description":"One request, by the `X-Request-Id` its response carried.","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":{}}