Tarri Classification API

Introduction

The Tarri API is a JSON-over-HTTPS endpoint. There is one method — classify a product — and it returns everything the app shows: the ranked HTS classification, a full landed-duty breakdown (Section 301 / 122 / 232 / MPF / HMF, gated by country of origin), and an honest confidence score that tells you when to trust the answer and when to review it.

Authentication

Every request must include your secret API key as a bearer token:

Authorization: Bearer tarri_sk_live_…

• Get your key in the app under Settings → API access (available on the Team plan). Click Generate API key.
• One key per workspace. Generating again rotates the key — the previous one stops working immediately.
• Shown once. For your security only a hash is stored; copy the key when it's shown. If you lose it, regenerate.
• Keep it secret. Use it server-side only — never ship it in a browser, mobile app, or public repo.

Quickstart

Classify your first product in one call. Set TARRI_API_KEY in your environment, then:

curl -X POST https://app.tarri.ai/api/v1/classify \
  -H "Authorization: Bearer $TARRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "1500W stainless steel convection toaster oven",
    "origin": "CN",
    "fob": 42,
    "units": 1
  }'

const res = await fetch("https://app.tarri.ai/api/v1/classify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TARRI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "1500W stainless steel convection toaster oven",
    origin: "CN",
    fob: 42,
    units: 1,
  }),
});

if (!res.ok) throw new Error(`Tarri API error ${res.status}`);
const result = await res.json();
console.log(result.best.htsNumber, result.best.confidence);

import os, requests

res = requests.post(
    "https://app.tarri.ai/api/v1/classify",
    headers={"Authorization": f"Bearer {os.environ['TARRI_API_KEY']}"},
    json={
        "description": "1500W stainless steel convection toaster oven",
        "origin": "CN",
        "fob": 42,
        "units": 1,
    },
    timeout=60,
)
res.raise_for_status()
result = res.json()
print(result["best"]["htsNumber"], result["best"]["confidence"])

A classification typically takes a few seconds (it runs retrieval, an AI rerank, and a CBP-ruling lookup). Use a request timeout of at least 60 seconds.

Rate limits & quota

API calls draw from the same monthly classification quota as the app — there is no separate API meter.

When the quota is exhausted the endpoint returns 402 quota_exceeded with plan, used, and limit. Quota resets at the start of each calendar month (UTC). Only successful (2xx) classifications count.

POST /api/v1/classify

Classify a single product. Returns the ranked HTS shortlist, the landed-duty breakdown, and a confidence score.

POST https://app.tarri.ai/api/v1/classify

Request parameters

A JSON body. Supply at least one of description, name, or imageUrl; everything else is optional but improves accuracy and unlocks the dollar duty breakdown.

The response object

A 200 returns the full classification result:

Example response (abridged):

{
  "best": {
    "htsNumber": "8516.60.40.70",
    "htsDigits": "8516604070",
    "item": "Electrothermic ovens … Cooking stoves, ranges and ovens",
    "confidence": 0.94,
    "generalDutyRate": 2.7,
    "section301Rate": 25,
    "generalDuty": "2.7%",
    "section301Duty": "25%",
    "rationale": "Consumer electric toaster oven — domestic electrothermic oven under 8516.60.",
    "retrievalScore": 0.81
  },
  "candidates": [ /* … ranked alternatives … */ ],
  "abstained": false,
  "abstainReason": null,
  "perUnitValue": 42,
  "duty": {
    "fob": 42,
    "totalKnownDuty": 16.04,
    "effectiveKnownRate": 38.2,
    "landedCostKnown": 58.04,
    "lines": [ /* Standard, Sec 301, Sec 122, MPF, HMF … */ ],
    "manualReview": false,
    "missingInputs": []
  },
  "pipeline": { "aiRerankUsed": true, "rulingsUsed": true, "headings": ["8516"] }
}

The candidate object

Each entry in best and candidates:

The duty object

Present when you pass a positive fob. It computes the full landed-duty stack by country of origin.

Confidence & abstention

Tarri is calibrated — it tells you how sure it is, and refuses to bluff. Read these two fields before you trust a result programmatically:

• best.confidence — a score in [0, 1]. As a rule of thumb: ≥ 0.80 high (safe to auto-accept), 0.60–0.79 medium (spot-check the value band), < 0.60 low.
• abstained — when true, no candidate was a confident fit. best is null; route the item to a human and review candidates (still returned) instead of auto-accepting.

Errors

Errors return a non-2xx status with a JSON body of the form { "error": "…" }.

Full examples

The same request in three languages:

curl -X POST https://app.tarri.ai/api/v1/classify \
  -H "Authorization: Bearer $TARRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "1500W stainless steel convection toaster oven",
    "origin": "CN",
    "fob": 42,
    "units": 1
  }'

const res = await fetch("https://app.tarri.ai/api/v1/classify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TARRI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "1500W stainless steel convection toaster oven",
    origin: "CN",
    fob: 42,
    units: 1,
  }),
});

if (!res.ok) throw new Error(`Tarri API error ${res.status}`);
const result = await res.json();
console.log(result.best.htsNumber, result.best.confidence);

import os, requests

res = requests.post(
    "https://app.tarri.ai/api/v1/classify",
    headers={"Authorization": f"Bearer {os.environ['TARRI_API_KEY']}"},
    json={
        "description": "1500W stainless steel convection toaster oven",
        "origin": "CN",
        "fob": 42,
        "units": 1,
    },
    timeout=60,
)
res.raise_for_status()
result = res.json()
print(result["best"]["htsNumber"], result["best"]["confidence"])

Support

Questions, higher limits, or a bulk/Enterprise plan? Email hello@tarri.ai or manage your key any time in Settings → API access.

Classifications are decision support, not customs or legal advice. Review before filing.