API reference

Base URL https://staging-api.border.bot, version 1.6.0. Machine-readable: OpenAPI 3.1. Try requests in the interactive reference.

Classify products to HS/HTS codes and calculate duties, taxes, fees and landed cost for cross-border parcels.

Versions: This is v1, the current version. Within a version, changes are only additive (new endpoints, new optional fields, new enum values). Breaking changes ship as a new version; every version and its dates: https://staging-api.border.bot/versions

Authentication: send a workspace API key: Authorization: Bearer bb_live_…. Create keys in the dashboard.

Credits: billable requests use prepaid credits (see GET /v1/pricing). Prices are set server-side; failed requests are refunded automatically. Every response includes X-Request-Id (a UUID; quote it to support) and API-Version; billable responses include X-Credits-Charged and X-Credits-Remaining.

Retries: send an Idempotency-Key header on POST requests; repeating it returns the original result without charging again.

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.

Errors: { "error": { "code", "message", "details"? } } with a stable code (e.g. 402 insufficient_credits, 429 rate_limited).

MCP: use border.bot from Claude, ChatGPT, Codex, Cursor, VS Code and other MCP clients at https://staging-mcp.border.bot/mcp (OAuth, no API key). Setup guides: https://staging.border.bot/mcp

Classification#

HS/HTS codes.

• Classify a product: POST /v1/classify
• Classify up to 25 products: POST /v1/classify/batch
• Find an agency product code: POST /v1/classify/regulator
• Classification modes: GET /v1/classify/modes
• Blocked codes: GET /v1/classify/blocklist
• Block a code: POST /v1/classify/blocklist
• Unblock a code: DELETE /v1/classify/blocklist
• Block many codes: POST /v1/classify/blocklist/import
• Say whether a classification was right: POST /v1/classify/feedback

Landed cost#

Duties, taxes and fees.

• Calculate duties, taxes and landed cost: POST /v1/calculate
• Calculate a whole shipment: POST /v1/calculate/shipment
• Duty stacking: POST /v1/calculate/stacking

Products#

Product pages and country of origin.

• Read a product page: POST /v1/products/extract

Compliance#

Restricted and prohibited goods (free).

• Check restricted goods: POST /v1/restrictions
• Restricted-goods checks: GET /v1/restrictions/checks
• Your restricted-goods rules: GET /v1/restrictions/rules
• Add a restricted-goods rule: POST /v1/restrictions/rules
• Remove a restricted-goods rule: DELETE /v1/restrictions/rules
• Screen a person or company: POST /v1/screen
• Your screening checks: GET /v1/screen/checks

Account#

Your workspace, credits and usage.

• Who am I: GET /v1/me
• Credit balance: GET /v1/credits
• Usage history: GET /v1/usage
• Request log: GET /v1/requests

Reference#

Public reference data (no key needed).

• Supported countries: GET /v1/countries
• Pricing: GET /v1/pricing

Origin#

• Infer country of origin: POST /v1/origin
• Check a declared country of origin: POST /v1/origin/validate
• Infer or check the origin of up to 50 products: POST /v1/origin/batch

Shipping documents#

• Generate an air waybill PDF: POST /v1/documents/waybill

Bulk#

• Your bulk runs: GET /v1/bulk/runs
• Start a bulk run: POST /v1/bulk/runs
• Cancel a bulk run: DELETE /v1/bulk/runs
• A bulk run’s progress: GET /v1/bulk/status
• A bulk run’s results: GET /v1/bulk/results

Catalogue#

• List products: GET /v1/catalog/products
• Create a product: POST /v1/catalog/products
• Get a product: GET /v1/catalog/products/{id}
• Update a product: PATCH /v1/catalog/products/{id}
• Archive a product: POST /v1/catalog/products/{id}/archive
• A product’s history: GET /v1/catalog/products/{id}/history
• A product’s codes: GET /v1/catalog/products/{id}/classifications
• Add a code: POST /v1/catalog/products/{id}/classifications
• Suggest codes: POST /v1/catalog/products/{id}/classifications/suggest
• Approve a code: POST /v1/catalog/products/{id}/classifications/{classificationId}/approve
• Reject a code: POST /v1/catalog/products/{id}/classifications/{classificationId}/reject
• Classify many products: POST /v1/catalog/classify
• Your imports: GET /v1/catalog/imports
• Import a CSV file: POST /v1/catalog/imports
• An import: GET /v1/catalog/imports/{id}
• Export as CSV: GET /v1/catalog/exports
• Sync records from a source: POST /v1/catalog/sync
• Approved codes to write back: GET /v1/catalog/sync/codes
• Catalogue vocabularies: GET /v1/catalog/terms
• Source kinds: GET /v1/catalog/sources
• Default target markets: GET /v1/catalog/markets
• Set default target markets: POST /v1/catalog/markets