Developer API

Authentication

Create an API key in Settings and send it with every request. Keys are shown once at creation and can be revoked at any time.

Authorization: Bearer tos_live_...

Calls count against your plan's monthly API limit (free: 500, Pro: 1,000, Business: 10,000). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers; exceeding the limit returns HTTP 429 with code API_QUOTA_EXCEEDED.

Create an API key in Settings · Compare plan limits

Response envelope

Every endpoint returns the same JSON envelope. Exactly one of data and error is non-null; errors carry a stable machine-readable code.

{ "data": { ... }, "error": null, "meta": { ... } }
{ "data": null, "error": { "code": "API_QUOTA_EXCEEDED", "message": "..." } }

POST /api/v1/resolutions

Resolve up to 100 tariff requests per call. Each request needs a ten-digit US HTS code, an ISO origin country (never inferred), a USD customs value, an evaluation date, and an integrity hash of the inputs. Validation happens per request: an invalid or uncovered request yields a structured blocked result with a failure code; the rest of the batch still resolves.

curl -X POST https://tariffos.com/api/v1/resolutions \
  -H "Authorization: Bearer tos_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [{
      "requestId": "req-001",
      "externalVariantRef": "sku-123",
      "destination": "US",
      "origin": "JP",
      "hsCode": "3924.10.4000",
      "evaluationDate": "2026-07-29",
      "valuationAmount": "1000.00",
      "valuationCurrency": "USD",
      "costBasis": "supplier_only",
      "costBasisVersion": "v1",
      "inputHash": "f85ceeb48558e1244fe04a44754f733d6ed53501ce8cc4e92f6993ec64cc2aa0"
    }]
  }'

A supported route returns verified duty components with rate, amount, source URLs, and the exact government source version:

{
  "data": {
    "results": [{
      "requestId": "req-001",
      "coverage": "supported",
      "verificationStatus": "verified",
      "calculationStatus": "calculated",
      "components": [{
        "measureId": "us-hts-column-1-general",
        "authority": "mfn",
        "rateType": "ad_valorem",
        "rateValue": "3.4",
        "amount": "34.00",
        "sourceUrls": ["https://hts.usitc.gov/search?query=3924.10.40"],
        "sourceVersion": "USITC-2026HTSRev16"
      }],
      "estimatedDutyTotal": "34.00",
      "effectiveRate": "3.4",
      "engineVersion": "tariffos-resolver-m0.2.0",
      "warnings": ["M0 covers only the listed Column 1 General base rate for this exact route."]
    }]
  },
  "error": null,
  "meta": { "engineVersion": "tariffos-resolver-m0.2.0", "requestCount": 1 }
}

The inputHash field

inputHash is the lowercase hex SHA-256 of the JSON serialization of the canonicalized request fields below (uppercased country codes, HTS code without dots, canonical decimal amounts). It exists so a stored result can always be traced back to exactly the inputs that produced it. If the hash does not match the inputs, the request is rejected.

destination, origin, hsCode (dots removed), evaluationDate,
valuationAmount, valuationCurrency, costBasis, costBasisVersion,
quantity, customsQuantityUnit, netWeight, netWeightUnit

GET /api/v1/measure-changes

Cursor-paginated feed of verified tariff-measure changes — the machine-readable answer to "tell my software when anything affecting my HTS codes changes." Poll with your last cursor; limit is 1–100 per page. Every record cites official sources and carries old and new state.

curl "https://tariffos.com/api/v1/measure-changes?limit=100" \
  -H "Authorization: Bearer tos_live_..."

The feed fails closed: it only ever serves records verified against official source snapshots. If verified data cannot be served, it returns HTTP 503 with code MEASURE_CHANGE_FEED_NOT_READY rather than guessing.

POST /api/v1/mcp

Model Context Protocol server (Streamable HTTP, stateless JSON-RPC over POST). Connect AI assistants like Claude Desktop or Cursor directly to the resolution engine, coverage matrix, and change feed — same key, same metering (one API call per request). Example client config:

{
  "mcpServers": {
    "tariffos": {
      "url": "https://tariffos.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer tos_live_..." }
    }
  }
}

Exposed tools: resolve_tariffs (batch resolution), get_coverage (the reviewed matrix — call it first), get_measure_changes (verified change feed).

GET /api/v1/coverage

The full machine-readable coverage matrix: supported routes, known-unsupported routes, rate types, source versions with SHA-256 checksums of the government source files, and the verified evaluation-date range. The currently supported routes:

curl https://tariffos.com/api/v1/coverage \
  -H "Authorization: Bearer tos_live_..."

Coverage matrix last verified 2026-08-17 against the cited government sources.