# border.bot API

> HS/HTS code classification and landed cost (duties, taxes and fees) for cross-border parcels, as a REST API and a remote MCP server.

Authenticate REST calls with a workspace API key (`Authorization: Bearer bb_live_...`), created in the border.bot dashboard. Billable calls use prepaid credits; failed calls are refunded automatically. MCP clients sign in with OAuth instead of an API key.

## When to use border.bot

- Classify a product to the tariff code its destination uses (US HTS, EU CN, UK, Canada, or the 6-digit HS elsewhere) from a description or a product page URL: REST `POST /v1/classify` (up to 25 at once: `POST /v1/classify/batch`), MCP `classify_product` / `classify_products`
- Landed cost of a parcel: duties, taxes and fees for an HS code, origin, destination and value: REST `POST /v1/calculate` (a whole shipment: `POST /v1/calculate/shipment`), MCP `calculate_landed_cost` / `calculate_cart`
- Country of origin: infer where a product is made, with the evidence, or check a declared origin: REST `POST /v1/origin`, `POST /v1/origin/validate`, `POST /v1/origin/batch`, MCP `infer_country_of_origin` / `check_country_of_origin`
- Restricted and prohibited goods for a destination (and the origin's export rules), free: REST `POST /v1/restrictions`, MCP `check_restricted_goods`
- Denied-party screening of a buyer or consignee against the US Consolidated Screening List, free: REST `POST /v1/screen`, MCP `screen_party`
- Bulk runs: classify, calculate or check origin for up to 10,000 items in the background: REST `POST /v1/bulk/runs`, then `GET /v1/bulk/status` and `GET /v1/bulk/results`

How to call: an agent running code calls the REST API at https://api.border.bot with a workspace API key; an agent inside an MCP client (Claude, ChatGPT, Cursor, ...) connects to the MCP server at https://api.border.bot/mcp and signs in with OAuth, no API key. Supported destinations: `GET /v1/countries`; prices: `GET /v1/pricing` (both public).

Not for: legal advice or binding rulings (results are guidance for customs declarations; review low-confidence answers), and not for booking freight, buying postage or filing customs entries.

- [Docs and guides](https://border.bot/docs): quickstart, endpoint reference and MCP setup
- [Authentication](https://border.bot/auth.md): API keys and OAuth for agents

## Reference

- [API reference (Markdown)](https://api.border.bot/v1/docs.md): every endpoint of the current version (v1) with parameters, responses and curl examples
- [OpenAPI 3.1 document](https://api.border.bot/v1/openapi.json): machine-readable description of the REST API
- [API versions](https://api.border.bot/versions): every version, its status, deprecation and sunset dates, and what changed
- [API catalog](https://api.border.bot/.well-known/api-catalog): RFC 9727 links to the documents above

## MCP

- [MCP server](https://api.border.bot/mcp): Streamable HTTP, OAuth 2.1 (dynamic client registration and client ID metadata documents)
- [Server card](https://api.border.bot/mcp/server-card): connection details for MCP clients
- [Tools](https://api.border.bot/mcp/tools.json): every MCP tool with its input schema and annotations
- [Setup guides for 34 MCP clients](https://border.bot/mcp.md): Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, Gemini CLI and more

## Optional

- [border.bot website](https://border.bot/llms.txt): product, pricing, free tools and guides