API & MCP reference

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

# 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,
  // Access password; the edge shows a gate form. Hash is SHA-256 hex of
  // salt + ":" + password. Send a random "passwordSalt" with it — without one the
  // hash is a rainbow-table lookup. The salt is part of this rule, not billed as
  // another one. Wrong guesses are throttled per link, per client network.
  "passwordHash": "9f86d081…",
  "passwordSalt": "3f9a1c7e2b4d8a60",
  // 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" }
}

# The same link, now with two rules (10 credits · 5 credits per rule changed):
# iPhones go to the App Store, scans from Germany go to /de.
curl -X PATCH https://taproute.io/api/v1/links/LINK_ID \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "rules": {
    "ios": "https://apps.apple.com/app/id123",
    "geo": { "DE": "https://example.com/de" }
  } }'

# The create vocabulary. Fetch it · never guess a template id.
curl https://taproute.io/api/v1/pages/templates \
  -H "Authorization: Bearer tr_..."

# { "categories": ["custom", "experience", "bio", …],
#   "templates": [
#     { "id": "bio-links", "blocks": ["profile", "button"], "tier": null },
#     { "id": "…", "blocks": ["band", "loopvideo", "schedule"],
#       "tier": "experience", "unlockCredits": …, "scanCredits": … } ],
#   "skins": [ … ], "theme": { … } }

# tier null costs nothing beyond the link. tier "experience" is free to mint and
# free to edit, then 800 credits, once, at first publish · 2 credits per scan.

# Mint the code and its page in one call. "draft": true means the slug 404s until
# you release it · and an experience template's unlock is not charged yet.
curl -X POST https://taproute.io/api/v1/links \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "TEMPLATE_ID", "slug": "arrivals", "draft": true }'

# 201 Created · pageId is the handle every edit below uses
# { "id": "…", "pageId": "…", "slug": "arrivals",
#   "destination": { "kind": "page", "pageId": "…" } }

# Blocks REPLACE the array, so send the whole page every time. Field names are read
# off GET /api/v1/pages/blocks, which answers with a valid default of every type.
curl -X PATCH https://taproute.io/api/v1/pages/PAGE_ID \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "blocks": [
    { "type": "band", "name": "Today", "cols": "1", "tone": "default" },
    { "type": "heading", "text": "Arrivals", "level": 1 },
    { "type": "schedule", "date": "2026-09-14", "now": true,
      "sessions": [{ "time": "10:00", "end": "10:45", "title": "Doors", "track": "Main" }] },
    { "type": "audio", "title": "Lobby set",
      "tracks": [{ "title": "Side A", "url": "https://cdn.example/a.mp3", "dur": "3:41" }] },
    { "type": "loopvideo", "src": "https://cdn.example/loop.mp4", "ratio": "wide" },
    { "type": "zoomimage", "src": "https://cdn.example/map.jpg", "label": "Tap to zoom" }
  ] }'

# What the release will do, and what it will cost, before you commit to it.
curl https://taproute.io/api/v1/links/LINK_ID/publish \
  -H "Authorization: Bearer tr_..."

# { "slug": "arrivals", "warnings": [],
#   "experienceDue": { "unlock": …, "scan": … } }   # absent once it is paid

# Release it. This is the call that charges the unlock, once · and it charges BEFORE
# the go-live write, so a 402 leaves the link a draft with nothing spent.
curl -X POST https://taproute.io/api/v1/links/LINK_ID/publish \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" -d '{}'

# A static code carries its payload inside the symbol. Nothing resolves through us,
# so it costs no credits to create and none per scan · and it can never be repointed.
# Give it EITHER a raw payload OR a kind + fields; sending both is a 400.
curl -X POST https://taproute.io/api/v1/static-codes \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "kind": "wifi", "fields": { "ssid": "Lobby", "password": "hunter2" } }'

# 201 Created · escaping handled for you, and named for the SSID
# { "id": "…", "publicId": "QR-7Q4K2P", "type": "wifi", "name": "Lobby",
#   "payload": "WIFI:T:WPA;S:Lobby;P:hunter2;;" }

# The raw form still works · for a payload that is not one of the ten kinds,
# or for re-saving one you read back out of the library.
curl -X POST https://taproute.io/api/v1/static-codes \
  -H "Authorization: Bearer tr_..." \
  -d '{ "payload": "BEGIN:VCARD\r\nVERSION:3.0\r\nFN:Dana Levi\r\nEND:VCARD" }'

# The bulk job this exists for: a table of conference badges, in one call.
# Rows are independent · a bad row never cancels its neighbours, and the
# result reports every failure at its ORIGINAL index. Still 0 credits.
curl -X POST https://taproute.io/api/v1/static-codes/batch \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "codes": [
    { "kind": "vcard", "fields": { "name": "Dana Levi", "tel": "+972501234567" } },
    { "kind": "vcard", "fields": { "name": "Noa Bar", "email": "noa@example.com" } },
    { "payload": "https://example.com/programme", "name": "Programme" }
  ] }'

# 200 · always this shape, never 207
# { "created": [{ "index": 0, "id": "…", "publicId": "QR-…", "type": "vcard" }, …],
#   "errors":  [] }

# 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_..." }
    }
  }
}