HTS MCP
Skip to Content
REST APIOverview

REST API

HTS MCP exposes 12 REST endpoints through a FastAPI server, providing the same capabilities as the MCP tools via HTTP/JSON.

Base URL

http://localhost:8000/api/v1

Authentication

Optional API key authentication. Set the API_KEY environment variable to enable.

Authorization: Bearer your-api-key

If API_KEY is not set, the API runs without authentication.

Rate Limits

When RATE_LIMIT_ENABLED=true:

EndpointLimit
GET /api/v1/search30/minute
GET /api/v1/graph/edges/{code}60/minute
POST /api/v1/load5/minute
All other endpointsUnlimited

Endpoint Summary

Tariffs

MethodPathDescription
GET/api/v1/tariff/{hts_code}Get full tariff details
GET/api/v1/tariffSearch tariffs by description
GET/api/v1/searchMulti-strategy search
GET/api/v1/tariff/{code}/referencesCode references
GET/api/v1/tariff/{code}/referenced-byReverse references

Resources

MethodPathDescription
GET/api/v1/resourcesSearch resources
GET/api/v1/resources/statsResource statistics
GET/api/v1/resources/exportExport all resources
GET/api/v1/resources/{id}Get single resource
POST/api/v1/resourcesAdd new resource
PATCH/api/v1/resources/{id}/verifyToggle verification

Data Loading

MethodPathDescription
POST/api/v1/loadStart async data load
GET/api/v1/load/status/{job_id}Check load job status

Graph

MethodPathDescription
GET/api/v1/graph/statusGraph pipeline status
GET/api/v1/graph/edges/{code}Get edges for a code

Health

MethodPathDescription
GET/healthHealth check
GET/readyReadiness probe

Error Format

All errors return a consistent JSON structure:

{
  "detail": "Error message describing what went wrong"
}

Standard HTTP status codes:

  • 400: Invalid input
  • 404: Resource not found
  • 429: Rate limited
  • 500: Internal error
  • 503: Service unavailable
Section 301 ToolsTariffs