> ## Documentation Index
> Fetch the complete documentation index at: https://docs.htsapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> HTS API documentation - Base URL, authentication, rate limits, pagination, and response format

## 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):

```text theme={null}
https://htsapi.com/v1/
```

<Info>
  You'll need an account and API key to get started. From your account dashboard, you can monitor usage and setup integrations.
</Info>

## 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.

```text theme={null}
Authorization: Bearer your_hts_api_key
```

<Warning>
  Keep your API key secure. Never expose your API key in client-side code. Use environment variables and server-side requests.
</Warning>

## 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                     |

In general, `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    |

The response headers describe your current rate limit following every request:

```text theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 60
```

Contact our team to adjust rate limits based on your usage.

## Pagination

Most endpoints support pagination using `page` and `limit` parameters. The default limit is 25 results per page, with a maximum of 100.

Responses include pagination metadata:

```json theme={null}
{
  "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.