Developer Reference

API Documentation

Everything you need to integrate LandedAPI — authentication, endpoint reference, request shapes, and response examples.

Base URL https://trade-hts-api-production.up.railway.app

Authentication

All /v1/* endpoints require a Bearer token in the Authorization header. The /health endpoint is public and requires no authentication.

↗ Your API key is issued when you subscribe. Find it in your dashboard after purchase. Keep it secret — treat it like a password.

Required header

Authorization: Bearer <your_api_key>

Example request

# Authenticated request example
curl -X GET \
  "https://trade-hts-api-production.up.railway.app/v1/hts/search?q=cotton" \
  -H "Authorization: Bearer your_api_key_here"

! Note: The API expects Authorization: Bearer <key> — not x-api-key or any other header format. Requests with an incorrect or missing header receive a 401 response.

Quickstart

Two curl commands to verify connectivity and your first authenticated result.

1 — Health check (no auth required)

curl "https://trade-hts-api-production.up.railway.app/health"

# Response
{
  "status": "ok",
  "timestamp": "2026-06-30T05:05:07.488Z"
}

2 — Search HTS codes (auth required)

curl \
  -H "Authorization: Bearer your_api_key_here" \
  "https://trade-hts-api-production.up.railway.app/v1/hts/search?q=cotton"

# Response — array of matching HTS codes
{
  "data": [
    {
      "hts_number": "520100",
      "description": "Cotton, not carded or combed",
      "chapter": 52,
      "heading": "5201",
      "indent_level": 0
    },
    // ... more results
  ]
}

Endpoints

GET /health No auth

Returns the current API status and server timestamp. Use this to verify connectivity before making authenticated requests. No API key required.

Request

curl "https://trade-hts-api-production.up.railway.app/health"

Response · 200

{
  "status": "ok",
  "timestamp": "2026-06-30T05:05:07.488Z"
}

GET /v1/hts/search Auth required

Full-text search across 29,597 HTS code descriptions. Returns all matching codes ranked by relevance, including their chapter, heading, and indent level for hierarchy navigation.

Parameter	Type	Required	Description
q	string	required	Search term matched against HTS description text.

Request

curl \
  -H "Authorization: Bearer <key>" \
  "...up.railway.app/v1/hts/search?q=cotton"

Response · 200

{
  "data": [
    {
      "hts_number": "520100",
      "description": "Cotton, not carded or combed",
      "chapter": 52,
      "heading": "5201",
      "subheading": "520100",
      "indent_level": 0,
      "parent_hts": null,
      "created_at": "2026-06-29T11:21:58.589Z"
    }
  ]
}

GET /v1/rulings/search Auth required

Search 192,305 CBP administrative rulings by summary text. Returns ruling number, associated HTS code, ruling date, and summary. Useful for finding precedent classifications.

Parameter	Type	Required	Description
q	string	required	Search term matched against ruling summary text.

Request

curl \
  -H "Authorization: Bearer <key>" \
  "...up.railway.app/v1/rulings/search?q=classification"

Response · 200

{
  "data": [
    {
      "id": "e0537e9e-8847...",
      "ruling_number": "875963",
      "hts_number": "8302.41.9045",
      "ruling_date": "1992-07-10",
      "summary": "The tariff classification of..."
    }
  ]
}

POST /v1/classify Auth required

AI-powered HTS classification with GRI reasoning. Returns a ranked list of candidate HTS codes, confidence scores, full GRI analysis explaining each classification, and supporting CBP rulings where available.

Field	Type	Required	Description
description	string	required	Plain-language product description. More detail yields more accurate classifications.
country_of_origin	string	optional	Country of manufacture. Used to flag applicable Section 301 or antidumping duties.

Request

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "stainless steel hex bolts",
    "country_of_origin": "China"
  }' \
  "...up.railway.app/v1/classify"

Response · 200

{
  "country_of_origin": "China",
  "classifications": [
    {
      "hts_number": "7318.15.8065",
      "description": "Stainless steel hex bolts, shank ≥6mm",
      "confidence": 0.55,
      "gri_reasoning": "GRI 1: Chapter 73...",
      "supporting_rulings": []
    }
  ]
}

POST /v1/optimize-tariff Auth required

Returns up to four optimization vectors — material composition, country of origin, first-sale valuation, and FTA qualification — with estimated annual savings, feasibility ratings, and CBP ruling citations for each path.

Field	Type	Required	Description
product_description	string	required	Plain-language description of the product.
chapter	number	required	HTS chapter number (e.g. `64` for footwear).
material_composition	object	required	Key/value map of material names to percentage by weight.
country_of_origin	string	required	Current country of manufacture.
annual_import_value	number	required	Annual import value in USD. Used to calculate projected savings.
current_hts	string	optional	Known current HTS code. Improves accuracy of duty rate calculations.

Request

curl -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_description": "athletic shoe with textile upper and rubber sole",
    "chapter": 64,
    "material_composition": { "textile_upper": 55, "rubber_sole": 45 },
    "country_of_origin": "China",
    "annual_import_value": 2000000
  }' \
  "...up.railway.app/v1/optimize-tariff"

Response · 200

{
  "current_hts": "6404.11.9080",
  "current_duty_rate": "20% base + 25% Section 301 = 45% total",
  "optimized_duty_rate": "0% via USMCA/CAFTA-DR",
  "projected_annual_savings": 1035000,
  "optimization_vectors": [
    {
      "type": "country_of_origin",
      "estimated_savings": 500000,
      "feasibility": "high",
      "description": "Shift manufacturing to Vietnam...",
      "ruling_citations": ["USTR Section 301 List 3..."]
    },
    // material_composition, first_sale_valuation, fta_qualification
  ],
  "disclaimer": "Research support only. Not legal advice under 19 U.S.C. 1641"
}

Error Codes

All error responses return JSON with an error field containing a human-readable message.

{
  "error": "Missing or malformed Authorization header. Expected: Bearer <key>"
}

Status	Meaning	Common cause
200	OK	Request succeeded. Check `data` or response body.
401	Unauthorized	Missing, malformed, or invalid `Authorization` header. Verify format: `Bearer <key>`.
400	Bad Request	Missing required body field or invalid JSON. Check the `error` message for the specific field.
429	Rate Limit Exceeded	You have exhausted your tenant's combined credit balance. Purchase a top-up pack or upgrade your tier.
500	Server Error	Unexpected server-side error. Retry with exponential backoff. Contact support if persistent.

Rate Limits

Credits are consumed per request: classify = 1 credit, optimize-tariff = 20 credits. Credits reset monthly on your billing date. Top-up packs can be purchased at any time and carry over indefinitely.

Tier	Monthly credits	Price	When credits run out
Starter	300	$99 / month	Requests blocked. Purchase top-up pack or upgrade.
Pro	800	$250 / month	Soft overage — requests continue up to a defined multiple of the monthly allowance before 429. Purchase a top-up or upgrade to Scale.
Scale	2,000	$500 / month	Soft overage — requests continue up to a defined multiple of the monthly allowance before 429. Purchase a top-up or contact us for Enterprise.
Enterprise	Custom	Custom	Negotiated SLA. Dedicated infrastructure. Contact us.

↗ Starter: requests return 429 when the monthly credit balance is exhausted — hard cap. Pro / Scale: soft overage applies — requests continue beyond the monthly allowance up to a defined multiple before returning 429. Enterprise: uncapped by default; limits negotiated per contract. Credits reset monthly on your billing date. Top-up packs are available in the dashboard and never expire. Enterprise customers receive a dedicated API key — email hello@landedapi.dev to discuss.