Base URL
The HTS API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP.
All requests should contain the following base URL (v1):
You’ll need an account and API key to get started. From your account dashboard, you can monitor usage and setup integrations.
Authentication
To authenticate you need to add an Authorization header with the contents of the header being Bearer your_hts_api_key where your_hts_api_key is your API Key.
Authorization: Bearer your_hts_api_key
Keep your API key secure. Never expose your API key in client-side code. Use environment variables and server-side requests.
Response Codes
HTS API uses standard HTTP codes to indicate the success or failure of your requests.
| Status | Description |
|---|
200 | Success |
400 | Bad request - Invalid parameters |
401 | Unauthorized - Invalid or missing API key |
404 | Not found - Resource doesn’t exist |
429 | Rate limit exceeded |
500 | Internal server error |
2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.
Rate Limits
Rate limits vary by plan. Limits are applied per API key.
| Plan | Per Minute | Per Month |
|---|
| Free | 100 | 5,000 |
| Business | Custom | Custom |
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 60
page and limit parameters. The default limit is 25 results per page, with a maximum of 100.
Responses include pagination metadata:
{
"data": [...],
"meta": {
"total": 34377,
"page": 1,
"limit": 25,
"total_pages": 1376
}
}
Query Clarifications
When your search query is too broad or ambiguous, the API returns clarification suggestions to help you refine your search and find the correct classification.
The clarification field appears in responses when:
- HTS searches return parent-level codes or multiple subcategories
- HS ingredient searches span multiple processing levels
Business plans can also receive AI-assisted context (ai_context) to help determine the correct classification.
