> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

> This page describes the API as of 2026-10-09. The service runs the latest version: https://docs.htspilot.com/index.md

# Introduction

> What the HTS Pilot API does, its base URL, a first request that works, and how these pages are organised.

The HTS Pilot API proposes tariff codes from a product description for three import markets, the United States (HTS),
the European Union (CN and TARIC) and Vietnam (the Vietnamese import tariff, AHTN), with the reasons, the
sources it used and a review queue. It covers single lookups, batch files, a SKU
catalog that can be kept in step with an ERP or PIM, tariff data and duty estimates, usage, and the reviewer's
decision on a lookup.

A result is a suggestion for reference. It is not a classification decision by a customs authority: the declarant
and the authority decide. Duty and landed cost figures are estimates.

## Base URL

```
https://htspilot.com/api
```

Every path in these pages starts with `/api`. Requests and responses are JSON (`Content-Type: application/json`)
unless an operation says otherwise: a batch is uploaded as `multipart/form-data`, and the templates, the batch
results and the credit ledger are downloaded as Excel or CSV files. Use HTTPS.

## A first request

Create an API key in the application ([Authentication](/v/2026-10-09/authentication.md)), then ask who the key belongs to:

```bash
curl https://htspilot.com/api/auth/me \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

```json
{
  "id": "a7ba4a2440c7422fb695a1fd80d65ce5",
  "name": "Administrator (API: Documentation examples)",
  "email": "admin@example.com",
  "role": "admin",
  "role_label": "Admin",
  "via": "api_key",
  "avatar_url": "",
  "credits": 0,
  "unlimited": true
}
```

`via` is `api_key` when the request was recognised by its key. `GET /api/health` needs no key and tells whether
the service is up.

## Classify a product

A lookup runs in the background. Create it, then read it until it is finished
([Asynchronous work](/v/2026-10-09/asynchronous-work.md)):

```bash
curl -X POST https://htspilot.com/api/classify \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"description": "Knitted cotton T-shirt for men, short sleeves, crew neck", "origin": "VN", "market": "US"}'
```

The answer is `202 Accepted` with the lookup, its `status` still `queued` (shortened here: the full object is
described in [Lookups](/v/2026-10-09/lookups.md)):

```json
{
  "id": "f4a2251d5dc941ec99f7d459e05082a5",
  "created_at": "2026-10-03T19:48:02.932457",
  "kind": "single",
  "market": "US",
  "dataset_version": "2026-SAMPLE",
  "status": "queued",
  "recommended_code": null,
  "confidence": 0.0,
  "language": "en",
  "progress": null
}
```

Then read it:

```bash
curl https://htspilot.com/api/lookups/f4a2251d5dc941ec99f7d459e05082a5 \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

When `status` is no longer `queued` or `processing`, `recommended_code` holds the proposed code and `result` the
candidates, the reasons, the sources and what is still missing. A lookup can be charged to the account
([Rate limits and quotas](/v/2026-10-09/rate-limits.md#credits)).

## How these pages are organised

First the rules that hold for every call:

- [Authentication](/v/2026-10-09/authentication.md): API keys, roles, `401` and `403`.
- [Errors](/v/2026-10-09/errors.md): the error body and the status codes in use.
- [Request identifiers](/v/2026-10-09/request-identifiers.md)
- [Rate limits and quotas](/v/2026-10-09/rate-limits.md): credits, plan limits and the few per-minute limits.
- [Pagination](/v/2026-10-09/pagination.md)
- [Languages](/v/2026-10-09/languages.md): `Accept-Language` and the answer language of a lookup.
- [Versioning and changes](/v/2026-10-09/versioning.md)
- [Asynchronous work](/v/2026-10-09/asynchronous-work.md): `202`, states and polling.
- [Webhooks](/v/2026-10-09/webhooks.md): events, payloads, signatures, retries.

Then one page per resource, each with its object and its operations:
[Lookups](/v/2026-10-09/lookups.md), [Review](/v/2026-10-09/review.md), [Batches](/v/2026-10-09/batches.md), [Catalog](/v/2026-10-09/catalog.md),
[Tariff data](/v/2026-10-09/tariff-data.md), [Usage](/v/2026-10-09/usage.md), [Webhook endpoints](/v/2026-10-09/webhook-endpoints.md),
[Reports](/v/2026-10-09/reports.md) and [System](/v/2026-10-09/system.md).

Two more things sit next to these pages. The [API explorer](/explorer/) sends requests to the live API with your
key, from your browser. The [OpenAPI specification](/openapi.json) is the machine-readable description of every
operation, with its parameters and schemas.

## About the examples

The example answers in these pages were captured from a local run of the service, not from production. The US
answers use a small sample tariff (its version is labelled `2026-SAMPLE`), so codes, rates and texts in them
illustrate the shape of an answer and are not tariff information. Figures such as credit balances are
illustrative. A long list in an example is cut to its first two entries. Ids are 32 hexadecimal
characters for lookups, batches, datasets and webhooks, and whole numbers for SKUs, alerts and webhook
deliveries.
