# Tandom API — full reference > U.S. customs, tariff, and trade-compliance data for AI agents and integrators. This file follows the [llms.txt convention](https://llmstxt.org/) — a structured index of the Tandom API, intended for LLM-driven dev tools (Claude, Cursor, Cody, custom agents) to consume without scraping HTML. - Hosted reference (Scalar): https://docs.tandom.ai/api - OpenAPI spec (JSON): https://docs.tandom.ai/api/openapi.json - OpenAPI spec (YAML): https://docs.tandom.ai/api/openapi.yaml - Postman collection: https://docs.tandom.ai/api/postman.json - Full Markdown dump: https://docs.tandom.ai/api/llms-full.txt **Authentication.** Every request needs `Authorization: Bearer tk_live_<32_chars>`. Get a key at https://tandom.ai/account/api-keys. **Errors.** All 4xx/5xx responses are RFC 7807 `application/problem+json` with `{ type, title, status, detail }`. Rate-limited responses (429) carry `Retry-After` + `X-RateLimit-*` headers. **Citations.** Every endpoint that returns rates, scope, or determinations also returns citations to the authoritative U.S. legal source (Federal Register, Commerce, USITC, court decisions). Every AI-derived field carries confidence + reasoning + verbatim supporting phrases. --- # Tag: Duty Calculation Full landed-duty stack — MFN + Section 232 + Section 301 + IEEPA + Reciprocal + AD/CVD + Chapter 99 layered into one rate. # calculateDuty — Calculate full landed duty for one HTS line `GET /v1/duty/calculate` **Tags:** Duty Calculation **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `hts` | query | string | yes | 10-digit HTS code (dotted form accepted). | | `origin` | query | string | no | ISO 3166-1 alpha-2 country code. | | `value` | query | number | no | Declared value in USD. | | `date` | query | string | no | Entry date (YYYY-MM-DD). Resolves rates / scope / eligibility as-of this date. Defaults to today. | | `departure` | query | string | no | Date of loading (used for some Section 232 melt-pour cutoffs). | | `meltpour` | query | string | no | Country of melt and pour (steel) — ISO 3166-1 alpha-2. | | `steel` | query | number | no | Steel content percentage (0–100). | | `aluminum` | query | number | no | Aluminum content percentage. | | `copper` | query | number | no | Copper content percentage. | | `uscontent` | query | number | no | U.S.-content percentage (used for Section 232 derivative reductions). | | `qty` | query | number | no | Primary quantity (per the HTS unit of measure). | | `qty2` | query | number | no | Secondary quantity (when the HTS row has two UOMs). | | `degrees` | query | number | no | Alcohol-by-volume / proof / other degree-based fields. | | `transport` | query | string (enum: ocean, air, truck, rail) | no | Mode of transport — for HMF / MPF eligibility. | | `spi` | query | string | no | Special Program Indicator (e.g., USMCA, GSP, AGOA). | | `exclusions` | query | string | no | Comma-separated list of Chapter 99 exclusion codes claimed by the importer. | | `trace` | query | boolean | no | Include verbose computation trace. | | `includeLegalNoteRequiredInputs` | query | boolean | no | Include approved-only HTS legal-note required-fact prompts in dutyInfo.requiredInputs. Non-mutating; duty amounts do not consume these facts yet. | | `legalNoteFact.` | query | string | no | Optional supplied legal-note fact, keyed by required fact name, used to suppress matching advisory requiredInputs when includeLegalNoteRequiredInputs=true. | | `includeLegalNoteRateRuleDiagnostics` | query | boolean | no | Include approved-only, non-mutating HTS legal-note rate-rule shadow diagnostics. | | `includeLegalNoteChapter99ApplicabilityDiagnostics` | query | boolean | no | Include approved-only, non-mutating HTS legal-note Chapter 99 applicability diagnostics. | | `includeLegalNoteQuotaDiagnostics` | query | boolean | no | 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). | | `verbose` | query | boolean | no | Include all warnings + provenance. | ## Responses ### 200 — Successful calculation. `application/json` ```json { "type": "object", "required": [ "dutyInfo" ], "properties": { "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": { "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": { "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" } } }, "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": { "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." } } } } }, "respondentRate": { "type": "object", "description": "Per 19 CFR 351.107 — separate rate vs all-others vs country-wide." }, "effectiveDate": { "type": "string", "format": "date" }, "frCitation": { "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" } } } } } }, "chapter99Sources": { "type": "array", "items": { "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": { "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" } } } } } }, "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": { "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" } } }, "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": { "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" } } }, "estimatedTotalDuty": { "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" } } }, "totalDutyAmount": { "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" } } }, "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": { "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" ] } } } } } } } } } } ``` ### 400 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 401 — Unauthorized — missing or invalid Bearer token. `application/problem+json` ```json { "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." } } } ``` ### 413 — Payload too large — request body exceeds the per-route cap (default 1 MiB). `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/duty/calculate?hts=7307.91.50.10&origin=CN&date=2026-04-30" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/duty/calculate?hts=7307.91.50.10&origin=CN&date=2026-04-30", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/duty/calculate?hts=7307.91.50.10&origin=CN&date=2026-04-30", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # calculateDutyWithValuation — Calculate full landed duty (POST variant — accepts valuation adjustments) `POST /v1/duty/calculate` **Tags:** Duty Calculation **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Idempotency-Key` | header | string | no | 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. | ## Request body (required) **`application/json`** ```json { "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 — Successful calculation. `application/json` ```json { "type": "object", "required": [ "dutyInfo" ], "properties": { "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": { "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": { "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" } } }, "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": { "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." } } } } }, "respondentRate": { "type": "object", "description": "Per 19 CFR 351.107 — separate rate vs all-others vs country-wide." }, "effectiveDate": { "type": "string", "format": "date" }, "frCitation": { "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" } } } } } }, "chapter99Sources": { "type": "array", "items": { "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": { "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" } } } } } }, "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": { "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" } } }, "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": { "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" } } }, "estimatedTotalDuty": { "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" } } }, "totalDutyAmount": { "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" } } }, "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": { "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" ] } } } } } } } } } } ``` ### 400 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 401 — Unauthorized — missing or invalid Bearer token. `application/problem+json` ```json { "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." } } } ``` ### 411 — Length Required — POST/PUT/PATCH must include a Content-Length header. `application/problem+json` ```json { "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." } } } ``` ### 413 — Payload too large — request body exceeds the per-route cap (default 1 MiB). `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X POST \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/duty/calculate" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/duty/calculate", { method: "POST", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "POST", "https://api.tandom.ai/v1/duty/calculate", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: AD/CVD Intelligence Antidumping and countervailing duty orders, scope analysis, rate history, lifecycle, scope rulings, court decisions. # checkAdcvd — Apply AD/CVD orders to a shipment `GET /v1/adcvd/check` **Tags:** AD/CVD Intelligence **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `htsCode` | query | string | no | 10-digit HTS code. Required unless stats=true. | | `country` | query | string | no | ISO 3166-1 alpha-2. Required unless stats=true. | | `date` | query | string | no | Entry date (YYYY-MM-DD). Resolves rates / scope / eligibility as-of this date. Defaults to today. | | `productDescription` | query | string | no | Optional — feeds AI scope analysis. | | `manufacturer` | query | string | no | Optional — used for company-specific rate matching. | | `exporter` | query | string | no | Optional. | | `declaredValue` | query | number | no | | | `stats` | query | boolean | no | When true, returns dataset-level statistics instead of a lookup. | | `refresh` | query | boolean | no | Bypass response cache. | ## Responses ### 200 — Lookup result OR stats payload. `application/json` ```json { "oneOf": [ { "type": "object", "required": [ "matches", "dataSource" ], "properties": { "matches": { "type": "array", "items": { "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": { "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" } } }, "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": { "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." } } } } }, "respondentRate": { "type": "object", "description": "Per 19 CFR 351.107 — separate rate vs all-others vs country-wide." }, "effectiveDate": { "type": "string", "format": "date" }, "frCitation": { "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" } } } } } }, "pendingInvestigations": { "type": "array", "items": { "type": "object" } }, "dataSource": { "type": "string" }, "_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" ] } } } } } } } }, { "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" } } } } ] } ``` ### 400 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 401 — Unauthorized — missing or invalid Bearer token. `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/adcvd/check?date=2026-04-30" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/adcvd/check?date=2026-04-30", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/adcvd/check?date=2026-04-30", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # searchAdcvdOrders — Search the AD/CVD order catalog `GET /v1/adcvd/orders` **Tags:** AD/CVD Intelligence **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `q` | query | string | no | Full-text search over scope text + product description. | | `country` | query | string | no | Filter by country. | | `orderType` | query | string (enum: AD, CVD) | no | | | `status` | query | string (enum: active, revoked, suspended) | no | | | `hts` | query | string | no | Filter to orders covering this 10-digit code. | | `cursor` | query | string | no | 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. | | `page` | query | integer | no | Legacy offset-style page number — public /v1/* clients should use ?cursor= instead. Ignored when cursor is supplied. | | `limit` | query | integer | no | | ## Responses ### 200 — Search results. `application/json` ```json { "type": "object", "required": [ "orders", "total", "page", "limit", "hasMore" ], "properties": { "orders": { "type": "array", "items": { "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,\n4/6/8/10-digit). Single source of truth for HTS coverage on AD/CVD orders\n(Engine 0.121 / #146 — Haiku is the sole writer via this column).\nPrefer this over `htsHeadings` for new clients.\n", "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\n`htsCodes` via the `hts_products` hierarchy. Kept for back-compat\n(Triage 0.164 — EPIC 12 Story 1 Phase 2 soft migration). New clients\nshould read `htsCodes` directly.\n", "items": { "type": "string" }, "example": [ "7610", "7615" ] }, "frCitation": { "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" } } }, "rateFrCitation": { "type": [ "string", "null" ], "description": "Rate-establishment FR citation (the document that set the\ncurrent `countryWideRate`). Often differs from `frCitation` —\ne.g., the order was established by a 2015 sunset review but\nthe current rate comes from a 2025 administrative review.\nBrokers should consult both.\n", "example": "91 FR 5717" }, "rateFrDocumentNumber": { "type": [ "string", "null" ], "description": "Federal Register document_number (form `YYYY-NNNNNN`) for the\nrate-setting FR doc. Sister to `rateFrCitation` (text form).\nWhen present, callers should build the FR URL as\n`https://www.federalregister.gov/d/` — this is the\nsafe per-document permalink. The `/citation/-FR-`\nform derived from `rateFrCitation` is risky: it resolves to\nwhichever document starts on that page, which can be a\ndifferent agency's notice. NULL for ~80% of orders today;\npopulated as cascade ingest covers the rate-setting FR cohort.\n", "example": "2024-00396" }, "searchRank": { "type": "number", "description": "Full-text relevance rank when q is provided." } } } }, "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 — Unauthorized — missing or invalid Bearer token. `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/adcvd/orders" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/adcvd/orders", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/adcvd/orders", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # generateAdcvdReport — Full case-by-case AD/CVD analysis `POST /v1/adcvd/report` **Tags:** AD/CVD Intelligence **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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=,v1=`). ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Idempotency-Key` | header | string | no | 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. | ## Request body (required) **`application/json`** ```json { "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\nresponse is `202 Accepted` with `{jobId, webhookSecret}`;\nthe result is delivered to `webhookUrl` once ready.\n", "example": false }, "webhookUrl": { "type": "string", "format": "uri", "description": "Required when `async=true`. HTTPS URL that receives the\nsigned `report.completed` (or `report.failed`) event\nenvelope.\n", "example": "https://example.com/tandom-webhooks/report" } } } ``` ## Responses ### 200 — Report generated (sync path). `application/json` ```json { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "inputs": { "type": "object" }, "lookupResult": { "type": "object", "required": [ "matches", "dataSource" ], "properties": { "matches": { "type": "array", "items": { "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": { "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" } } }, "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": { "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." } } } } }, "respondentRate": { "type": "object", "description": "Per 19 CFR 351.107 — separate rate vs all-others vs country-wide." }, "effectiveDate": { "type": "string", "format": "date" }, "frCitation": { "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" } } } } } }, "pendingInvestigations": { "type": "array", "items": { "type": "object" } }, "dataSource": { "type": "string" }, "_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" ] } } } } } } } }, "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" }, { "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)." } } } ], "description": "Matched RespondentRateMatch for the saved report's selected\ncase at save time, per 19 CFR 351.107 (combination >\nexporter > producer). Targets the 2024 CBP MID-rate-mismatch\nenforcement program. NULL when no manufacturer/exporter was\nsupplied or no match resolved.\n" }, "csmsMessagesSnapshot": { "type": [ "array", "null" ], "items": { "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" } } } }, "description": "CBP CSMS messages on file for the saved report's selected\ncase at save time. Operational rate authority between FR\nnotices. NULL on rows saved before PR #804 shipped; capped\nat 50 most-recent messages on save.\n" } } } ``` ### 202 — Job enqueued (async path). Result will be delivered to `webhookUrl`. `webhookSecret` is shown ONCE — store it to verify the eventual signature. `application/json` ```json { "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 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 401 — Unauthorized — missing or invalid Bearer token. `application/problem+json` ```json { "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." } } } ``` ### 411 — Length Required — POST/PUT/PATCH must include a Content-Length header. `application/problem+json` ```json { "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." } } } ``` ### 413 — Payload too large — request body exceeds the per-route cap (default 1 MiB). `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X POST \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/adcvd/report" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/adcvd/report", { method: "POST", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "POST", "https://api.tandom.ai/v1/adcvd/report", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getAdcvdRateAtDate — Point-in-time rate query `GET /v1/adcvd/rates-at` **Tags:** AD/CVD Intelligence **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `case` | query | string | yes | | | `date` | query | string | yes | | | `rateType` | query | string (enum: country_wide, all_others, company_specific) | no | | | `company` | query | string | no | Partial match on company_name or company_suffix. | ## Responses ### 200 — Rate found. `application/json` ```json { "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": { "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" } } }, "frDocumentNumber": { "type": "string" }, "sourceType": { "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." } } }, "rateAppliesTo": { "type": "string" }, "combinationCounterparty": { "type": "string", "description": "For combination rates (e.g., specific exporter + specific producer)." }, "asOfDate": { "type": "string", "format": "date" } } } ``` ### 400 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 404 — Not found. `application/problem+json` ```json { "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." } } } ``` ### 429 — Rate limited. Includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/adcvd/rates-at?case=A-570-001" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/adcvd/rates-at?case=A-570-001", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/adcvd/rates-at?case=A-570-001", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: HTS Reference USITC Harmonized Tariff Schedule — search, browse, hierarchy, notes, scope expansions. # searchHts — Full-text HTS search `GET /v1/hts/search` **Tags:** HTS Reference **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `q` | query | string | yes | | | `limit` | query | integer | no | | | `cursor` | query | string | no | 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. | ## Responses ### 200 — Matching HTS rows. `application/json` ```json { "type": "object", "required": [ "results", "query", "count" ], "properties": { "results": { "type": "array", "items": { "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" } } } }, "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 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ### 500 — Internal server error. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/hts/search" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/hts/search", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/hts/search", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getHtsNotes — Section / chapter / subheading notes `GET /v1/hts/notes` **Tags:** HTS Reference **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `htsCode` | query | string | no | Pass either htsCode OR chapter. | | `chapter` | query | integer | no | | ## Responses ### 200 — Notes. `application/json` ```json { "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" } } } } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/hts/notes" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/hts/notes", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/hts/notes", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # browseHts — Enumerate HTS codes by chapter or parent prefix `GET /v1/hts/browse` **Tags:** HTS Reference **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. Pass `chapter`, OR `parent` (prefix), OR neither (returns chapters list). ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `chapter` | query | integer | no | | | `parent` | query | string | no | HTS prefix to enumerate children below. | ## Responses ### 200 — Hierarchical results. `application/json` ```json { "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": { "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" } } } }, "count": { "type": "integer" } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/hts/browse" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/hts/browse", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/hts/browse", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getHtsHierarchy — Walk parents / children for one code `GET /v1/hts/hierarchy` **Tags:** HTS Reference **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `code` | query | string | yes | | ## Responses ### 200 — Hierarchy breadcrumb. `application/json` ```json { "type": "object", "properties": { "code": { "type": "string" }, "breadcrumb": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "indent": { "type": "integer" } } } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/hts/hierarchy" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/hts/hierarchy", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/hts/hierarchy", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: Trade Programs Partner Government Agency flags, Chapter 99 applicable tariffs, FTA / SPI eligibility (closed beta). # checkPga — Partner Government Agency flags for an HTS code `GET /v1/pga/check` **Tags:** Trade Programs **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `htsCode` | query | string | no | Required unless agencies=true. | | `description` | query | string | no | Optional — refines flag matching. | | `includeWoodPackaging` | query | boolean | no | | | `agencies` | query | boolean | no | List agencies + programs instead of flag-checking. | ## Responses ### 200 — Flags or agency directory. `application/json` ```json { "oneOf": [ { "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" } } } } } }, { "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" } } } } } } } ] } ``` ### 400 — Bad request — invalid or missing parameters. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/pga/check" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/pga/check", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/pga/check", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getChapter99Applicable — Chapter 99 applicable tariffs for an HTS code + country `GET /v1/chapter99/applicable` **Tags:** Trade Programs **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `htsCode` | query | string | yes | | | `country` | query | string | yes | | | `debug` | query | boolean | no | | | `refresh` | query | boolean | no | | ## Responses ### 200 — Applicable Chapter 99 tariffs. `application/json` ```json { "type": "object", "properties": { "htsCode": { "type": "string" }, "country": { "type": "string" }, "applicableTariffs": { "type": "array", "items": { "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": { "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" } } } } } }, "matchedExclusions": { "type": "array", "items": { "type": "object" } }, "totalAdditionalRate": { "type": "number" }, "source": { "type": "string" }, "codeCount": { "type": "integer" } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/chapter99/applicable" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/chapter99/applicable", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/chapter99/applicable", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: Catalog Public HTS catalog used by `tariffs.tandom.ai/catalog/*` — sections, chapters, codes, full-text search. # searchCatalog — Full-text catalog search `GET /v1/catalog/search` **Tags:** Catalog **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `q` | query | string | yes | | | `chapter` | query | integer | no | | | `limit` | query | integer | no | | | `offset` | query | integer | no | | | `pga` | query | string | no | Filter by PGA agency code (e.g., FDA). | | `adcvd` | query | string (enum: true, false) | no | Filter to codes with / without AD/CVD coverage. | ## Responses ### 200 — Catalog rows + offset pagination meta. `application/json` ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "allOf": [ { "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" } } }, { "type": "object", "description": "HTS row with extended catalog metadata." } ] }, { "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" } } } } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/catalog/search" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/catalog/search", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/catalog/search", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # listCatalogSections — List HTS sections + their chapters `GET /v1/catalog/sections` **Tags:** Catalog **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters _None._ ## Responses ### 200 — Sections. `application/json` ```json { "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" } } } } } } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/catalog/sections" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/catalog/sections", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/catalog/sections", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getCatalogChapter — List codes in one chapter `GET /v1/catalog/chapters/{chapter}` **Tags:** Catalog **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `chapter` | path | integer | yes | | ## Responses ### 200 — Chapter detail. `application/json` ```json { "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": { "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" } } } }, "notes": { "type": "array", "items": { "type": "object" } }, "codeCount": { "type": "integer" } } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/catalog/chapters/{chapter}" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/catalog/chapters/{chapter}", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/catalog/chapters/{chapter}", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # getCatalogCode — Full detail for one HTS code `GET /v1/catalog/codes/{code}` **Tags:** Catalog **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `code` | path | string | yes | | ## Responses ### 200 — Code detail. `application/json` ```json { "type": "object", "properties": { "data": { "allOf": [ { "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" } } }, { "type": "object", "description": "HTS row with extended catalog metadata." } ] } } } ``` ### 404 — Not found. `application/problem+json` ```json { "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." } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/catalog/codes/7307.91.50.10" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/catalog/codes/7307.91.50.10", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/catalog/codes/7307.91.50.10", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: Regulatory Data Dataset freshness signals across HTS, FR, CSMS, S301, S232, AD/CVD, PGA, Trade Programs, Scope Rulings, CIT decisions. # getRegulatoryDataStatus — Dataset freshness signals `GET /v1/regulatory-data/status` **Tags:** Regulatory Data **Auth:** none (public endpoint). 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `pgaCounts` | query | boolean | no | Include PGA record counts by agent. | ## Responses ### 200 — Dataset status. `application/json` ```json { "type": "object", "properties": { "success": { "type": "boolean" }, "datasets": { "type": "array", "items": { "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" } } } }, "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" } } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/regulatory-data/status" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/regulatory-data/status", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/regulatory-data/status", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # Tag: Agent Interface 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. # getMcpInfo — MCP server info + tool catalog `GET /v1/mcp` **Tags:** Agent Interface **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. ## Parameters _None._ ## Responses ### 200 — MCP server descriptor. `application/json` ```json { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object" } } } ``` ## Examples ### cURL ```bash curl -X GET \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/mcp" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/mcp", { method: "GET", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "GET", "https://api.tandom.ai/v1/mcp", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` --- # callMcp — JSON-RPC 2.0 entry point `POST /v1/mcp` **Tags:** Agent Interface **Auth:** `Authorization: Bearer tk_live_`. Get a key at https://tandom.ai/account/api-keys. 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. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Idempotency-Key` | header | string | no | 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. | ## Request body (required) **`application/json`** ```json { "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 }." } } } ``` ## Responses ### 200 — JSON-RPC response. `application/json` ```json { "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" } } } } } ``` ## Examples ### cURL ```bash curl -X POST \ -H "Authorization: Bearer tk_live_..." \ "https://api.tandom.ai/v1/mcp" ``` ### Node.js ```javascript const response = await fetch("https://api.tandom.ai/v1/mcp", { method: "POST", headers: { "Authorization": "Bearer tk_live_..." } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests response = requests.request( "POST", "https://api.tandom.ai/v1/mcp", headers={ "Authorization": "Bearer tk_live_..." }, ) print(response.json()) ``` ---