border.bot
Docs menu

API reference

API reference

Infer country of origin

POST https://api.border.bot/v1/origin

Requires an API key (Authorization: Bearer bb_live_…).

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.

API key scope: origin.

Headers#

Name Type Required Description
idempotency-key string no Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).

Request body (JSON)#

Name Type Required Description
productUrl string no Product page URL: its structured data and “Made in …” text are read first.
imageUrl string no 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 string no Product description.
title string no Product name.
brand string no Brand.
sku string no Your SKU (kept with the result).
gtin string no Barcode (GTIN, UPC, EAN). Its GS1 prefix shows where the brand registered: a weak hint, never proof.
material string no Main materials.
categories string[] no Category path, broadest first.
price number no Selling price, in currency.
currency string no ISO 4217 currency of price.
shipFromCountry string no Country the goods ship from (often, not always, where they are made). ISO 3166-1 alpha-2, case-insensitive.
reviewThreshold number no 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).

Responses#

  • 200: The most likely origin, its probability, the alternates and the evidence. (InferOriginResponse)
  • 400: Invalid input (invalid_input). (Error)
  • 401: Missing, invalid, revoked or expired API key (unauthorized). (Error)
  • 402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
  • 403: Workspace suspended, action disabled, or the key lacks the scope (org_suspended, action_disabled, forbidden). (Error)
  • 409: A request with this Idempotency-Key is still in progress (conflict). (Error)
  • 429: 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. (Error)
  • 500: Unexpected error (internal). (Error)
  • 502: The engine failed (upstream_error). The credits are refunded automatically. (Error)
  • 504: The engine timed out (upstream_timeout). The credits are refunded automatically. (Error)

Example#

bash
curl -X POST 'https://api.border.bot/v1/origin' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Organic cotton tee","brand":"Example","productUrl":"https://shop.example.com/products/organic-tee"}'