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 exceeded your tier's monthly call limit. Upgrade or wait for reset.
500	Server Error	Unexpected server-side error. Retry with exponential backoff. Contact support if persistent.

Rate Limits

Limits are applied per API key on a monthly rolling basis. Pro and Scale tiers include overage protection — calls above the included quota are blocked, not billed, preventing surprise charges.

Tier	Monthly calls	Price	Overage behavior
Starter	1,000	$49 / month	Calls blocked at limit. Upgrade to continue.
Pro	5,000	$149 / month	Overage Protection — no surprise bills. Calls blocked at limit.
Scale	20,000	$399 / month	Overage Protection — no surprise bills. Calls blocked at limit.
Enterprise	Custom	Custom	Negotiated SLA. Dedicated infrastructure. Contact us.

↗ When you hit a rate limit you'll receive a 429 response. Monthly limits reset on your billing cycle date. Enterprise customers receive a dedicated API key with custom limits — email hello@landedapi.dev to discuss.