> ## 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. # Get HTS Codes > Search US HTS codes by keyword, code prefix, or chapter/heading/subheading filters Search HTS codes using full-text search, code prefix matching, or hierarchical filtering. Returns paginated results with optional clarification suggestions. ## Parameters | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------ | | `q` | string | No | Full-text search query (max 500 chars) | | `code` | string | No | Exact or prefix code match (e.g., '8517' or '8517.12') | | `chapter` | string | No | Filter by chapter (2 digits, e.g., '85') | | `heading` | string | No | Filter by heading (4 digits, e.g., '8517') | | `subheading` | string | No | Filter by subheading (6 digits, e.g., '851712') | | `page` | integer | No | Page number (default: 1, min: 1) | | `limit` | integer | No | Results per page (default: 25, min: 1, max: 100) | ## Example Request ```bash theme={null} curl -X GET "https://htsapi.com/v1/hts?q=coffee&page=1&limit=25" \ -H "Authorization: Bearer your_hts_api_key" ``` ## Example Response ```json theme={null} { "data": [ { "id": 12345, "code": "0901.11.00", "normalized_code": "09011100", "description": "Coffee, not roasted, not decaffeinated", "indent": 2, "chapter": "09", "heading": "0901", "subheading": "090111", "rates": { "general": "Free", "special": "Free (A+,AU,BH,CA...)", "other": "Free" }, "units": [], "footnotes": [] } ], "meta": { "total": 45, "page": 1, "limit": 25, "total_pages": 2 }, "clarification": { "needed": true, "message": "Your search for \"coffee\" returned multiple classifications. Please refine your search:", "suggestions": [ "Unroasted (green) coffee - 0901.11 or 0901.12", "Roasted coffee - 0901.21 or 0901.22", "Decaffeinated coffee - specify roasted (0901.22) or unroasted (0901.12)", "Note: Instant/soluble coffee is classified under 2101.11, not 0901" ], "grouped_by": "heading" } } ``` ## Clarifications When a search returns multiple classifications, the API includes a `clarification` object with suggestions to help refine your search. Business plans can also receive `ai_context` with AI-assisted guidance. ## OpenAPI ````yaml GET /hts openapi: 3.0.1 info: title: HTS API description: >- An API for HTS and HS Codes - Enabling supply chain organizations to scale with reliable data license: name: MIT version: 1.0.0 servers: - url: https://htsapi.com/v1 security: - bearerAuth: [] paths: /hts: get: summary: Search HTS Codes description: >- Returns all HTS Codes based on the query parameters. Supports full-text search, code prefix matching, and hierarchical filtering. parameters: - name: q in: query description: Full-text search query schema: type: string maxLength: 500 - name: code in: query description: Exact or prefix code match (e.g., '8517' or '8517.12') schema: type: string maxLength: 50 - name: chapter in: query description: Filter by chapter (2 digits, e.g., '85') schema: type: string maxLength: 10 - name: heading in: query description: Filter by heading (4 digits, e.g., '8517') schema: type: string maxLength: 10 - name: subheading in: query description: Filter by subheading (6 digits, e.g., '851712') schema: type: string maxLength: 10 - name: page in: query description: 'Page number (default: 1)' schema: type: integer minimum: 1 default: 1 - name: limit in: query description: 'Results per page (max: 100, default: 25)' schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: HTS Code response with pagination content: application/json: schema: $ref: '#/components/schemas/PaginatedHtsResponse' '400': description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PaginatedHtsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/HsCode' meta: $ref: '#/components/schemas/PaginationMeta' clarification: $ref: '#/components/schemas/Clarification' ai_context: type: string description: AI-assisted context (Business plans only) Error: type: object required: - error properties: error: type: string message: type: string retry_after: type: integer description: Seconds to wait before retrying (for 429 errors) HsCode: type: object required: - id - description properties: id: type: integer description: Internal ID code: type: string nullable: true description: HTS/HS Code (raw format) normalized_code: type: string nullable: true description: Normalized code (digits only) description: type: string description: Code description indent: type: integer description: Hierarchy indent level chapter: type: string nullable: true description: Chapter (2 digits) heading: type: string nullable: true description: Heading (4 digits) subheading: type: string nullable: true description: Subheading (6 digits) rates: type: object properties: general: type: string nullable: true special: type: string nullable: true other: type: string nullable: true units: type: array items: type: string description: Measurement units footnotes: type: array items: type: object properties: marker: type: string nullable: true value: type: string description: Code footnotes PaginationMeta: type: object properties: total: type: integer page: type: integer limit: type: integer total_pages: type: integer Clarification: type: object properties: needed: type: boolean message: type: string suggestions: type: array items: type: string grouped_by: type: string enum: - heading - chapter - parent securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API key as Bearer token. Format: Bearer your_hts_api_key' ````