{"openapi":"3.1.0","info":{"title":"USTariffRates API","version":"1.0.1","summary":"Provenance-rich US tariff lookup, landed-duty calculation, and customs entry audit — every response cites the Federal Register / Executive Order authority for any overlay applied.","description":"USTariffRates exposes a small set of focused endpoints designed for both human integrators and LLM agents:\n\n- **`/v1/lookup`** — current rate stack for an HTS code, with `as_of` retroactive lookups.\n- **`/v1/search`** — HTS search by description, exact code, or prefix, returning the same canonical response envelope.\n- **`/v1/calculate`** — landed-duty calculation (base MFN + Section 122 + 232 + 301 + MPF + HMF).\n- **`/v1/audit/entry`** — line-by-line audit of a 7501 entry against current rates.\n\nEvery response includes a `provenance[]` array with the Federal Register cite and effective date for any tariff overlay applied — so any agent or auditor can trace a number back to its legal authority without leaving the response.\n\n**Authentication.** The first 25 requests/month from any IP are anonymous and unauthenticated; past that, supply an API key via `X-Api-Key`, `Authorization: Bearer …`, or `?api_key=…`. Tier caps are enforced server-side.\n\n**Hosted MCP.** Connect an MCP client to `https://api.ustariffrates.com/mcp` and send a customer API key with `Authorization: Bearer …` or `X-Api-Key`. The hosted server exposes seven curated tariff workflows without requiring a local package. MCP usage is authorized and billed to the customer account behind that key under its existing plan, quota, and overage rules. Autonomous wallet payments are not enabled for v1.","contact":{"name":"USTariffRates","url":"https://ustariffrates.com","email":"hello@ustariffrates.com"},"license":{"name":"Proprietary","url":"https://ustariffrates.com/terms"}},"servers":[{"url":"https://api.ustariffrates.com","description":"Production"}],"security":[{"apiKeyHeader":[]},{"bearerAuth":[]},{"apiKeyQuery":[]}],"tags":[{"name":"Lookup","description":"Read tariff rate stacks."},{"name":"Calculate","description":"Compute landed duty for a single line."},{"name":"Audit","description":"Audit a 7501 entry for declared-vs-expected duty discrepancies."},{"name":"MCP","description":"Hosted Model Context Protocol access to curated tariff workflows."},{"name":"Health","description":"Liveness probe."}],"paths":{"/mcp":{"post":{"tags":["MCP"],"summary":"Hosted MCP Streamable HTTP endpoint","description":"Stateless Streamable HTTP endpoint for search, lookup, calculation, historical replay, nomenclature concordance, monitored changes, and entry audit. A customer API key is always required. Tool calls inherit the key's plan limits and usage metering. The server uses @modelcontextprotocol/sdk 1.29 and negotiates the SDK's supported official MCP protocol versions, currently led by 2025-11-25. Its request-isolated architecture follows the July 28, 2026 stateless direction without claiming that date as a published protocol version. Optional X-Mcp-Client-Name and X-Mcp-Client-Version headers improve observable client attribution. Payment-Signature is reserved for future wallet/x402 compatibility and currently returns a customer-safe 402 response rather than authorizing a call.","operationId":"hostedMcp","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"MCP JSON-RPC response."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/health":{"get":{"tags":["Health"],"summary":"Liveness probe","description":"Public, unauthenticated. Returns the service identifier and version.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"ok":true,"service":"ustariffrates-api","version":"1.0.1","api_version":"v1","schema_version":"2026-07-match-confidence"}}}}}}},"/v1/lookup":{"get":{"tags":["Lookup"],"summary":"Look up the current rate stack for an HTS code","description":"Returns the HTS row plus, when `country` is supplied, the per-country rate stack (base MFN + Section 122 + 232 + 301) with FR cites for every applied overlay. Use `as_of` to resolve the rate stack as it stood on a past date — useful for entry audits and refund work.","operationId":"lookupTariff","parameters":[{"name":"hts","in":"query","required":true,"description":"10-digit HTS code (dotted or undotted, e.g. `8471.30.01.00` or `8471300100`).","schema":{"type":"string","example":"8471.30.01.00"}},{"name":"country","in":"query","required":false,"description":"ISO-2 country code of origin (e.g. `CN`, `MX`). Required to compute the rate stack. Without it, the bare HTS row is returned with country-specific program rates omitted.","schema":{"type":"string","example":"CN"}},{"name":"origin","in":"query","required":false,"description":"Alias for `country`, matching the name used by `/v1/changes`.","schema":{"type":"string","example":"CN"}},{"name":"as_of","in":"query","required":false,"description":"ISO date (YYYY-MM-DD) for retroactive rate lookup. Defaults to today. Requires a country; returns 400 without one, because rates only move through time per country.","schema":{"type":"string","format":"date","example":"2026-04-15"}},{"name":"mode","in":"query","required":false,"description":"`exact` returns 404 when the HTS code is not an exact match. `best` allows canonicalized best matches and reports match metadata.","schema":{"type":"string","enum":["exact","strict","best"],"default":"exact"}}],"responses":{"200":{"description":"Rate stack returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/replay":{"get":{"tags":["Lookup"],"summary":"Replay a historical tariff stack","description":"Reconstructs the deterministic tariff stack for an HTS/origin lane on a requested date and compares it with the current stack. Coverage is explicit: program rates resolve by effective date, while historical HTS schedule coverage remains partial until the corresponding archive is available.","operationId":"replayTariffStack","parameters":[{"name":"hts","in":"query","required":true,"description":"10-digit HTS code, dotted or undotted.","schema":{"type":"string","example":"8471.30.01.00"}},{"name":"country","in":"query","required":false,"description":"Country of origin. Required unless `origin` is supplied.","schema":{"type":"string","example":"CN"}},{"name":"origin","in":"query","required":false,"description":"Alias for `country`, matching the name used by `/v1/changes`. Required unless `country` is supplied.","schema":{"type":"string","example":"CN"}},{"name":"as_of","in":"query","required":true,"description":"Historical entry or comparison date in YYYY-MM-DD form.","schema":{"type":"string","format":"date","example":"2026-04-15"}},{"name":"mode","in":"query","required":false,"description":"Use exact for filing-grade code resolution or best to permit an explicitly reported best match.","schema":{"type":"string","enum":["exact","strict","best"],"default":"exact"}}],"responses":{"200":{"description":"Historical and current stack snapshots with explicit archive coverage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/changes":{"get":{"tags":["Tariff Assurance"],"summary":"List monitored tariff-stack changes","description":"Returns customer-scoped, country-aware changes for watched HTS/origin lanes, including before/after Assurance snapshots and workflow state. Requires Pro or higher.","operationId":"listTariffChanges","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"before_id","in":"query","schema":{"type":"string"}},{"name":"acknowledged","in":"query","schema":{"type":"boolean"}},{"name":"hts","in":"query","schema":{"type":"string"}},{"name":"origin","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Customer-scoped tariff changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TariffChangesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"patch":{"tags":["Tariff Assurance"],"summary":"Update tariff-change workflow state","description":"Acknowledges or assigns a customer-scoped tariff change. Requires Team or higher.","operationId":"updateTariffChange","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["change_id"],"properties":{"change_id":{"type":"string"},"acknowledged":{"type":"boolean"},"assigned_to":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Workflow state updated."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/search":{"get":{"tags":["Lookup"],"summary":"Search HTS codes","description":"Search by product description, exact HTS code, or HTS prefix. Each result includes the canonical metadata envelope so clients can pin data freshness and schema version.","operationId":"searchTariffs","parameters":[{"name":"q","in":"query","required":true,"description":"Product description, exact HTS code, or HTS prefix.","schema":{"type":"string","example":"electric vehicle"}},{"name":"country","in":"query","required":false,"description":"Optional ISO-2 country code used to attach rate stacks to each result.","schema":{"type":"string","example":"CN"}},{"name":"origin","in":"query","required":false,"description":"Alias for `country`, matching the name used by `/v1/changes`.","schema":{"type":"string","example":"CN"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Search results returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/calculate":{"post":{"tags":["Calculate"],"summary":"Calculate landed duty for a single import line","description":"Returns itemized line items (base MFN, Section 122, Section 232, Section 301 China, IEEPA, MPF, HMF) plus `total_duty`, `total_landed`, `effective_rate_pct`, risk layers, and FR/source provenance. Structured quantities can complete specific and compound base-duty formulas; unresolved facts remain excluded rather than becoming zero or Free.","operationId":"calculateDuty","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"}}}},"responses":{"200":{"description":"Duty calculated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/audit/entry":{"post":{"tags":["Audit"],"summary":"Audit a 7501 entry against current rates","description":"Per-line diff between declared and expected duty for an import entry. Each line returns a `flag` (`match` | `underpaid` | `overpaid` | `needs_facts` | `error`), the canonical Tariff Assurance snapshot, and FR cite provenance. Specific or compound duties return `needs_facts` until quantity and unit facts are supplied. Requires a Team or Enterprise API key.","operationId":"auditEntry","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryRequest"}}}},"responses":{"200":{"description":"Audit complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Caller's tier does not include the audit endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"Audit endpoint requires a Team or Enterprise API key.","hint":"Upgrade at https://ustariffrates.com/pricing"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"},"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"Health":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"service":{"type":"string","example":"ustariffrates-api"},"version":{"type":"string","example":"1.0.1"},"api_version":{"type":"string","example":"v1"},"schema_version":{"type":"string","example":"2026-07-match-confidence"}},"required":["ok","service","version","api_version","schema_version"]},"ProvenanceEntry":{"type":"object","description":"Federal Register / Executive Order cite for an applied tariff overlay. `kind` identifies which overlay this provenance row applies to.","properties":{"kind":{"type":"string","enum":["section_122","section_232","section_301_china","section_301","section_338","ieepa"],"example":"section_232"},"program_id":{"type":["string","null"],"example":"232-steel"},"authority":{"type":["string","null"],"example":"Section 232 — Proc 11021"},"source_doc_number":{"type":["string","null"],"example":"2026-06960"},"source_url":{"type":["string","null"],"format":"uri","example":"https://www.federalregister.gov/documents/2026/04/09/2026-06960/strengthening-actions-taken-to-adjust-imports-of-aluminum-steel-and-copper-into-the-united-states"},"effective_from":{"type":["string","null"],"format":"date","example":"2026-04-06"},"notes":{"type":["string","null"]},"label":{"type":["string","null"],"example":"Auto - Parts (Section 232)"},"list":{"type":["string","null"],"example":"List 4A"}},"required":["kind"]},"RateStackEntry":{"type":"object","properties":{"kind":{"type":"string","enum":["base_mfn","section_122","section_232","section_301_china","section_301","section_338","ieepa"]},"rate_pct":{"type":"number","example":25},"label":{"type":["string","null"]},"list":{"type":["string","null"]}},"required":["kind","rate_pct"]},"TariffAssuranceSnapshot":{"type":"object","description":"Versioned, coverage-visible tariff stack for one HTS/origin/as-of lane. Deterministic and fact-dependent layers remain separate.","properties":{"schema_version":{"type":"string","example":"2026-07-28"},"hts":{"type":"string"},"origin":{"type":"string"},"as_of":{"type":"string","format":"date"},"calculated_at":{"type":"string","format":"date-time"},"data_version":{"type":"string"},"coverage":{"type":"object","properties":{"status":{"type":"string","enum":["verified","partial","unavailable"]},"missing_layers":{"type":"array","items":{"type":"string"}},"note":{"type":["string","null"]}},"required":["status","missing_layers","note"]},"layers":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"status":{"type":"string","enum":["applied","excluded","not_applicable","fact_dependent","unverified"]},"rate_pct":{"type":["number","null"]},"label":{"type":["string","null"]},"authority":{"type":["string","null"]},"source_url":{"type":["string","null"]},"effective_from":{"type":["string","null"]},"effective_to":{"type":["string","null"]}},"required":["kind","status","rate_pct"]}},"deterministic_total_pct":{"type":"number"}},"required":["schema_version","hts","origin","as_of","calculated_at","data_version","coverage","layers","deterministic_total_pct"]},"LookupResponse":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"schema_version":{"type":"string","example":"2026-07-match-confidence"},"data_version":{"type":"string","example":"hts:2026-02-25 15:50:27"},"data_updated_at":{"type":["string","null"],"example":"2026-02-25 15:50:27"},"last_verified_at":{"type":["string","null"],"example":"2026-08-06T13:02:11.000Z","description":"When the data was last verified against the official USITC source. Unlike data_updated_at, this advances even on days when the source is checked and found unchanged."},"source_edition":{"type":"string","example":"USITC HTS 2026 Basic Edition"},"match":{"$ref":"#/components/schemas/HTSMatch"},"hts":{"type":"string","example":"8471.30.01.00"},"description":{"type":"string","example":"Portable automatic data processing machines, weighing not more than 10 kg..."},"country":{"type":["string","null"],"example":"CN"},"as_of":{"type":["string","null"],"format":"date","example":null},"rate_stack":{"type":"array","items":{"$ref":"#/components/schemas/RateStackEntry"}},"total_additional_pct":{"type":"number","example":35},"total_estimated":{"type":"string","example":"35%","description":"Deterministic rate stack only; fact-dependent AD/CVD, quota/TRQ, exclusions, and special programs are reported in risk_layers."},"warnings":{"type":"array","items":{"type":"string"}},"risk_layers":{"type":"array","items":{"$ref":"#/components/schemas/RiskLayer"}},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceEntry"}},"assurance":{"$ref":"#/components/schemas/TariffAssuranceSnapshot"}},"required":["hts","description"]},"ReplayResponse":{"type":"object","properties":{"api_version":{"type":"string"},"schema_version":{"type":"string"},"data_version":{"type":"string"},"hts":{"type":"string"},"description":{"type":"string"},"origin":{"type":"string"},"requested_as_of":{"type":"string","format":"date"},"historical":{"$ref":"#/components/schemas/TariffAssuranceSnapshot"},"current":{"$ref":"#/components/schemas/TariffAssuranceSnapshot"},"change":{"type":["object","null"],"description":"Typed difference between the historical and current snapshots."},"coverage":{"type":"object","description":"Historical archive coverage for the requested replay."},"coverage_note":{"type":["string","null"]}},"required":["hts","description","origin","requested_as_of","historical","current","coverage"]},"HTSMatch":{"type":"object","description":"How the requested code was resolved. `confidence` is a deterministic resolution-quality heuristic (1.0 exact, 0.9 prefix, 0.6 truncated_prefix, 0.4 parent), not a statistical probability.","properties":{"input_code":{"type":"string","example":"8703800020"},"input_code_clean":{"type":"string","example":"8703800020"},"matched_code":{"type":"string","example":"8703.80.00.20"},"matched_code_clean":{"type":"string","example":"8703800020"},"match_type":{"type":"string","enum":["exact","prefix","truncated_prefix","parent"],"example":"exact"},"exact":{"type":"boolean","example":true},"matched_prefix_length":{"type":"integer","example":10},"confidence":{"type":"number","minimum":0,"maximum":1,"example":1}},"required":["input_code","matched_code","match_type","exact","confidence"]},"SearchRelevance":{"type":"object","description":"Ranking metadata for a search result. `fts_bm25` results are ranked by SQLite FTS5 BM25 (`bm25_score`, lower is more relevant); `code_match` results come from direct/prefix code resolution and carry a match block instead of a BM25 score.","properties":{"result_rank":{"type":"integer","example":1},"method":{"type":"string","enum":["code_match","fts_bm25"],"example":"fts_bm25"},"bm25_score":{"type":["number","null"],"example":-4.2}},"required":["result_rank","method","bm25_score"]},"SearchResult":{"type":"object","properties":{"hts":{"type":"string","example":"8703.80.00.20"},"description":{"type":"string"},"match":{"oneOf":[{"$ref":"#/components/schemas/HTSMatch"},{"type":"null"}],"description":"Present for code-style queries resolved against the schedule; null for text-query candidates, which carry `relevance` ranking instead."},"relevance":{"$ref":"#/components/schemas/SearchRelevance"},"rate_stack":{"type":"array","items":{"$ref":"#/components/schemas/RateStackEntry"}},"total_additional_pct":{"type":"number","example":100},"risk_layers":{"type":"array","items":{"$ref":"#/components/schemas/RiskLayer"}},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceEntry"}}},"required":["hts","description"]},"SearchResponse":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"schema_version":{"type":"string","example":"2026-07-match-confidence"},"data_version":{"type":"string","example":"hts:2026-02-25 15:50:27"},"data_updated_at":{"type":["string","null"],"example":"2026-02-25 15:50:27"},"last_verified_at":{"type":["string","null"],"example":"2026-08-06T13:02:11.000Z","description":"When the data was last verified against the official USITC source. Unlike data_updated_at, this advances even on days when the source is checked and found unchanged."},"source_edition":{"type":"string","example":"USITC HTS 2026 Basic Edition"},"query":{"type":"string","example":"electric vehicle"},"country":{"type":["string","null"],"example":"CN"},"count":{"type":"integer","example":10},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"required":["api_version","schema_version","data_version","source_edition","query","count","results"]},"TariffQuantity":{"type":"object","required":["amount","unit"],"properties":{"amount":{"type":"number","minimum":0},"unit":{"type":"string","enum":["kg","g","lb","metric_ton","liter","ml","gallon","proof_liter","dozen","pair","head","item","m2","m3"]},"source":{"type":"string"}}},"AdvancedDutyCalculation":{"type":"object","properties":{"status":{"type":"string","enum":["complete","needs_facts","unresolved"]},"sourceExpression":{"type":"string"},"appliedExpression":{"type":"string"},"dutyAmountUsd":{"type":["number","null"]},"effectiveRatePercent":{"type":["number","null"]},"missingFacts":{"type":"array","items":{"type":"object","additionalProperties":true}},"conversions":{"type":"array","items":{"type":"object","additionalProperties":true}},"eligibility":{"type":"object","additionalProperties":true},"appliedTreatment":{"type":"string","enum":["general","preference","in_quota","out_of_quota","seasonal","cross_reference"]}},"required":["status","sourceExpression","appliedExpression","dutyAmountUsd","missingFacts","conversions","appliedTreatment"]},"CalculateRequest":{"type":"object","required":["hts","country","value"],"properties":{"hts":{"type":"string","example":"8471.30.01.00"},"country":{"type":"string","example":"CN"},"value":{"type":"number","description":"Customs (dutiable) value in USD.","example":1000},"mode":{"type":"string","enum":["ocean","air","land","other"],"default":"ocean","description":"Mode of transport. Affects HMF (only applies to ocean)."},"as_of":{"type":"string","format":"date","description":"ISO date for retroactive calculation."},"quantities":{"type":"array","items":{"$ref":"#/components/schemas/TariffQuantity"}},"alcohol_by_volume_percent":{"type":"number","minimum":0,"maximum":100},"product_content":{"type":"object","additionalProperties":{"type":"number"}}}},"CalculateLineItem":{"type":"object","properties":{"kind":{"type":"string","enum":["base_mfn","section_122","section_232","section_301_china","section_301","section_338","ieepa","mpf","hmf"]},"status":{"type":"string","enum":["calculated","needs_facts","not_applied","not_applicable"],"example":"calculated"},"rate_pct":{"type":["number","null"]},"amount_usd":{"type":["number","null"],"example":250},"specific_rates":{"type":"array","items":{"type":"string"}},"label":{"type":["string","null"]},"list":{"type":["string","null"]},"note":{"type":["string","null"]},"calculation":{"$ref":"#/components/schemas/AdvancedDutyCalculation"}},"required":["kind","amount_usd"]},"RiskLayer":{"type":"object","description":"Fact-dependent or non-deterministic duty layer. These are not silently included in deterministic totals; callers need additional importer, producer/exporter, quantity, quota, or certification facts before applying them.","properties":{"kind":{"type":"string","enum":["adcvd","quota_trq","fta_special","exclusion","specific_duty","base_duty","ieepa"]},"status":{"type":"string","enum":["risk","needs_facts","not_applied"]},"label":{"type":"string"},"detail":{"type":"string"},"source":{"type":["string","null"]}},"required":["kind","status","label","detail"]},"CalculateResponse":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"schema_version":{"type":"string","example":"2026-07-match-confidence"},"data_version":{"type":"string","example":"hts:2026-02-25 15:50:27"},"data_updated_at":{"type":["string","null"],"example":"2026-02-25 15:50:27"},"last_verified_at":{"type":["string","null"],"example":"2026-08-06T13:02:11.000Z","description":"When the data was last verified against the official USITC source. Unlike data_updated_at, this advances even on days when the source is checked and found unchanged."},"source_edition":{"type":"string","example":"USITC HTS 2026 Basic Edition"},"hts":{"type":"string"},"description":{"type":"string"},"country":{"type":"string"},"value":{"type":"number"},"mode":{"type":"string"},"as_of":{"type":["string","null"]},"calculation_status":{"type":"string","enum":["complete","incomplete_requires_facts"]},"totals_exclude":{"type":"array","items":{"type":"string","enum":["base_duty"]}},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/CalculateLineItem"}},"total_duty":{"type":["number","null"],"example":350},"total_duty_excluding_specific":{"type":"number","example":350},"total_duty_excluding_unresolved_base":{"type":"number","example":350},"total_fees":{"type":"number","example":33.96},"total_landed":{"type":["number","null"],"example":383.96},"total_landed_excluding_specific":{"type":"number","example":383.96},"effective_rate_pct":{"type":["number","null"],"example":38.395},"effective_rate_pct_excluding_specific":{"type":"number","example":38.395},"warnings":{"type":"array","items":{"type":"string"}},"risk_layers":{"type":"array","items":{"$ref":"#/components/schemas/RiskLayer"}},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceEntry"}}},"required":["hts","country","value","line_items","total_duty","total_fees","total_landed","effective_rate_pct","provenance"]},"AuditLineInput":{"type":"object","required":["hts","country","value","declared_duty"],"properties":{"line_no":{"type":"integer","example":1},"hts":{"type":"string","example":"8471.30.01.00"},"country":{"type":"string","example":"CN"},"value":{"type":"number","example":12500},"freight":{"type":"number"},"mode":{"type":"string","enum":["ocean","air","land","other"]},"declared_duty":{"type":"number","example":1875},"mpf_paid":{"type":"number","example":43.3},"hmf_paid":{"type":"number","example":15.63},"quantities":{"type":"array","items":{"$ref":"#/components/schemas/TariffQuantity"}},"alcohol_by_volume_percent":{"type":"number","minimum":0,"maximum":100},"product_content":{"type":"object","additionalProperties":{"type":"number"}}}},"AuditEntryRequest":{"type":"object","required":["lines"],"properties":{"entry_number":{"type":"string","example":"ABI-12345678-9"},"as_of":{"type":"string","format":"date","example":"2026-04-15"},"mode":{"type":"string","enum":["ocean","air","land","other"]},"lines":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/AuditLineInput"}}}},"AuditLineResult":{"type":"object","properties":{"line_no":{"type":"integer"},"hts":{"type":"string"},"country":{"type":"string"},"expected":{"type":["object","null"],"properties":{"base_mfn":{"type":"number"},"section_122":{"type":"number"},"section_232":{"type":"number"},"section_301":{"type":"number","description":"Section 301 duty for the line's origin (any country scope). section_301_china remains the China-scope mirror."},"section_301_china":{"type":"number"},"section_338":{"type":"number","description":"Section 338 duty on covered products of Canada."},"mpf":{"type":"number"},"hmf":{"type":"number"},"total_duty":{"type":["number","null"]},"total_duty_excluding_specific":{"type":"number"},"total_duty_excluding_unresolved_base":{"type":"number"},"total_landed":{"type":["number","null"]},"total_landed_excluding_specific":{"type":"number"},"total_landed_excluding_unresolved_base":{"type":"number"}}},"declared":{"type":"object","properties":{"duty":{"type":"number"},"mpf":{"type":["number","null"]},"hmf":{"type":["number","null"]}}},"discrepancy":{"type":["number","null"]},"flag":{"type":"string","enum":["match","underpaid","overpaid","needs_facts","error"]},"calculation_status":{"type":"string","enum":["complete","incomplete_requires_facts"]},"totals_exclude":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}},"assurance":{"$ref":"#/components/schemas/TariffAssuranceSnapshot"},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceEntry"}}},"required":["line_no","hts","country","flag","provenance"]},"AuditEntryResponse":{"type":"object","properties":{"entry_number":{"type":["string","null"]},"as_of":{"type":["string","null"]},"audited_lines":{"type":"integer","example":1},"calculation_status":{"type":"string","enum":["complete","incomplete_requires_facts"]},"incomplete_lines":{"type":"integer"},"totals_exclude":{"type":"array","items":{"type":"string"}},"total_declared_duty":{"type":"number","example":1875},"total_expected_duty":{"type":"number","example":2500},"total_discrepancy":{"type":["number","null"],"example":625},"total_underpaid":{"type":"number","example":625},"total_overpaid":{"type":"number","example":0},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AuditLineResult"}}},"required":["audited_lines","calculation_status","incomplete_lines","totals_exclude","total_declared_duty","total_expected_duty","total_discrepancy","total_underpaid","total_overpaid","lines"]},"TariffChangesResponse":{"type":"object","properties":{"api_version":{"type":"string"},"schema_version":{"type":"string"},"count":{"type":"integer"},"next_before":{"type":["string","null"]},"next_before_id":{"type":["string","null"]},"changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["rate_stack_changed","program_coverage_changed","source_coverage_degraded"]},"lane":{"type":"object","properties":{"hts":{"type":"string"},"origin":{"type":"string"}},"required":["hts","origin"]},"changed_layers":{"type":"array","items":{"type":"string"}},"detected_at":{"type":"string"},"acknowledged_at":{"type":["string","null"]},"assigned_to":{"type":["string","null"]},"before":{"anyOf":[{"$ref":"#/components/schemas/TariffAssuranceSnapshot"},{"type":"null"}]},"after":{"anyOf":[{"$ref":"#/components/schemas/TariffAssuranceSnapshot"},{"type":"null"}]}},"required":["id","type","lane","changed_layers","detected_at","before","after"]}}},"required":["api_version","schema_version","count","changes"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"tier":{"type":"string"},"limit":{"type":"number"},"used":{"type":"number"},"docs":{"type":"string","format":"uri"}},"required":["error"]}},"responses":{"BadRequest":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated plan does not include this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"HTS code or path not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Monthly request cap exceeded for this tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}