openapi: 3.1.0
info:
  title: Tandom API
  version: 0.1.0
  x-tandom-status: pre-release
  summary: U.S. customs, tariff, and trade-compliance data and computations.
  description: |
    Tandom's pre-release public API gives U.S. industrial sourcing and import
    teams programmatic access to the live duty, AD/CVD, HTS, PGA, Chapter 99,
    and regulatory-data operations shown in this reference. Public access is
    free under fair-use and endpoint-specific safeguards.

    Use the versioned namespace (`api.tandom.ai/v1/*`) with
    `Authorization: Bearer tk_live_...`. Response fields, citations, warnings,
    pagination, and availability vary by operation; treat each operation's
    schema and status as the source of truth.

    **Postman / Bruno / Insomnia:** import this collection URL —
    `https://docs.tandom.ai/api/postman.json`. The collection is generated
    from this spec at request time, so it stays in sync with whatever you
    see on this page. Folders mirror the OpenAPI tag groupings; request
    cells pre-fill from the spec's example values, runnable without manual
    filling.

    **Pre-release SDKs.** TypeScript and Python clients are vendored in the
    repository for testing and source-based use. They are not yet published to
    npm or PyPI. Source + per-language docs:
    [github.com/tandomai/tandom-app/tree/main/sdks](https://github.com/tandomai/tandom-app/tree/main/sdks).

    **AI agents / LLM tooling.** Machine-readable surfaces follow the
    [llms.txt convention](https://llmstxt.org/):

    - `https://docs.tandom.ai/llms.txt` — short index of every endpoint
      with links to per-operation Markdown.
    - `https://docs.tandom.ai/llms-full.txt` — full Markdown dump of
      the entire reference (single fetch).
    - `https://docs.tandom.ai/api/operations/{operationId}.md` — one
      operation as Markdown (description, parameters, schema, cURL
      example). E.g.,
      `https://docs.tandom.ai/api/operations/calculateDuty.md`.
    - `https://docs.tandom.ai/api/openapi.yaml` and
      `https://docs.tandom.ai/api/openapi.json` — raw spec in either
      serialization.
    - `https://mcp.tandom.ai/mcp` — canonical authenticated remote MCP
      endpoint for compatible clients. The public catalog is read-only.

    **Quick copy.** Paste these URLs into your AI agent (Claude, Cursor,
    custom bots) — click the copy button on the code block:

    ```
    https://docs.tandom.ai/llms-full.txt
    https://docs.tandom.ai/llms.txt
    https://docs.tandom.ai/api/openapi.yaml
    https://mcp.tandom.ai/mcp
    ```

    **Or pipe the full reference straight to your clipboard:**

    ```bash
    # macOS
    curl -sL https://docs.tandom.ai/llms-full.txt | pbcopy

    # Linux (Wayland: wl-copy; X11: xclip -selection clipboard)
    curl -sL https://docs.tandom.ai/llms-full.txt | xclip -selection clipboard
    ```

    See `docs/strategy/API_SURFACE.md` in the repository for the strategic
    catalog. See `docs/products/shared-infrastructure/API_PLATFORM_READINESS.md`
    for platform conventions (rate limits, retries, idempotency, observability).
  contact:
    name: Tandom API support
    email: api@tandom.ai
    url: https://tandom.ai/api
  termsOfService: https://tandom.ai/legal/terms
  license:
    name: Tandom Commercial License
    url: https://tandom.ai/legal/terms
servers:
  - url: https://api.tandom.ai
    description: Production (canonical namespace; routes today still mount under product hosts — see `x-tandom-current-hosts`)
x-tandom-current-hosts:
  - description: Today, AD/CVD Intelligence routes serve from this host. Migrating to api.tandom.ai with INFRA-25.
    url: https://compliance.tandom.ai
  - description: Today, Duty Calculator + HTS reference routes serve from this host.
    url: https://tariffs.tandom.ai
tags:
  - name: Duty Calculation
    description: Full landed-duty stack — MFN + Section 232 + Section 301 + IEEPA + Reciprocal + AD/CVD + Chapter 99 layered into one rate.
  - name: AD/CVD Intelligence
    description: Antidumping and countervailing duty orders, scope analysis, rate history, lifecycle, scope rulings, court decisions.
  - name: HTS Reference
    description: USITC Harmonized Tariff Schedule — search, browse, hierarchy, notes, scope expansions.
  - name: Trade Programs
    description: Partner Government Agency flags, Chapter 99 applicable tariffs, FTA / SPI eligibility (closed beta).
  - name: Catalog
    description: Public HTS catalog used by `tariffs.tandom.ai/catalog/*` — sections, chapters, codes, full-text search.
  - name: Regulatory Data
    description: Dataset freshness signals across HTS, FR, CSMS, S301, S232, AD/CVD, PGA, Trade Programs, Scope Rulings, CIT decisions.
  - name: Agent Interface
    description: JSON-RPC 2.0 MCP (Model Context Protocol) endpoint. Canonical connector URL is https://mcp.tandom.ai/mcp; API-platform URL is https://api.tandom.ai/v1/mcp.
security:
  - bearerAuth: []
paths:
  /v1/duty/calculate:
    get:
      tags:
        - Duty Calculation
      summary: Calculate full landed duty for one HTS line
      description: |
        Returns the full layered duty stack for one HTS code at one origin
        on one entry date: MFN base rate, Section 232, Section 301, IEEPA,
        Reciprocal, AD/CVD, Chapter 99 sources, matched exclusions, split
        lines, and final effective rate.

        Date-aware: pass `date` to resolve rates as-of any historical entry
        date. Conditional fields (`steel`, `aluminum`, `copper`, `meltpour`,
        etc.) trigger Section 232 melt-pour and aluminum-smelt resolution.

        No Claude on the request path — this is a deterministic calculation
        over our pipelined regulatory data.
      operationId: calculateDuty
      parameters:
        - $ref: "#/components/parameters/HtsCode"
        - $ref: "#/components/parameters/Country"
        - name: value
          in: query
          schema:
            type: number
            minimum: 0
          description: Declared value in USD.
        - $ref: "#/components/parameters/EntryDate"
        - name: departure
          in: query
          schema:
            type: string
            format: date
          description: Date of loading (used for some Section 232 melt-pour cutoffs).
        - name: meltpour
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
          description: Country of melt and pour (steel) — ISO 3166-1 alpha-2.
        - name: steel
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Steel content percentage (0–100).
        - name: aluminum
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Aluminum content percentage.
        - name: copper
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Copper content percentage.
        - name: uscontent
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: U.S.-content percentage (used for Section 232 derivative reductions).
        - name: qty
          in: query
          schema:
            type: number
            minimum: 0
          description: Primary quantity (per the HTS unit of measure).
        - name: qty2
          in: query
          schema:
            type: number
            minimum: 0
          description: Secondary quantity (when the HTS row has two UOMs).
        - name: degrees
          in: query
          schema:
            type: number
          description: Alcohol-by-volume / proof / other degree-based fields.
        - name: transport
          in: query
          schema:
            type: string
            enum:
              - ocean
              - air
              - truck
              - rail
          description: Mode of transport — for HMF / MPF eligibility.
        - name: spi
          in: query
          schema:
            type: string
          description: Special Program Indicator (e.g., USMCA, GSP, AGOA).
        - name: exclusions
          in: query
          schema:
            type: string
          description: Comma-separated list of Chapter 99 exclusion codes claimed by the importer.
        - name: trace
          in: query
          schema:
            type: boolean
            default: false
          description: Include verbose computation trace.
        - name: includeLegalNoteRequiredInputs
          in: query
          schema:
            type: boolean
            default: false
          description: Include approved-only HTS legal-note required-fact prompts in dutyInfo.requiredInputs. Non-mutating; duty amounts do not consume these facts yet.
        - name: legalNoteFact.<key>
          in: query
          schema:
            type: string
          description: Optional supplied legal-note fact, keyed by required fact name, used to suppress matching advisory requiredInputs when includeLegalNoteRequiredInputs=true.
        - name: includeLegalNoteRateRuleDiagnostics
          in: query
          schema:
            type: boolean
            default: false
          description: Include approved-only, non-mutating HTS legal-note rate-rule shadow diagnostics.
        - name: includeLegalNoteChapter99ApplicabilityDiagnostics
          in: query
          schema:
            type: boolean
            default: false
          description: Include approved-only, non-mutating HTS legal-note Chapter 99 applicability diagnostics.
        - name: includeLegalNoteQuotaDiagnostics
          in: query
          schema:
            type: boolean
            default: false
          description: Include approved-only, non-mutating HTS legal-note quota diagnostics (surface quota quantity / unit / target codes; engine does not track aggregate quota usage across entries).
        - name: verbose
          in: query
          schema:
            type: boolean
            default: false
          description: Include all warnings + provenance.
      responses:
        "200":
          description: Successful calculation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dutyInfo
                properties:
                  dutyInfo:
                    $ref: "#/components/schemas/DutyInfo"
        "400":
          $ref: "#/components/responses/Problem400"
        "401":
          $ref: "#/components/responses/Problem401"
        "413":
          $ref: "#/components/responses/Problem413"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
    post:
      tags:
        - Duty Calculation
      summary: Calculate full landed duty (POST variant — accepts valuation adjustments)
      description: |
        POST variant of `GET /v1/duty/calculate`. Accepts the same fields
        plus structured first-sale + assists + royalties + selling
        commissions + packing + freight/insurance deductions for full
        valuation adjustment per 19 CFR 152.
      operationId: calculateDutyWithValuation
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - htsCode
              properties:
                htsCode:
                  type: string
                  example: 7307.91.50.10
                countryOfOrigin:
                  type: string
                  example: CN
                declaredValue:
                  type: number
                  example: 10000
                entryDate:
                  type: string
                  format: date
                manufacturerName:
                  type: string
                includeLegalNoteRequiredInputs:
                  type: boolean
                  default: false
                  description: Include approved-only HTS legal-note required-fact prompts in dutyInfo.requiredInputs. Non-mutating; duty amounts do not consume these facts yet.
                legalNoteFacts:
                  type: object
                  additionalProperties:
                    type:
                      - string
                      - number
                      - boolean
                      - "null"
                  description: Caller-supplied legal-note facts keyed by required fact name, used to suppress matching advisory requiredInputs.
                includeLegalNoteRateRuleDiagnostics:
                  type: boolean
                  default: false
                  description: Include approved-only, non-mutating HTS legal-note rate-rule shadow diagnostics.
                includeLegalNoteChapter99ApplicabilityDiagnostics:
                  type: boolean
                  default: false
                  description: Include approved-only, non-mutating HTS legal-note Chapter 99 applicability diagnostics.
                includeLegalNoteQuotaDiagnostics:
                  type: boolean
                  default: false
                  description: Include approved-only, non-mutating HTS legal-note quota diagnostics (surface quota quantity / unit / target codes; engine does not track aggregate quota usage across entries).
                steel:
                  type: number
                  minimum: 0
                  maximum: 100
                aluminum:
                  type: number
                  minimum: 0
                  maximum: 100
                copper:
                  type: number
                  minimum: 0
                  maximum: 100
                meltpourCountry:
                  type: string
                valuation:
                  type: object
                  properties:
                    firstSaleValue:
                      type: number
                    assistsValue:
                      type: number
                    royaltiesValue:
                      type: number
                    sellingCommissions:
                      type: number
                    packingCosts:
                      type: number
                    freightDeduction:
                      type: number
                    insuranceDeduction:
                      type: number
      responses:
        "200":
          description: Successful calculation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dutyInfo
                properties:
                  dutyInfo:
                    $ref: "#/components/schemas/DutyInfo"
        "400":
          $ref: "#/components/responses/Problem400"
        "401":
          $ref: "#/components/responses/Problem401"
        "411":
          $ref: "#/components/responses/Problem411"
        "413":
          $ref: "#/components/responses/Problem413"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/adcvd/check:
    get:
      tags:
        - AD/CVD Intelligence
      summary: Apply AD/CVD orders to a shipment
      description: |
        Given an HTS code + country (+ optional product description /
        manufacturer / exporter / declared value), returns matching AD/CVD
        orders with current rates, scope citations, and AI-driven scope
        analysis.

        Use `stats=true` (no other params) to get dataset-level counts +
        country / heading rollups for the AD/CVD corpus.
      operationId: checkAdcvd
      parameters:
        - name: htsCode
          in: query
          schema:
            type: string
          description: 10-digit HTS code. Required unless stats=true.
        - name: country
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 2
          description: ISO 3166-1 alpha-2. Required unless stats=true.
        - $ref: "#/components/parameters/EntryDate"
        - name: productDescription
          in: query
          schema:
            type: string
          description: Optional — feeds AI scope analysis.
        - name: manufacturer
          in: query
          schema:
            type: string
          description: Optional — used for company-specific rate matching.
        - name: exporter
          in: query
          schema:
            type: string
          description: Optional.
        - name: declaredValue
          in: query
          schema:
            type: number
            minimum: 0
        - name: stats
          in: query
          schema:
            type: boolean
          description: When true, returns dataset-level statistics instead of a lookup.
        - name: refresh
          in: query
          schema:
            type: boolean
            default: false
          description: Bypass response cache.
      responses:
        "200":
          description: Lookup result OR stats payload.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/AdcvdCheckLookup"
                  - $ref: "#/components/schemas/AdcvdCheckStats"
        "400":
          $ref: "#/components/responses/Problem400"
        "401":
          $ref: "#/components/responses/Problem401"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/adcvd/orders:
    get:
      tags:
        - AD/CVD Intelligence
      summary: Search the AD/CVD order catalog
      operationId: searchAdcvdOrders
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Full-text search over scope text + product description.
        - name: country
          in: query
          schema:
            type: string
          description: Filter by country.
        - name: orderType
          in: query
          schema:
            type: string
            enum:
              - AD
              - CVD
        - name: status
          in: query
          schema:
            type: string
            enum:
              - active
              - revoked
              - suspended
            default: active
        - name: hts
          in: query
          schema:
            type: string
          description: Filter to orders covering this 10-digit code.
        - $ref: "#/components/parameters/Cursor"
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Legacy offset-style page number — public /v1/* clients should use ?cursor= instead. Ignored when cursor is supplied.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - orders
                  - total
                  - page
                  - limit
                  - hasMore
                properties:
                  orders:
                    type: array
                    items:
                      $ref: "#/components/schemas/AdcvdOrderSummary"
                  total:
                    type: integer
                  page:
                    type: integer
                  limit:
                    type: integer
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                      - string
                      - "null"
                    description: Opaque cursor for the next page (INFRA-19). Null when no more results.
        "401":
          $ref: "#/components/responses/Problem401"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/adcvd/report:
    post:
      tags:
        - AD/CVD Intelligence
      summary: Full case-by-case AD/CVD analysis
      description: |
        Heavyweight endpoint that fans out across scope analysis, lifecycle,
        and rate history for every matching case. Access is free and subject
        to fair-use and operation-specific safeguards; the service may return
        `429` with retry guidance when capacity limits are reached.

        **Async option (INFRA-39):** pass `async: true` + `webhookUrl` to
        receive the result via webhook instead of waiting for the response.
        We return `202 Accepted` immediately with `{jobId, webhookSecret}`;
        the report is POSTed to your URL once processing finishes (typically
        <60s). The webhook envelope is signed HMAC-SHA256 using the per-job
        secret returned in the 202 response (`X-Tandom-Signature: t=<unix>,v1=<hex>`).
      operationId: generateAdcvdReport
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - htsCode
                - countryOfOrigin
                - productDescription
              properties:
                htsCode:
                  type: string
                  example: 7307.91.50.10
                countryOfOrigin:
                  type: string
                  minLength: 2
                  maxLength: 2
                  example: CN
                productDescription:
                  type: string
                manufacturerName:
                  type: string
                entryDate:
                  type: string
                  format: date
                declaredValue:
                  type: number
                async:
                  type: boolean
                  description: |
                    When true, the report is processed asynchronously. The
                    response is `202 Accepted` with `{jobId, webhookSecret}`;
                    the result is delivered to `webhookUrl` once ready.
                  example: false
                webhookUrl:
                  type: string
                  format: uri
                  description: |
                    Required when `async=true`. HTTPS URL that receives the
                    signed `report.completed` (or `report.failed`) event
                    envelope.
                  example: https://example.com/tandom-webhooks/report
      responses:
        "200":
          description: Report generated (sync path).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdcvdReport"
        "202":
          description: |
            Job enqueued (async path). Result will be delivered to
            `webhookUrl`. `webhookSecret` is shown ONCE — store it to
            verify the eventual signature.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jobId
                  - status
                  - webhookSecret
                properties:
                  jobId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                      - queued
                  webhookSecret:
                    type: string
                    description: Per-job HMAC-SHA256 signing secret. Format `whsec_<32 base62>`.
                  estimatedSeconds:
                    type: integer
                    description: Best-effort latency hint. Real time depends on queue depth.
        "400":
          $ref: "#/components/responses/Problem400"
        "401":
          $ref: "#/components/responses/Problem401"
        "411":
          $ref: "#/components/responses/Problem411"
        "413":
          $ref: "#/components/responses/Problem413"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/adcvd/rates-at:
    get:
      tags:
        - AD/CVD Intelligence
      summary: Point-in-time rate query
      description: |
        Returns the rate that was in effect for a specific case (and
        optionally a specific company) on a specific date — useful for
        historical entry reconciliation.
      operationId: getAdcvdRateAtDate
      parameters:
        - name: case
          in: query
          required: true
          schema:
            type: string
            pattern: ^[A-C]-\d{3}-\d{3}$
          example: A-570-001
        - name: date
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: rateType
          in: query
          schema:
            type: string
            enum:
              - country_wide
              - all_others
              - company_specific
        - name: company
          in: query
          schema:
            type: string
          description: Partial match on company_name or company_suffix.
      responses:
        "200":
          description: Rate found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdcvdRateAtDate"
        "400":
          $ref: "#/components/responses/Problem400"
        "404":
          $ref: "#/components/responses/Problem404"
        "429":
          $ref: "#/components/responses/Problem429"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/hts/search:
    get:
      tags:
        - HTS Reference
      summary: Full-text HTS search
      operationId: searchHts
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 2
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 30
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Matching HTS rows.
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                  - query
                  - count
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/HtsRow"
                  query:
                    type: string
                  count:
                    type: integer
                  nextCursor:
                    type:
                      - string
                      - "null"
                    description: Opaque cursor for the next page (INFRA-19). True cursor pagination — `WHERE htsno > $cursor` — stable under concurrent writes. Null when no more results.
        "400":
          $ref: "#/components/responses/Problem400"
        "500":
          $ref: "#/components/responses/Problem500"
      x-tandom-status: available
  /v1/hts/notes:
    get:
      tags:
        - HTS Reference
      summary: Section / chapter / subheading notes
      operationId: getHtsNotes
      parameters:
        - name: htsCode
          in: query
          schema:
            type: string
          description: Pass either htsCode OR chapter.
        - name: chapter
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 99
      responses:
        "200":
          description: Notes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    description: Source backend used for the note response.
                  requiredFacts:
                    type: array
                    description: Approved legal-note semantic facts that may be needed before relying on the note. These are retrieval/display signals only; they do not mutate duty calculations.
                    items:
                      type: object
                      properties:
                        noteId:
                          type: string
                        effectId:
                          type: string
                        requiredFactKey:
                          type: string
                        effectType:
                          type: string
                        conditionText:
                          type:
                            - string
                            - "null"
                        effectValueText:
                          type:
                            - string
                            - "null"
                        sourceLocator:
                          type:
                            - string
                            - "null"
                        sourceSpan:
                          type: string
                  notes:
                    type: array
                    items:
                      type: object
                      properties:
                        note:
                          type: string
                        source:
                          type: string
                          example: Section XV Note 1(f)
                        effect:
                          type: string
                          enum:
                            - applies
                            - excludes
                            - redirects
                        effects:
                          type: array
                          description: Approved semantic effects by default. Unreviewed effects are blocked from the public runtime endpoint.
                          items:
                            type: object
                        requiredFacts:
                          type: array
                          description: Approved required-fact signals for this note.
                          items:
                            type: object
      x-tandom-status: available
  /v1/hts/browse:
    get:
      tags:
        - HTS Reference
      summary: Enumerate HTS codes by chapter or parent prefix
      description: Pass `chapter`, OR `parent` (prefix), OR neither (returns chapters list).
      operationId: browseHts
      parameters:
        - name: chapter
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 99
        - name: parent
          in: query
          schema:
            type: string
          description: HTS prefix to enumerate children below.
      responses:
        "200":
          description: Hierarchical results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  level:
                    type: string
                    enum:
                      - root
                      - chapter
                      - code
                  chapter:
                    type: integer
                  parent:
                    type: string
                  ancestors:
                    type: array
                    items:
                      type: object
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/HtsRow"
                  count:
                    type: integer
      x-tandom-status: available
  /v1/hts/hierarchy:
    get:
      tags:
        - HTS Reference
      summary: Walk parents / children for one code
      operationId: getHtsHierarchy
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
            minLength: 4
      responses:
        "200":
          description: Hierarchy breadcrumb.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  breadcrumb:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        description:
                          type: string
                        indent:
                          type: integer
      x-tandom-status: available
  /v1/pga/check:
    get:
      tags:
        - Trade Programs
      summary: Partner Government Agency flags for an HTS code
      description: |
        Returns flags by agency (FDA, EPA, USDA, FCC, NHTSA, CPSC, etc.)
        for a given HTS code. Pass `agencies=true` (no htsCode) to list all
        recognized PGA agencies + their programs.
      operationId: checkPga
      parameters:
        - name: htsCode
          in: query
          schema:
            type: string
          description: Required unless agencies=true.
        - name: description
          in: query
          schema:
            type: string
          description: Optional — refines flag matching.
        - name: includeWoodPackaging
          in: query
          schema:
            type: boolean
            default: true
        - name: agencies
          in: query
          schema:
            type: boolean
            default: false
          description: List agencies + programs instead of flag-checking.
      responses:
        "200":
          description: Flags or agency directory.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PgaCheckResult"
                  - $ref: "#/components/schemas/PgaAgenciesResult"
        "400":
          $ref: "#/components/responses/Problem400"
      x-tandom-status: available
  /v1/chapter99/applicable:
    get:
      tags:
        - Trade Programs
      summary: Chapter 99 applicable tariffs for an HTS code + country
      operationId: getChapter99Applicable
      parameters:
        - name: htsCode
          in: query
          required: true
          schema:
            type: string
        - name: country
          in: query
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: debug
          in: query
          schema:
            type: boolean
            default: false
        - name: refresh
          in: query
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Applicable Chapter 99 tariffs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  htsCode:
                    type: string
                  country:
                    type: string
                  applicableTariffs:
                    type: array
                    items:
                      $ref: "#/components/schemas/Chapter99Tariff"
                  matchedExclusions:
                    type: array
                    items:
                      type: object
                  totalAdditionalRate:
                    type: number
                  source:
                    type: string
                  codeCount:
                    type: integer
      x-tandom-status: available
  /v1/catalog/search:
    get:
      tags:
        - Catalog
      summary: Full-text catalog search
      operationId: searchCatalog
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 2
        - name: chapter
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 99
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: pga
          in: query
          schema:
            type: string
          description: Filter by PGA agency code (e.g., FDA).
        - name: adcvd
          in: query
          schema:
            type: string
            enum:
              - "true"
              - "false"
          description: Filter to codes with / without AD/CVD coverage.
      responses:
        "200":
          description: Catalog rows + offset pagination meta.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/CatalogCode"
                        - type: object
                          properties:
                            href:
                              type: string
                              description: Customer-facing catalog URL for this search result.
                              example: /hts-catalog/chapter/85#8517
                  meta:
                    type: object
                    properties:
                      query:
                        type: string
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
                      filters:
                        type: object
                        properties:
                          chapter:
                            type: integer
                          pga:
                            type: string
                          adcvd:
                            type: string
      x-tandom-status: available
  /v1/catalog/sections:
    get:
      tags:
        - Catalog
      summary: List HTS sections + their chapters
      operationId: listCatalogSections
      responses:
        "200":
          description: Sections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        number:
                          type: integer
                        numeral:
                          type: string
                          example: XV
                        title:
                          type: string
                        chapters:
                          type: array
                          items:
                            type: object
                            properties:
                              number:
                                type: integer
                              title:
                                type: string
      x-tandom-status: available
  /v1/catalog/chapters/{chapter}:
    get:
      tags:
        - Catalog
      summary: List codes in one chapter
      operationId: getCatalogChapter
      parameters:
        - name: chapter
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 99
      responses:
        "200":
          description: Chapter detail.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      chapter:
                        type: integer
                      title:
                        type: string
                      section:
                        type:
                          - object
                          - "null"
                        properties:
                          number:
                            type: integer
                          numeral:
                            type: string
                          title:
                            type: string
                      codes:
                        type: array
                        items:
                          $ref: "#/components/schemas/HtsRow"
                      notes:
                        type: array
                        items:
                          type: object
                      codeCount:
                        type: integer
      x-tandom-status: available
  /v1/catalog/codes/{code}:
    get:
      tags:
        - Catalog
      summary: Full detail for one HTS code
      operationId: getCatalogCode
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
            minLength: 4
          example: 7307.91.50.10
      responses:
        "200":
          description: Code detail.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/CatalogCode"
        "404":
          $ref: "#/components/responses/Problem404"
      x-tandom-status: available
  /v1/regulatory-data/status:
    get:
      tags:
        - Regulatory Data
      summary: Dataset freshness signals
      description: |
        Per-dataset health (HTSUS, FR, CSMS, S301, S232, AD/CVD, PGA, Trade
        Programs, Scope Rulings, CIT decisions) — last refreshed timestamp,
        record counts, coverage window.

        **Auth-optional, unmetered.** Free public freshness signal.
      operationId: getRegulatoryDataStatus
      security: []
      parameters:
        - name: pgaCounts
          in: query
          schema:
            type: boolean
          description: Include PGA record counts by agent.
      responses:
        "200":
          description: Dataset status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  datasets:
                    type: array
                    items:
                      $ref: "#/components/schemas/RegulatoryDataset"
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      healthy:
                        type: integer
                      stale:
                        type: integer
                      error:
                        type: integer
                      unknown:
                        type: integer
                  pgaCountsByAgent:
                    type: object
                    additionalProperties:
                      type: integer
      x-tandom-status: available
  /v1/mcp:
    get:
      tags:
        - Agent Interface
      summary: MCP server info + tool catalog
      operationId: getMcpInfo
      responses:
        "200":
          description: MCP server descriptor.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  version:
                    type: string
                  description:
                    type: string
                  tools:
                    type: array
                    items:
                      type: object
                  usage:
                    type: object
      x-tandom-status: available
    post:
      tags:
        - Agent Interface
      summary: JSON-RPC 2.0 entry point
      description: |
        JSON-RPC 2.0 MCP (Model Context Protocol) endpoint. The canonical
        connector URL is `https://mcp.tandom.ai/mcp`; this API-platform
        URL remains supported at `https://api.tandom.ai/v1/mcp`.

        The MCP `tools/list` result only includes callable tools. The
        official connector roadmap mirrors the broader REST surface as
        tools as each REST-backed tool adapter ships. Methods:

        - `initialize` — handshake; returns server capabilities.
        - `tools/list` — enumerate available tools.
        - `tools/call` — invoke a tool by name with arguments.
      operationId: callMcp
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: JSON-RPC response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
      x-tandom-status: available
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_<32 base62 chars>
      description: |
        Tandom-issued API key. Format: `tk_live_` (production) or
        `tk_test_` (sandbox / fixture-backed responses) followed by
        32 base62 characters (40 chars total). Issue and manage at
        `https://tandom.ai/account/api-keys`.
  parameters:
    HtsCode:
      name: hts
      in: query
      required: true
      schema:
        type: string
        pattern: ^\d{4}(\.\d{2}){0,3}$
      example: 7307.91.50.10
      description: 10-digit HTS code (dotted form accepted).
    Country:
      name: origin
      in: query
      schema:
        type: string
        minLength: 2
        maxLength: 2
      example: CN
      description: ISO 3166-1 alpha-2 country code.
    EntryDate:
      name: date
      in: query
      schema:
        type: string
        format: date
      example: 2026-04-30
      description: Entry date (YYYY-MM-DD). Resolves rates / scope / eligibility as-of this date. Defaults to today.
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: |
        INFRA-19 — opaque cursor for the next page. Pass the `nextCursor`
        from the previous response. Cursors are opaque; treat them as
        black boxes — the internal payload may evolve without breaking
        the wire format. Mutually exclusive with offset-style `?page=`
        on legacy endpoints — public /v1/* clients should always use
        cursors.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: |
        INFRA-19 — Stripe-style idempotency. Send a unique opaque value
        (e.g., a UUID) per logical request. Replaying the same key
        within 24h returns the cached response — same status, same
        body — and the response carries `Idempotent-Replayed: true`.
        Different keys (or the same key after 24h) execute fresh. The
        replay scope is bound to the key+method+path tuple, so reusing
        a value across endpoints is safe (it just won't replay).
        Stored hashed; the plaintext header value never persists.
  responses:
    Problem400:
      description: Bad request — invalid or missing parameters.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem401:
      description: Unauthorized — missing or invalid Bearer token.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem403:
      description: Forbidden — token lacks the required scope.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem404:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem411:
      description: Length Required — POST/PUT/PATCH must include a Content-Length header.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem413:
      description: Payload too large — request body exceeds the per-route cap (default 1 MiB).
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem429:
      description: |
        Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`,
        `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the limiter window resets.
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix epoch (seconds) when the bucket resets.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Problem500:
      description: Internal server error.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    Money:
      type: object
      description: |
        Canonical currency-amount shape (INFRA-24). Every monetary value
        on the public surface is returned as `{ value, currency }` so
        consumers can scale to multi-currency without a versioning
        break. Phase 1 supports USD only; `value` is rounded to 2
        decimal places.
      required:
        - value
        - currency
      properties:
        value:
          type: number
          description: Decimal currency value, rounded to 2 dp.
          example: 1234.56
        currency:
          type: string
          enum:
            - USD
          description: ISO 4217 currency code. USD only in Phase 1.
    ConfidenceLevel:
      type: string
      enum:
        - high
        - medium
        - low
        - unclassified
      description: |
        Tier label derived from `confidenceScore` (INFRA-23). Mapping:
          - `high`         — score ≥ 0.85 — automated decision is safe.
          - `medium`       — 0.60 ≤ score < 0.85 — review recommended.
          - `low`          — 0.40 ≤ score < 0.60 — manual classification needed.
          - `unclassified` — score < 0.40 — system could not produce a usable answer.
    ConfidenceScore:
      type: number
      minimum: 0
      maximum: 1
      description: |
        Numeric confidence in the classification, from 0 (no signal)
        to 1 (perfect match). Use this when you need to make
        threshold-based decisions; use `confidenceLevel` for
        human-readable display. Both fields are populated on every
        classification response.
      example: 0.92
    Problem:
      type: object
      description: RFC 7807 Problem Details. Returned for every 4xx/5xx response.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          example: tandom://errors/validation
          description: URI identifying the problem type.
        title:
          type: string
          example: Invalid request
        status:
          type: integer
          format: int32
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          description: URI of the specific request that triggered this error.
        traceId:
          type: string
          description: Per-request trace ID echoed in the X-Tandom-Trace-Id response header. Use this to correlate with logs and Sentry.
    Currency:
      type: object
      description: Monetary value. Always USD today; the shape is forward-compatible with multi-currency.
      required:
        - value
        - currency
      properties:
        value:
          type: number
          example: 25.5
        currency:
          type: string
          enum:
            - USD
          example: USD
    Citation:
      type: object
      description: Reference to a primary U.S. legal source. At least one of the URL fields will be populated.
      properties:
        frDocumentNumber:
          type: string
          example: 2025-12345
        frCitation:
          type: string
          example: 90 FR 1234
        frCitationUrl:
          type: string
          format: uri
        csmsId:
          type: string
          example: "54321"
        crossRulingId:
          type: string
          example: N321456
        proclamationNumber:
          type: string
          example: "11021"
        eoNumber:
          type: string
          example: "14257"
        cfrSection:
          type: string
          example: 19 CFR 351.213(d)
        htsno:
          type: string
    Confidence:
      type: object
      description: AI-derived confidence + reasoning. Returned alongside any field that involved a model.
      required:
        - score
        - tier
      properties:
        score:
          type: number
          minimum: 0
          maximum: 1
        tier:
          type: string
          enum:
            - high
            - medium
            - low
        reasoning:
          type: string
        supportingPhrases:
          type: array
          items:
            type: string
          description: Verbatim quotes from the primary source.
    Meta:
      type: object
      properties:
        traceId:
          type: string
          description: Echoes X-Tandom-Trace-Id; useful for correlating with logs and Sentry.
        dataFreshness:
          type: object
          description: Per-dataset freshness signals for sources consulted in this response.
          additionalProperties:
            type: object
            properties:
              lastRefreshed:
                type: string
                format: date-time
              health:
                type: string
                enum:
                  - healthy
                  - stale
                  - error
                  - unknown
    DutyInfo:
      type: object
      description: Full layered duty stack for one HTS line.
      properties:
        htsCode:
          type: string
        description:
          type: string
        unit:
          type: string
        generalRate:
          type: string
          description: MFN base rate (HTSUS Column 1 General).
        specialRates:
          type: array
          items:
            type: object
            properties:
              spi:
                type: string
              rate:
                type: string
        column2Rate:
          type: string
        section232:
          type: string
          description: Steel / aluminum / copper / etc. additional rate.
        section301:
          type: string
          description: Section 301 List 1–4 additional rate.
        ieepaRate:
          type: string
        reciprocalRate:
          type: string
        adCvdRate:
          type: string
        adcvdCases:
          type: array
          items:
            $ref: "#/components/schemas/AdcvdMatch"
        chapter99Sources:
          type: array
          items:
            $ref: "#/components/schemas/Chapter99Tariff"
        matchedExclusions:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
              confidence:
                type: number
        splitLines:
          type: array
          items:
            type: object
            properties:
              lineType:
                type: string
              value:
                $ref: "#/components/schemas/Currency"
              mfnRate:
                type: string
              chapter99Layers:
                type: array
                items:
                  type: object
        valuationAdjustments:
          type: object
          description: Adjustments per 19 CFR 152 — first-sale, assists, royalties, packing, freight/insurance deductions.
        landedCost:
          $ref: "#/components/schemas/Currency"
        estimatedTotalDuty:
          $ref: "#/components/schemas/Currency"
        totalDutyAmount:
          $ref: "#/components/schemas/Currency"
        effectiveRate:
          type: number
          description: Final ad-valorem rate applied (sum of all layers).
        calculationComplete:
          type: boolean
        requiredInputs:
          type: array
          description: Inputs the engine needs or recommends. Legal-note entries are advisory and only emitted when includeLegalNoteRequiredInputs=true.
          items:
            type: object
            required:
              - field
              - type
              - severity
              - reason
            properties:
              field:
                type: string
              type:
                type: string
                enum:
                  - number
                  - string
                  - iso2_country
                  - iso_date
                  - boolean
              unit:
                type: string
              min:
                type: number
              max:
                type: number
              severity:
                type: string
                enum:
                  - blocking
                  - advisory
              reason:
                type: string
              citation:
                type: string
              exampleValue:
                type:
                  - string
                  - number
                  - boolean
        warnings:
          type: array
          items:
            type: string
        legalNoteRateRuleDiagnostics:
          type: array
          description: Approved-only HTS legal-note rate-rule diagnostics. Evidence only; duty arithmetic does not consume this field.
          items:
            type: object
            required:
              - effectId
              - noteId
              - effectType
              - reviewStatus
              - sourceSpan
              - applicability
              - parityStatus
              - blockedByFacts
            properties:
              effectId:
                type: string
              noteId:
                type: string
              effectType:
                type: string
                enum:
                  - rate_rule
              reviewStatus:
                type: string
                enum:
                  - approved
              sourceLocator:
                type:
                  - string
                  - "null"
              sourceSpan:
                type: string
              effectValueText:
                type:
                  - string
                  - "null"
              conditionText:
                type:
                  - string
                  - "null"
              requiredFactKey:
                type:
                  - string
                  - "null"
              ratePercent:
                type:
                  - number
                  - "null"
              quantityValue:
                type:
                  - number
                  - "null"
              quantityUnit:
                type:
                  - string
                  - "null"
              applicability:
                type: string
                enum:
                  - matched
                  - not_matched
                  - unknown
              parityStatus:
                type: string
                enum:
                  - already_accounted_for
                  - not_accounted_for
                  - not_evaluable
              blockedByFacts:
                type: array
                items:
                  type: string
        legalNoteChapter99ApplicabilityDiagnostics:
          type: array
          description: Approved-only HTS legal-note Chapter 99 applicability diagnostics. Evidence only; duty arithmetic does not consume this field.
          items:
            type: object
            required:
              - effectId
              - noteId
              - effectType
              - reviewStatus
              - sourceSpan
              - targetChapter99Codes
              - applicability
              - parityStatus
              - blockedByFacts
              - blockedByReview
            properties:
              effectId:
                type: string
              noteId:
                type: string
              effectType:
                type: string
                enum:
                  - chapter_99_applicability
              reviewStatus:
                type: string
                enum:
                  - approved
              sourceLocator:
                type:
                  - string
                  - "null"
              sourceSpan:
                type: string
              effectValueText:
                type:
                  - string
                  - "null"
              conditionText:
                type:
                  - string
                  - "null"
              requiredFactKey:
                type:
                  - string
                  - "null"
              countryCodes:
                type: array
                items:
                  type: string
              targetChapter99Codes:
                type: array
                items:
                  type: string
              exceptionChapter99Codes:
                type: array
                items:
                  type: string
              conditionHtsTargets:
                type: array
                items:
                  type: string
              applicability:
                type: string
                enum:
                  - matched
                  - not_matched
                  - unknown
              parityStatus:
                type: string
                enum:
                  - already_accounted_for
                  - not_accounted_for
                  - blocked_by_reference_review
                  - not_evaluable
              blockedByFacts:
                type: array
                items:
                  type: string
              blockedByReview:
                type: array
                items:
                  type: string
        legalNoteQuotaDiagnostics:
          type: array
          description: Approved-only HTS legal-note quota diagnostics. Surface the quota quantity / unit / target codes so consumers can cross-check aggregate quota usage; the engine does not track aggregate quota across entries, and duty arithmetic does not consume this field.
          items:
            type: object
            required:
              - effectId
              - noteId
              - effectType
              - reviewStatus
              - sourceSpan
              - targetCodes
              - applicability
              - applicabilityReason
              - notice
            properties:
              effectId:
                type: string
              noteId:
                type: string
              effectType:
                type: string
                enum:
                  - quota
              reviewStatus:
                type: string
                enum:
                  - approved
              sourceLocator:
                type:
                  - string
                  - "null"
              sourceSpan:
                type: string
              effectValueText:
                type:
                  - string
                  - "null"
              conditionText:
                type:
                  - string
                  - "null"
              requiredFactKey:
                type:
                  - string
                  - "null"
              quotaQuantity:
                type:
                  - number
                  - "null"
              quotaUnit:
                type:
                  - string
                  - "null"
              targetCodes:
                type: array
                items:
                  type: string
              countryCodes:
                type: array
                items:
                  type: string
              programIndicators:
                type: array
                items:
                  type: string
              applicability:
                type: string
                enum:
                  - matched
                  - not_matched
                  - unknown
              applicabilityReason:
                type: string
              notice:
                type: string
                enum:
                  - engine_does_not_track_aggregate_quota_usage
                  - diagnostic_only_not_used_for_amount_computation
                description: Reminder that the diagnostic is advisory; aggregate quota usage tracking is the consumer's responsibility.
        provenance:
          type: object
          description: Per-rate citations (which FR notice / EO / Proclamation each layer came from).
        _meta:
          $ref: "#/components/schemas/Meta"
    AdcvdMatch:
      type: object
      properties:
        caseNumber:
          type: string
          example: A-570-983
        orderType:
          type: string
          enum:
            - AD
            - CVD
        product:
          type: string
        country:
          type: string
        countryCode:
          type: string
        rate:
          type: string
          description: Display rate string (may include "%", "Bonded", etc.).
        parsedRate:
          type: number
          description: Numeric ad-valorem rate when expressible.
        amount:
          $ref: "#/components/schemas/Currency"
        matchType:
          type: string
          enum:
            - exact
            - heading
            - scope_text
            - ai_inferred
        headingMatched:
          type: string
        scopeText:
          type: string
          description: Full scope text from the FR notice.
        scopeAnalysis:
          type: object
          properties:
            determination:
              type: string
              enum:
                - likely_in_scope
                - possibly_in_scope
                - likely_out_of_scope
            confidence:
              $ref: "#/components/schemas/Confidence"
        respondentRate:
          type: object
          description: Per 19 CFR 351.107 — separate rate vs all-others vs country-wide.
        effectiveDate:
          type: string
          format: date
        frCitation:
          $ref: "#/components/schemas/Citation"
    AdcvdOrderSummary:
      type: object
      properties:
        caseNumber:
          type: string
        orderType:
          type: string
          enum:
            - AD
            - CVD
        productDescription:
          type: string
        country:
          type: string
        countryCode:
          type: string
        status:
          type: string
          enum:
            - active
            - revoked
            - suspended
        countryWideRate:
          type: string
        countryWideRatePct:
          type: number
        effectiveDate:
          type: string
          format: date
        companionCaseNumber:
          type: string
        htsCodes:
          type: array
          description: |
            Native-granularity HTS codes the order's scope cites (USITC dotted form,
            4/6/8/10-digit). Single source of truth for HTS coverage on AD/CVD orders
            (Engine 0.121 / #146 — Haiku is the sole writer via this column).
            Prefer this over `htsHeadings` for new clients.
          items:
            type: string
          example:
            - "7610.10"
            - "7610.90"
            - "7615.20"
        htsHeadings:
          type: array
          description: |
            4-digit HTSUS headings the order covers, derived server-side from
            `htsCodes` via the `hts_products` hierarchy. Kept for back-compat
            (Triage 0.164 — EPIC 12 Story 1 Phase 2 soft migration). New clients
            should read `htsCodes` directly.
          items:
            type: string
          example:
            - "7610"
            - "7615"
        frCitation:
          $ref: "#/components/schemas/Citation"
          description: Order-establishment FR citation (the document that initiated the order).
        rateFrCitation:
          type:
            - string
            - "null"
          description: |
            Rate-establishment FR citation (the document that set the
            current `countryWideRate`). Often differs from `frCitation` —
            e.g., the order was established by a 2015 sunset review but
            the current rate comes from a 2025 administrative review.
            Brokers should consult both.
          example: 91 FR 5717
        rateFrDocumentNumber:
          type:
            - string
            - "null"
          description: |
            Federal Register document_number (form `YYYY-NNNNNN`) for the
            rate-setting FR doc. Sister to `rateFrCitation` (text form).
            When present, callers should build the FR URL as
            `https://www.federalregister.gov/d/<value>` — this is the
            safe per-document permalink. The `/citation/<vol>-FR-<page>`
            form derived from `rateFrCitation` is risky: it resolves to
            whichever document starts on that page, which can be a
            different agency's notice. NULL for ~80% of orders today;
            populated as cascade ingest covers the rate-setting FR cohort.
          example: 2024-00396
        searchRank:
          type: number
          description: Full-text relevance rank when q is provided.
    AdcvdCheckLookup:
      type: object
      required:
        - matches
        - dataSource
      properties:
        matches:
          type: array
          items:
            $ref: "#/components/schemas/AdcvdMatch"
        pendingInvestigations:
          type: array
          items:
            type: object
        dataSource:
          type: string
        _meta:
          $ref: "#/components/schemas/Meta"
    AdcvdCheckStats:
      type: object
      required:
        - dataSource
        - totalOrders
      properties:
        dataSource:
          type: string
        totalOrders:
          type: integer
        byType:
          type: object
          properties:
            AD:
              type: integer
            CVD:
              type: integer
        byCountry:
          type: object
          additionalProperties:
            type: integer
        byHeading:
          type: object
          additionalProperties:
            type: integer
        countries:
          type: array
          items:
            type: string
        headings:
          type: array
          items:
            type: string
    AdcvdReport:
      type: object
      properties:
        id:
          type: string
          format: uuid
        inputs:
          type: object
        lookupResult:
          $ref: "#/components/schemas/AdcvdCheckLookup"
        cases:
          type: array
          items:
            type: object
        totalADRate:
          type: number
        totalCVDRate:
          type: number
        totalCombinedRate:
          type: number
        riskFlags:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              caseNumber:
                type: string
              description:
                type: string
              severity:
                type: string
                enum:
                  - low
                  - medium
                  - high
        warnings:
          type: array
          items:
            type: string
        dataSnapshotVersion:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        stored:
          type: boolean
        appliedManufacturerSnapshot:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/AppliedManufacturerSnapshot"
          description: |
            Matched RespondentRateMatch for the saved report's selected
            case at save time, per 19 CFR 351.107 (combination >
            exporter > producer). Targets the 2024 CBP MID-rate-mismatch
            enforcement program. NULL when no manufacturer/exporter was
            supplied or no match resolved.
        csmsMessagesSnapshot:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/CsmsMessageSnapshot"
          description: |
            CBP CSMS messages on file for the saved report's selected
            case at save time. Operational rate authority between FR
            notices. NULL on rows saved before PR #804 shipped; capped
            at 50 most-recent messages on save.
    AppliedManufacturerSnapshot:
      type: object
      properties:
        companyName:
          type: string
        counterpartyName:
          type:
            - string
            - "null"
          description: Paired entity when matchKind=combination.
        matchKind:
          type: string
          enum:
            - combination
            - exporter
            - producer
            - producer_or_exporter
          description: 19 CFR 351.107 bucket the row resolved against.
        ratePercent:
          type: number
        rateText:
          type: string
          example: 4.64%
        effectiveDate:
          type:
            - string
            - "null"
          format: date
        sourceFrCitation:
          type:
            - string
            - "null"
        frDocumentNumber:
          type:
            - string
            - "null"
        sourceType:
          type:
            - string
            - "null"
          description: extraction_method tag from adcvd_deposit_rates.
        matchScore:
          type: number
          description: Fuzzy-matcher score (0–1).
    CsmsMessageSnapshot:
      type: object
      properties:
        csms_id:
          oneOf:
            - type: string
            - type: integer
        subject:
          type: string
        body_text:
          type:
            - string
            - "null"
        category:
          type:
            - string
            - "null"
        published_at:
          type:
            - string
            - "null"
          format: date-time
        is_aliwe:
          type:
            - boolean
            - "null"
        extracted_case_numbers:
          type:
            - array
            - "null"
          items:
            type: string
    AdcvdRateAtDate:
      type: object
      properties:
        caseNumber:
          type: string
        rateType:
          type: string
          enum:
            - country_wide
            - all_others
            - company_specific
        ratePercent:
          type: number
        effectiveDate:
          type: string
          format: date
        companyName:
          type: string
        companySuffix:
          type: string
        eventType:
          type: string
          description: e.g., initiation, preliminary, final, admin-review, sunset, revocation.
        reviewPeriod:
          type: string
        frCitation:
          $ref: "#/components/schemas/Citation"
        frDocumentNumber:
          type: string
        sourceType:
          type: string
        confidence:
          $ref: "#/components/schemas/Confidence"
        rateAppliesTo:
          type: string
        combinationCounterparty:
          type: string
          description: For combination rates (e.g., specific exporter + specific producer).
        asOfDate:
          type: string
          format: date
    HtsRow:
      type: object
      properties:
        htsno:
          type: string
          example: 7307.91.50.10
        indent:
          type: integer
          description: Indent level in the HTSUS hierarchy.
        description:
          type: string
        general:
          type: string
          description: Column 1 General (MFN) rate.
        special:
          type: string
          description: Column 1 Special (FTAs / SPIs).
        other:
          type: string
          description: Column 2 (statutory) rate.
        units:
          type: string
          description: Unit of quantity.
        chapter:
          type: integer
    CatalogCode:
      allOf:
        - $ref: "#/components/schemas/HtsRow"
        - type: object
          description: HTS row with extended catalog metadata.
    PgaCheckResult:
      type: object
      properties:
        htsCode:
          type: string
        description:
          type: string
        flags:
          type: array
          items:
            type: object
            properties:
              flagName:
                type: string
              status:
                type: string
              agency:
                type: string
              programCode:
                type: string
              severity:
                type: string
                enum:
                  - info
                  - warn
                  - restrict
              requiredDocuments:
                type: array
                items:
                  type: string
        summary:
          type: object
          properties:
            hasRestrictions:
              type: boolean
            agencies:
              type: array
              items:
                type: string
    PgaAgenciesResult:
      type: object
      properties:
        agencies:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: FDA
              name:
                type: string
              parent:
                type: string
                description: Parent department, e.g., HHS.
              programs:
                type: array
                items:
                  type: object
    Chapter99Tariff:
      type: object
      properties:
        code:
          type: string
          example: 9903.81.91
        authority:
          type: string
          description: e.g., Section 232 (Steel), Section 301 List 4A, IEEPA.
        rate:
          type: string
        amount:
          $ref: "#/components/schemas/Currency"
        citation:
          $ref: "#/components/schemas/Citation"
    RegulatoryDataset:
      type: object
      properties:
        name:
          type: string
          example: AD/CVD orders
        recordCount:
          type: integer
        freshness:
          type: string
          format: date-time
        health:
          type: string
          enum:
            - healthy
            - stale
            - error
            - unknown
        sourceVersion:
          type: string
        sourceDate:
          type: string
        parseSuccess:
          type: boolean
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
        method:
          type: string
          enum:
            - initialize
            - tools/list
            - tools/call
        params:
          type: object
          description: "Method-specific parameters. For tools/call: { name: string, arguments: object }."
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
            - type: "null"
        result:
          type: object
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              type: object
