openapi: 3.0.3
info:
  title: UAE HS Codes Public API
  version: 0.1.0
  description: |
    Public read API for UAE HS code search, lookup, hierarchy and tariff estimation.
servers:
  - url: https://www.uaehscodes.com
    description: Production
  - url: http://localhost/uaehscodes
    description: Local
tags:
  - name: health
  - name: hs-codes
  - name: tariff
paths:
  /api/v1/health:
    get:
      tags: [health]
      summary: Health check
      responses:
        '200':
          description: Service status
  /api/v1/search:
    get:
      tags: [hs-codes]
      summary: Search HS codes
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
            minLength: 2
        - in: query
          name: level
          required: false
          schema:
            type: integer
            enum: [2, 4, 6, 8, 10]
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - in: query
          name: offset
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results
  /api/v1/hs-codes/{code}:
    get:
      tags: [hs-codes]
      summary: Lookup an HS code
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: code
          required: true
          schema:
            type: string
            pattern: '^\\d{2,14}$'
      responses:
        '200':
          description: HS code record
  /api/v1/hs-codes/{code}/children:
    get:
      tags: [hs-codes]
      summary: Get one-level-down children
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: code
          required: true
          schema:
            type: string
            pattern: '^\\d{2,10}$'
      responses:
        '200':
          description: Child codes
  /api/v1/tariff/calculate:
    get:
      tags: [tariff]
      summary: Calculate import duty and optional VAT
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: hs_code
          required: true
          schema:
            type: string
            pattern: '^\\d{2,14}$'
        - in: query
          name: value
          required: true
          schema:
            type: number
            minimum: 0.01
        - in: query
          name: include_vat
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Tariff calculation result
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: X-RapidAPI-Key and Authorization Bearer are also accepted.