API Documentation

HS Code Lookup

GET /api/hs-code/:code

Returns details for a specific HS code including description, hierarchy, regulatory flags, and children codes.

GET /api/hs-code/847130

Response:
{
  "code": "847130",
  "level": 6,
  "description": "Portable automatic data processing machines",
  "section": "XVI",
  "parent": "8471",
  "slug": "portable-automatic-data-processing-machines",
  "is_commodity": false,
  "flags": { "eudr": false, "eutr": false, "cbam": false },
  "children": []
}

Search

GET /api/search?q=:term

Full-text search across HS codes, descriptions, and product names. Supports prefix matching. Returns up to 10 results.

GET /api/search?q=laptop

Response:
{
  "results": [
    { "code": "847130", "description": "Portable automatic data processing machines" },
    { "code": "8471", "description": "Automatic data processing machines" }
  ]
}

AI Classification

POST /api/classify

Uses AI to classify a product description into the correct HS code. Send a JSON body with a query field.

Optional: include "mode": "suggest" for faster, lighter results (used for autocomplete), or "mode": "full" (default) for complete classification.

POST /api/classify
Content-Type: application/json

{ "query": "organic green tea in bulk bags" }

Response:
{
  "results": [
    {
      "code": "090210",
      "description": "Green tea, not fermented",
      "confidence": "high",
      "product_name": "Green Tea"
    }
  ]
}

Product Search

GET /api/product-search?q=:term

Search products by name. Returns matching products with their primary HS code.

GET /api/product-search?q=laptop

Response:
{
  "results": [
    {
      "slug": "laptop-hs-code",
      "product_name": "Laptop",
      "primary_hs_code": "847130"
    }
  ]
}