HS Code Endpoints

HS Code Endpoints

The same classification engine behind the in-app Find HS Code dialog, exposed over the API. All endpoints require authentication.

Search

GET /hs-codes/search?q={description}&topK={n}

Semantic search over 5,600+ WCO 6-digit subheadings. q is required; topK ranges 1-20 (default 10).

curl "https://api.cargolint.com/api/v1/hs-codes/search?q=children%27s%20cotton%20hooded%20sweatshirts&topK=10" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Returns ranked candidates with code, description, and confidence.

AI Search

GET /hs-codes/search-llm?q={description}&topK={n}

LLM-assisted classification - higher accuracy on ambiguous trade descriptions, plus the “did you mean” tariff-vocabulary rephrasing. Counts against your plan’s daily AI search allowance; returns 503 Service Unavailable when the AI service is down (fall back to /search).

Refine with Attributes

POST /hs-codes/suggest
POST /hs-codes/reclassify-partial

These power the progressive-accuracy flow: suggest returns candidates plus the attribute questions worth answering (material, article type, and so on, each with an expected accuracy lift); reclassify-partial re-ranks with the attribute answers applied. Send the original query and the answered attributes in the body.

Browse and Lookup

GET /hs-codes/browse           - walk the HS hierarchy (chapters → headings → subheadings)
GET /hs-codes/lookup/{code}    - resolve a specific code to its description and metadata
GET /hs-codes/versions         - supported HS nomenclature versions

CargoLint maintains HS 2022 as the primary version with fallback to HS 2017 for codes that only exist in the older edition.

Important: HS code suggestions are informational only. Verify classifications with a licensed customs broker before using them in a regulatory filing.

What’s next

• HS Code Classification - How the recommendation model works
• Working with HS Codes - The in-app Find HS Code flow