API & MCP reference

Authorization: Bearer tr_...

curl https://taproute.io/api/v1/links \
  -H "Authorization: Bearer tr_your_key_here"

curl -X POST https://taproute.io/api/v1/links \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/menu",
    "slug": "summer-menu",
    "rules": { "ios": "https://apps.apple.com/app/id123" }
  }'

# 201 Created
# { "id": "…", "slug": "summer-menu", "domain": "_", "shortUrl": "https://tap2u.link/summer-menu" }

# Change the destination after printing: the QR keeps working
curl -X PATCH https://taproute.io/api/v1/links/LINK_ID \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/winter-menu", "status": "active" }'

# Put the link on one of your own verified domains.
# Slugs are unique PER DOMAIN, so "summer-menu" can exist on both.
curl -X POST https://taproute.io/api/v1/links \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/menu",
    "slug": "summer-menu",
    "domain": "qr.yourbrand.com"
  }'

# 201 Created
# { "id": "…", "slug": "summer-menu", "domain": "qr.yourbrand.com",
#   "shortUrl": "https://qr.yourbrand.com/summer-menu" }

curl https://taproute.io/api/v1/wallet -H "Authorization: Bearer tr_..."

# { "balance": 48210, "inGrace": false, "graceExhausted": false, … }

# days: 7 | 30 | 90 | 180 | 365 | all (default 30). Over 90 days is served from the lifetime rollup.
curl "https://taproute.io/api/v1/analytics?days=30" -H "Authorization: Bearer tr_..."

# { "total": 1289, "uniques": 903, "bots": 44,
#   "timeseries": [{ "date": "2026-07-01", "count": 42, "uniques": 31 }, …],
#   "byCountry": […], "byDevice": […], "byBrowser": […], "byOs": […],
#   "byReferrer": […], "byUtmSource": […], "byCity": […], "byHour": […],
#   "topLinks": […] }

{
  "ios": "https://apps.apple.com/app/id123456",
  "android": "https://play.google.com/store/apps/details?id=com.example",

  // First matching window wins. Absolute (ISO start/end) …
  "schedule": [
    { "start": "2026-07-01T08:00:00Z", "end": "2026-07-01T11:00:00Z", "url": "https://example.com/breakfast" },
    // … or recurring: days 0=Sun..6=Sat, 'HH:MM' in "tz" (default: the scanner's timezone)
    { "days": [1, 2, 3, 4, 5], "from": "09:00", "to": "17:00", "tz": "Europe/Berlin", "url": "https://example.com/open" }
  ],

  // Country code (from the edge) → destination
  "geo": { "DE": "https://example.com/de", "FR": "https://example.com/fr" },
  // Accept-Language prefix → destination
  "lang": { "he": "https://example.com/he" },

  // Hard scan cap — past it, the paused page is shown
  "cap": 10000,
  // SHA-256 hex of an access password; the edge shows a gate form
  "passwordHash": "9f86d081…",
  // Geofence gate — "allow": only these countries may open the link (an unknown
  // country is refused); "block": these countries are refused. Blocked scanners
  // 302 to "url" when set, else see a region notice. Runs before the password gate.
  "geoGate": { "mode": "allow", "countries": ["US", "CA"], "url": "https://example.com/elsewhere" },
  // Verified-brand preview interstitial (anti-quishing); auto = ms before auto-continue
  "preview": { "brand": "Acme Coffee", "domain": "acme.com", "auto": 2000 },

  // A/B split over the DEFAULT destination only: an explicit rule above wins outright.
  // 'sticky' (default) keeps a visitor on one variant; 'random' rerolls every scan.
  "split": {
    "mode": "sticky",
    "variants": [
      { "name": "a", "url": "https://example.com/a", "weight": 50 },
      { "name": "b", "url": "https://example.com/b", "weight": 50 }
    ]
  },

  // Hard expiry, checked before every other rule: after "at", 302 to "url"
  // (or an expired notice when absent)
  "expire": { "at": "2026-12-31T23:59:59Z", "url": "https://example.com/gone" }
}

# Register a GTIN as a resolvable Digital Link. Costs 200 credits, once.
curl -X POST https://taproute.io/api/v1/gs1/items \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "keyValue": "09506000134352",
    "name": "Single Origin Coffee 250g",
    "defaultUrl": "https://example.com/coffee",
    "attributes": { "17": "261231", "3103": "000250" }
  }'

# 201 Created
# { "id": "…", "charged": 200,
#   "claim": { "claimed": true },
#   "licence": { "licensed": true, "status": "attested" } }

# Issue serialised codes (AI 21). 1 credit each: every serial is a dynamic code.
# Returns a CSV stream: serial,url,compressedUrl,elementString
curl -X POST https://taproute.io/api/v1/gs1/items/ITEM_ID/serials \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "count": 10000, "lot": "LOT4471" }'

# The X-Job-Id header IS the batch. Keep it: re-deriving the identical serials
# later is free, so a lost export never means re-buying the codes.
curl -X POST https://taproute.io/api/v1/gs1/items/ITEM_ID/serials \
  -H "Authorization: Bearer tr_..." \
  -d '{ "count": 10000, "jobId": "7f2a1b3c-…" }'   # 0 credits

# "Did we issue this?" · recomputed from the batch seed, not looked up.
curl "https://taproute.io/api/v1/gs1/verify?serial=7F2A00001AK3VP7QZM" \
  -H "Authorization: Bearer tr_..."

# { "issued": true, "jobId": "7f2a1b3c-…", "keyAi": "01",
#   "keyValue": "09506000134352", "index": 42, "issuedAt": "2026-07-16T09:12:44.000Z" }

# A serial we never issued, or one edited by hand, fails the HMAC:
# { "issued": false, "reason": "no batch of this workspace issued that serial" }

{
  "event": "scan",
  "data": {
    "linkId": "9f1c…",
    "slug": "summer-menu",
    "domain": "_",
    "country": "DE",
    "device": "ios",
    "ts": 1751884800000
  }
}

import { createHmac, timingSafeEqual } from 'node:crypto';

// signature header: t=<ms>,v1=<hex>
export function verifyTaproute(secret, signature, rawBody) {
  const parts = Object.fromEntries(signature.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'));
}

{
  "mcpServers": {
    "taproute": {
      "url": "https://taproute.io/mcp",
      "headers": { "Authorization": "Bearer tr_..." }
    }
  }
}