# Quickstart

> Create a border.bot API key, classify a product, then calculate its landed cost, with curl.

Source: https://border.bot/docs/quickstart
Last updated: 2026-10-09

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.


## 1. Create an API key

Sign in to the [dashboard](https://app.border.bot/developers?tab=keys) and open **Developers → API keys**. Create a key for your workspace. It starts with `bb_live_` and is shown once, so put it in your secrets manager straight away.

```bash
export BORDERBOT_API_KEY=bb_live_...
```

Check the key works. `GET /v1/me` is free and returns the workspace, the key's scopes and the credit balance:

```bash
curl https://api.border.bot/v1/me \
  -H "Authorization: Bearer $BORDERBOT_API_KEY"
```

## 2. Classify a product

Send a description or a product URL with the destination country. Add the origin if you know it.

```bash
curl -X POST https://api.border.bot/v1/classify \
  -H "Authorization: Bearer $BORDERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"description":"Men'\''s cotton crew-neck t-shirt, knitted","destinationCountry":"US","originCountry":"PT"}'
```

The response has the code in the destination's format, the official description at each level, a confidence score, the reasoning and alternatives. The `X-Credits-Charged` and `X-Credits-Remaining` headers say what the call cost.

## 3. Calculate landed cost

Pass the code, the origin and destination, the goods value and the shipping cost:

```bash
curl -X POST https://api.border.bot/v1/calculate \
  -H "Authorization: Bearer $BORDERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"hsCode":"6109.10.00.12","originCountry":"PT","destinationCountry":"US","value":120,"currency":"USD","shippingCost":15}'
```

You get every duty, tax and fee line with its legal basis and the total landed cost. The [reference for this endpoint](https://border.bot/docs/api/calculate-landed-cost) lists every field, including shipping terms, preferential rates and seller-collected taxes.

## Next

- [Authentication](https://border.bot/docs/authentication): scopes and key handling.
- [Credits and retries](https://border.bot/docs/credits): what each call costs and how to retry without paying twice.
- [Errors](https://border.bot/docs/errors) and [rate limits](https://border.bot/docs/rate-limits).
- [API reference](https://border.bot/docs/api): every endpoint.