{
  "openapi": "3.1.0",
  "info": {
    "title": "CodeHTS Public API",
    "version": "0.1.0",
    "summary": "Global tariff classification and duty calculation API.",
    "description": "Programmatic access to HS / HTS / HTSUS / EU TARIC / UK / Canada / Australia / Singapore tariff classification, duty rates, and customs filing helpers.\n\n**Authentication**: All data endpoints require an API key. Generate one in CodeHTS Settings → API Keys (Pro plan required). Pass it as `Authorization: Bearer chts_YOUR_KEY` or `x-api-key: chts_YOUR_KEY`. The `/api-health` endpoint remains public.\n\n**Quota**: Pro plan includes 5,000 requests / month per key (rolling 30-day window). Exceeding the quota returns 429.",
    "contact": {
      "name": "CodeHTS",
      "url": "https://codehts.com",
      "email": "info@codehts.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://codehts.com/disclaimer"
    }
  },
  "servers": [
    {
      "url": "https://cclnbktsighurfpxfaiz.supabase.co/functions/v1",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "System", "description": "Service health & metadata" },
    { "name": "Classification", "description": "HS / HTS / TARIC classification" },
    { "name": "Customs filing", "description": "MID, SPI and other filing helpers" }
  ],
  "paths": {
    "/api-health": {
      "get": {
        "tags": ["System"],
        "summary": "Service health",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" }
              }
            }
          }
        }
      }
    },
    "/lookup-hts-suggestions": {
      "post": {
        "tags": ["Classification"],
        "summary": "Suggest HTS / HS codes for a product description",
        "operationId": "lookupHtsSuggestions",
        "security": [{ "apiKeyAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClassifyRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked list of candidate codes",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ClassifyResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/suggest-spi": {
      "post": {
        "tags": ["Customs filing"],
        "summary": "Suggest Special Program Indicators (SPI) for a line",
        "operationId": "suggestSpi",
        "security": [{ "apiKeyAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SpiRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked SPI suggestions with rationale",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SpiResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid request payload",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid or revoked API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Monthly quota exceeded",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": ["status", "time"],
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded"] },
          "service": { "type": "string", "example": "codehts-api" },
          "version": { "type": "string", "example": "0.1.0" },
          "time": { "type": "string", "format": "date-time" }
        }
      },
      "ClassifyRequest": {
        "type": "object",
        "required": ["description"],
        "properties": {
          "description": { "type": "string", "minLength": 3, "example": "Stainless steel water bottle, vacuum insulated, 500ml" },
          "region": {
            "type": "string",
            "enum": ["US", "EU", "UK", "CA", "AU", "SG"],
            "default": "US"
          },
          "country_of_origin": { "type": "string", "example": "CN", "description": "ISO 3166-1 alpha-2" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }
        }
      },
      "ClassifyResponse": {
        "type": "object",
        "properties": {
          "suggestions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ClassifySuggestion" }
          }
        }
      },
      "ClassifySuggestion": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "example": "9617.00.10" },
          "description": { "type": "string" },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "chapter": { "type": "string" },
          "duty_rate": { "type": "string", "example": "7.2%" }
        }
      },
      "SpiRequest": {
        "type": "object",
        "required": ["hts_code", "country_of_origin"],
        "properties": {
          "hts_code": { "type": "string", "example": "8471.30.0100" },
          "country_of_origin": { "type": "string", "example": "MX" },
          "product_description": { "type": "string" }
        }
      },
      "SpiResponse": {
        "type": "object",
        "properties": {
          "suggestions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": { "type": "string", "example": "S" },
                "program": { "type": "string", "example": "USMCA" },
                "duty_rate": { "type": "string", "example": "Free" },
                "rationale": { "type": "string" },
                "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "details": {}
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "chts_*",
        "description": "Pass your CodeHTS API key as 'Authorization: Bearer chts_YOUR_KEY'."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Alternative: pass your CodeHTS API key in the 'x-api-key' header."
      }
    }
  },
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://codehts.com/docs/api"
  }
}