Skip to the content

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 four import markets, the United States (HTS), the European Union (CN and TARIC), Vietnam (the Vietnamese import tariff, AHTN) and Japan (Japan's Tariff Schedule), 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), then ask who the key belongs to:

curl https://htspilot.com/api/auth/me \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
{
  "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):

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):

{
  "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:

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).

First the rules that hold for every call:

Then one page per resource, each with its object and its operations: Lookups, Review, Batches, Catalog, Tariff data, Usage, Webhook endpoints, Reports and System.

Two more things sit next to these pages. The API explorer sends requests to the live API with your key, from your browser. The OpenAPI specification 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.