API documentation

Base URL https://www.tracksonar.com · spec: OpenAPI 3.0 · for AI agents: llms.txt · MCP endpoint: https://www.tracksonar.com/mcp

1. Get a key (one call)

curl -X POST https://www.tracksonar.com/v1/signup -d '{"email":"you@example.com"}'
# → {"api_key":"trk_live_...","plan":"free"}

2. Track a package

curl -X POST https://www.tracksonar.com/v1/trackings \
  -H "Authorization: Bearer $KEY" \
  -d '{"tracking_number":"1Z12345E0205271688"}'
# 201 → {"id":"...","carrier":"ups","status":"pending",...}
# Carrier is auto-detected; pass "carrier":"usps" to pin it.
# Resubmitting the same number returns 200 and is never billed twice.

3. Read status

curl -H "Authorization: Bearer $KEY" https://www.tracksonar.com/v1/trackings/{id}
curl -H "Authorization: Bearer $KEY" "https://www.tracksonar.com/v1/trackings?limit=50"

Statuses: pending → info_received → in_transit → out_for_delivery → delivered, plus available_for_pickup, delivery_failure, exception, expired.

4. Webhooks

curl -X POST https://www.tracksonar.com/v1/webhooks \
  -H "Authorization: Bearer $KEY" \
  -d '{"url":"https://example.com/hooks/track"}'
# → {"secret":"whsec_..."}  (shown once)

Every update POSTs a JSON payload with header X-Track-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + body). Reject if |now − t| > 5 min. Event types: tracking.updated, tracking.delivered, tracking.exception, … (one per status). Delivery is at-least-once and unordered — dedupe on payload id.

# Python
import hmac, hashlib, time
def verify(secret, header, body):
    t, v1 = [p.split("=",1)[1] for p in header.split(",")]
    if abs(time.time() - int(t)) > 300: return False
    want = hmac.new(secret.encode(), f"{t}.".encode()+body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, v1)

// Node
const crypto = require("crypto");
function verify(secret, header, body) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  if (Math.abs(Date.now()/1000 - +t) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(`${t}.`).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

5. Limits & billing

Billing counts trackings created per month — reads, lists and webhooks are free. Free: 100/mo · Pro $9: 1,000/mo · Business $49: 10,000/mo. Over quota → 429 quota_exceeded; burst limit → 429 rate_limited with Retry-After.

6. MCP (AI assistants)

{"mcpServers": {"track": {"type": "http", "url": "https://www.tracksonar.com/mcp",
  "headers": {"Authorization": "Bearer trk_live_..."}}}}

Tools: track_number, get_tracking, list_trackings, list_carriers.

Errors

{"error":{"message":"...","code":"unauthorized|not_found|invalid_number|quota_exceeded|rate_limited|bad_request"}}