Start a bulk run

POST https://staging-api.border.bot/v1/bulk/runs

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

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.

API key scope: bulk.

Request body (JSON)#

Responses#

• 200: The run, queued. (BulkRunResponse)
• 400: Invalid input (invalid_input). (Error)
• 401: Missing, invalid, revoked or expired API key (unauthorized). (Error)
• 403: The API key doesn’t have the bulk scope (forbidden, details.reason: "missing_scope"). (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)

Example#

curl -X POST 'https://staging-api.border.bot/v1/bulk/runs' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"classify","reference":"catalogue-2026-10","items":[{"description":"Men'\''s cotton t-shirt","destinationCountry":"US"},{"description":"Stainless steel water bottle, 750 ml","destinationCountry":"GB"}]}'