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

> Search global HS codes (6-digit) by keyword, code prefix, or ingredient list

Search HS codes (6-digit international codes) using full-text search, code prefix matching, or ingredient-based search. 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., '1101' or '1101.00')                   |
| `ingredients` | string  | No       | Comma-separated list of ingredients (e.g., 'wheat,flour', max 500 chars) |
| `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/hs?ingredients=wheat,flour&page=1&limit=25" \
  -H "Authorization: Bearer your_hts_api_key"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": 1234,
      "code": "1101.00",
      "normalized_code": "110100",
      "description": "Wheat or meslin flour",
      "indent": 1,
      "chapter": "11",
      "heading": "1101",
      "subheading": "110100",
      "rates": {
        "general": "Free",
        "special": null,
        "other": null
      },
      "units": [],
      "footnotes": []
    },
    {
      "id": 1235,
      "code": "1001.99",
      "normalized_code": "100199",
      "description": "Wheat (other than durum), unmilled",
      "indent": 1,
      "chapter": "10",
      "heading": "1001",
      "subheading": "100199",
      "rates": {
        "general": "Free",
        "special": null,
        "other": null
      },
      "units": [],
      "footnotes": []
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "limit": 25,
    "total_pages": 1
  },
  "clarification": {
    "needed": true,
    "message": "Your ingredient search for \"wheat,flour\" returned results across multiple processing levels. Please clarify:",
    "suggestions": [
      "Raw wheat grain (unmilled) → Chapter 10 (1001.xx) - Use when product is whole wheat kernels/grain",
      "Wheat flour (plain, unmixed) → Chapter 11 (1101.00) - Use when plain wheat flour, no additives, not prepared food",
      "Doughs/mixes → Chapter 19 (1901.20) - Use when flour is mixed with yeast, salt, sugar, oil, etc., but not yet baked",
      "Finished baked goods → Chapter 19 (1905.xx) - Use when flour is no longer an ingredient but a finished food"
    ],
    "grouped_by": "chapter"
  }
}
```

## Ingredient Search

The `ingredients` parameter allows you to search for codes by listing product ingredients. This is particularly useful for food products where the same ingredients can appear at different processing levels (raw, milled, prepared).

When ingredient searches span multiple processing levels, the API provides clarification suggestions to help you choose the correct classification.


## OpenAPI

````yaml GET /hs
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:
  /hs:
    get:
      summary: Search HS Codes
      description: >-
        Returns HS codes (6-digit international codes) based on the query
        parameters. Supports full-text search, code prefix matching, and
        ingredient-based search.
      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., '1101' or '1101.00')
          schema:
            type: string
            maxLength: 50
        - name: ingredients
          in: query
          description: Comma-separated list of ingredients (e.g., 'wheat,flour')
          schema:
            type: string
            maxLength: 500
        - 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: HS Code response with pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedHsResponse'
        '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:
    PaginatedHsResponse:
      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'

````