API Reference

Base URL: https://tariffdiff.com/api/v1

Authentication

All endpoints except /register require authentication. Pass your API key as a header:

curl https://tariffdiff.com/api/v1/diffs \
  -H "x-api-key: YOUR_API_KEY"

Alternatively, pass it as a query parameter:

curl "https://tariffdiff.com/api/v1/diffs?api_key=YOUR_API_KEY"

Rate Limits

100 requests per 60 seconds per API key. Exceeding this returns 429 Too Many Requests.

Register

POST /api/v1/register

Create a new API key. No authentication required.

curl -X POST https://tariffdiff.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"label": "my-app"}'

Response 201

{
  "api_key": "td_live_a1b2c3d4e5f6...",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "key_prefix": "td_live",
  "label": "my-app",
  "created_at": "2026-02-08T12:00:00Z",
  "note": "Save this API key now — it cannot be retrieved again."
}

Diffs

GET /api/v1/diffs Auth

Query detected tariff rate changes.

Query Parameters

Param	Type	Description
`limit`	integer	Max results (default 50, max 500)
`since`	date	Only changes after this date (ISO 8601)
`hts_prefix`	string	Filter by HTS code prefix (e.g. "8541")
`status`	string	Filter by status (e.g. "confirmed")

curl "https://tariffdiff.com/api/v1/diffs?since=2026-01-01&hts_prefix=8541" \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "diffs": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "status": "confirmed",
      "hts_code_canonical": "854140",
      "hts_code_display": "8541.40",
      "change_type": "rate_increase",
      "old_rate_bps": 2500,
      "new_rate_bps": 5000,
      "delta_bps": 2500,
      "effective_at": "2026-09-27T00:00:00Z",
      "detected_at": "2026-02-08T14:03:22Z",
      "citation_url": "https://federalregister.gov/d/2026-02044",
      "confidence": 0.97
    }
  ],
  "disclaimer": "Informational only. Verify applicability with counsel."
}

HTS State

GET /api/v1/hts/:code/state Auth

Look up the current (or historical) tariff rate for any HTS code.

Query Parameters

Param	Type	Description
`at`	date	Point-in-time lookup (ISO 8601, default: today)

curl https://tariffdiff.com/api/v1/hts/8471.30.01.00/state \
  -H "x-api-key: YOUR_API_KEY"

Response 200

{
  "hts_code": "8471300100",
  "formatted": "8471.30.01.00",
  "description": "Portable automatic data processing machines...",
  "general_rate_bps": 0,
  "special_rate_bps": null,
  "section_301_bps": 0,
  "total_applicable_bps": 0,
  "authoritative_as_of": "2026-02-08",
  "citation": null,
  "disclaimer": "Informational only. Verify applicability with counsel."
}

Watchlists

POST /api/v1/watchlists Auth

Create watchlists for HTS codes you want to monitor.

curl -X POST https://tariffdiff.com/api/v1/watchlists \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hts_codes": ["8541.40", "8471.30"],
    "webhook_url": "https://yourapp.com/webhooks/tariff",
    "annual_value_usd": 500000,
    "alert_threshold_bps": 100
  }'

Response 200

{
  "created": 2,
  "watchlists": [
    {
      "id": "a1b2c3d4-...",
      "hts_prefix": "854140",
      "webhook_secret": "whsec_9f8e7d6c5b4a..."
    },
    {
      "id": "e5f6a7b8-...",
      "hts_prefix": "847130",
      "webhook_secret": "whsec_1a2b3c4d5e6f..."
    }
  ]
}

Request Body

Field	Type	Description
`hts_codes`	string[]	HTS codes to watch (required)
`webhook_url`	string	URL to receive webhook events
`email`	string	Email for alerts
`annual_value_usd`	number	Your annual import value (for impact estimates)
`alert_threshold_bps`	integer	Min rate change to alert on (default: 1 bps)
`origin_country`	string	ISO country code
`preliminary_alert_enabled`	boolean	Send Phase 1 alerts (default: true)

GET /api/v1/watchlists Auth

List all your watchlists.

curl https://tariffdiff.com/api/v1/watchlists \
  -H "x-api-key: YOUR_API_KEY"

GET /api/v1/watchlists/:id Auth

Get a specific watchlist by ID.

DELETE /api/v1/watchlists/:id Auth

Delete a watchlist.

curl -X DELETE https://tariffdiff.com/api/v1/watchlists/a1b2c3d4-... \
  -H "x-api-key: YOUR_API_KEY"

Alerts

GET /api/v1/alerts Auth

View your notification delivery ledger. Useful for confirming webhook delivery status.

Query Parameters

Param	Type	Description
`since`	date	Only alerts after this date

curl "https://tariffdiff.com/api/v1/alerts?since=2026-02-01" \
  -H "x-api-key: YOUR_API_KEY"

Webhook Test

POST /api/v1/webhooks/test Auth

Send a test webhook event to a watchlist's configured URL. Useful for verifying your endpoint works before real events fire.

curl -X POST https://tariffdiff.com/api/v1/webhooks/test \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"watchlist_id": "a1b2c3d4-..."}'

Response 200

{
  "ok": true,
  "status": 200
}