{
  "openapi": "3.1.0",
  "info": {
    "title": "US Tariff Rates API",
    "version": "1.1.0",
    "description": "Complete US tariff duty calculation with Section 122, 232, 301, and AD/CVD overlays. HS code concordance for US/EU/UK.",
    "contact": { "url": "https://ustariffrates.com/contact" }
  },
  "servers": [{ "url": "https://ustariffrates.com" }],
  "security": [{ "apiKey": [] }],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "API key from POST /api/v1/keys or ?api_key= query parameter"
      }
    },
    "schemas": {
      "HTSResult": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string", "description": "Public API major version" },
          "schema_version": { "type": "string", "description": "Additive response schema generation" },
          "hts_code": { "type": "string", "description": "HTS code (up to 10 digits)" },
          "description": { "type": "string" },
          "hierarchy": { "type": "string", "description": "Chapter > heading > subheading breadcrumb" },
          "general_duty": { "type": "string", "nullable": true, "description": "General (MFN) duty rate" },
          "special_duty": { "type": "string", "nullable": true, "description": "Special duty programs (GSP, FTA)" },
          "base_duty": { "type": "string", "description": "Base ad valorem or specific duty" },
          "section_122": { "type": "number", "description": "Section 122 surcharge — 10% (Proclamation 11012)" },
          "section_232": { "type": "number", "description": "Section 232 rate (50% steel/alum/copper, 25% autos)" },
          "section_232_label": { "type": "string", "nullable": true, "description": "Steel, Aluminum, Copper, Auto" },
          "section_301_china": { "type": "number", "description": "Section 301 China rate (%)" },
          "section_301_china_list": { "type": "string", "nullable": true, "description": "List 1, 2, 3, 4A, 4B" },
          "total_additional": { "type": "number", "description": "Sum of §122 + §232 + §301" },
          "total_estimated": { "type": "string", "description": "Total estimated deterministic duty; risk layers such as AD/CVD, quota/TRQ, exclusions, and fact-dependent special programs are surfaced separately" },
          "warnings": { "type": "array", "items": { "type": "string" }, "description": "Human-readable tariff warnings" },
          "adcvd_risk": {
            "type": "object",
            "nullable": true,
            "properties": {
              "product": { "type": "string" },
              "type": { "type": "string" },
              "rate_range": { "type": "string" },
              "countries": { "type": "array", "items": { "type": "string" } }
            }
          },
          "tariff_stack": {
            "type": "object",
            "description": "Structured deterministic tariff stack plus risk layers"
          },
          "adcvd_matches": {
            "type": "array",
            "description": "All matching AD/CVD screening matches by HTS prefix and country",
            "items": { "$ref": "#/components/schemas/ADCVDOrder" }
          },
          "evidence": {
            "type": "object",
            "description": "Source and matching metadata for auditability"
          }
        }
      },
      "ADCVDOrder": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "case_number": { "type": "string" },
          "product": { "type": "string" },
          "country": { "type": "string" },
          "case_type": { "type": "string", "enum": ["AD", "CVD"] },
          "rate_range": { "type": "string" },
          "federal_register_url": { "type": "string" },
          "status": { "type": "string" },
          "effective_date": { "type": "string", "nullable": true },
          "last_review_date": { "type": "string", "nullable": true },
          "hts_prefixes": { "type": "array", "items": { "type": "string" } },
          "matched_prefix": { "type": "string", "nullable": true },
          "risk_level": { "type": "string", "enum": ["likely", "possible", "review"], "nullable": true },
          "scope_warning": { "type": "string", "nullable": true }
        }
      },
      "FreshnessResponse": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string" },
          "schema_version": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "summary": {
            "type": "object",
            "description": "Aggregate source-monitor health"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "label": { "type": "string" },
                "authority": { "type": "string" },
                "status": { "type": "string" },
                "cadence_hours": { "type": "number", "nullable": true },
                "last_checked_at": { "type": "string", "nullable": true },
                "last_success_at": { "type": "string", "nullable": true },
                "last_changed_at": { "type": "string", "nullable": true },
                "hours_since_check": { "type": "number", "nullable": true },
                "latest_event": { "type": "string", "nullable": true },
                "latest_summary": { "type": "string", "nullable": true },
                "error": { "type": "string", "nullable": true },
                "source_urls": { "type": "array", "items": { "type": "string" } },
                "description": { "type": "string", "nullable": true }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/search": {
      "get": {
        "summary": "Search HTS codes",
        "description": "Search by product description or partial HTS code",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country of origin" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/HTSResult" } } } } } }
          },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/v1/search/eu": {
      "get": {
        "summary": "Search EU CN/TARIC codes",
        "description": "Search EU customs tariff codes by product description or partial code",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "EU tariff search results",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string" }, "schema_version": { "type": "string" }, "results": { "type": "array" }, "count": { "type": "integer" }, "query": { "type": "string" } } } } }
          }
        }
      }
    },
    "/api/v1/search/uk": {
      "get": {
        "summary": "Search UKGT codes",
        "description": "Search UK Trade Tariff commodity codes by product description or partial code",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "UK tariff search results",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string" }, "schema_version": { "type": "string" }, "results": { "type": "array" }, "count": { "type": "integer" }, "query": { "type": "string" } } } } }
          }
        }
      }
    },
    "/api/v1/lookup": {
      "get": {
        "summary": "Look up HTS code",
        "description": "Full duty breakdown for a specific HTS code. Resolves headings, subheadings, and statistical suffixes.",
        "parameters": [
          { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "HTS code (any level: chapter, heading, 8-digit, 10-digit)" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country of origin for country-specific rates" },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["best", "exact", "strict"], "default": "best" }, "description": "best preserves v1 prefix fallback; exact/strict require exact HTS match" }
        ],
        "responses": {
          "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTSResult" } } } },
          "404": { "description": "HTS code not found" }
        }
      }
    },
    "/api/v1/bulk": {
      "post": {
        "summary": "Bulk lookup",
        "description": "Batch lookup multiple products by description and/or HTS code",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "description": { "type": "string" },
                        "hts_code": { "type": "string" },
                        "country": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Bulk results with summary" }
        }
      }
    },
    "/api/v1/prices": {
      "get": {
        "summary": "Trade statistics",
        "description": "Import values by country for an HTS code",
        "parameters": [
          { "name": "hts", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "months", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 36, "default": 12 } },
          { "name": "country", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Trade data",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "hts_code": { "type": "string" }, "total_value": { "type": "number" }, "top_origins": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "value": { "type": "number" } } } } } } } }
          }
        }
      }
    },
    "/api/v1/convert": {
      "get": {
        "summary": "HS code concordance",
        "description": "Convert between US HTS, EU CN, and UK commodity codes via HS6 matching",
        "parameters": [
          { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "HS/HTS code to convert" },
          { "name": "from", "in": "query", "schema": { "type": "string", "enum": ["us", "eu", "uk"] }, "description": "Source system (auto-detected if omitted)" }
        ],
        "responses": {
          "200": {
            "description": "Concordance results",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "hs6": { "type": "string" }, "us_codes": { "type": "array" }, "eu_codes": { "type": "array" }, "uk_codes": { "type": "array" } } } } }
          }
        }
      }
    },
    "/api/v1/trade-remedies": {
      "get": {
        "summary": "AD/CVD orders",
        "description": "Antidumping and countervailing duty cases. Use hts for live HTS-prefix screening matches.",
        "parameters": [
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["ad", "cvd"] } },
          { "name": "country", "in": "query", "schema": { "type": "string" } },
          { "name": "product", "in": "query", "schema": { "type": "string" } },
          { "name": "hts", "in": "query", "schema": { "type": "string" }, "description": "HTS code for prefix-based order screening" },
          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string" }, "schema_version": { "type": "string" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/ADCVDOrder" } }, "count": { "type": "integer" } } } } }
          }
        }
      }
    },
    "/api/v1/freshness": {
      "get": {
        "summary": "Source freshness",
        "description": "Current source-monitor health for public tariff and trade-remedy data sources",
        "security": [],
        "responses": {
          "200": {
            "description": "Freshness and source-monitor status",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshnessResponse" } } }
          }
        }
      }
    },
    "/api/v1/keys": {
      "post": {
        "summary": "Generate API key",
        "description": "Get a free API key (no authentication required)",
        "security": [],
        "requestBody": {
          "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } }
        },
        "responses": {
          "201": { "description": "API key created" }
        }
      }
    },
    "/api/v1/docs": {
      "get": {
        "summary": "API documentation (JSON)",
        "security": [],
        "responses": { "200": { "description": "Machine-readable docs" } }
      }
    }
  }
}