Reticle QR Code API

Create and manage dynamic QR code links straight from your own scripts: mint a link, list your links, read or update one, delete it, and pull its scan stats, all over plain HTTPS and JSON. The API is included with Reticle Pro at $7 a month or $60 a year, with no separate API tier and no metered add-on charge.

Authentication

Every request is authenticated with a bearer API key, minted from your account page. A key is shown to you exactly once at creation time; Reticle stores only a hash of it, never the key itself, so if you lose it there's nothing to recover, only a new key to mint. Each account can hold a small number of named keys at once (see the limits table below) and revoke any of them individually at any time; a revoked key stops working on its very next request.

Send the key as Authorization: Bearer rk_live_<your key>. The API is server-to-server by design: it sends no CORS headers, so a browser page cannot call it directly, which is deliberate, since a page that could would be shipping your bearer key to anyone who opens dev tools. Call it from a server, a script, or a scheduled job instead.

Any request with a body must send valid JSON with Content-Type: application/json. A malformed body (invalid JSON) is rejected with a plain 400 before it reaches the API's own logic. The wrong content type still reaches the handler, which reports it with the same JSON error shape used everywhere else, described below.

Quick start

Create a dynamic link that redirects to a destination URL:

curl -X POST https://reticle.cloud/api/v1/links \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com/menu", "name": "menu"}'

which returns:

{
  "slug": "aB3xY9",
  "shortUrl": "https://open-qr.link/aB3xY9",
  "kind": "redirect",
  "destination": "https://example.com/menu",
  "name": "menu",
  "active": true,
  "labels": [],
  "customSlug": null,
  "linkDomain": null,
  "createdAt": "2026-08-12T19:04:05.000Z",
  "scanCount": 0,
  "lastScanAt": null,
  "reclaimed": false,
  "reclaimedAt": null
}

That response shape, the "public link" shape, is what every endpoint below returns for a link: a fixed, closed set of fields. Anything not in that list (routing rules, password hashes, Safe Browsing verdicts, the owner id) is never returned by the API, no matter what's on the underlying document. Timestamps are always ISO 8601 UTC strings, or null when not yet set.

Endpoints

All six routes live under https://reticle.cloud/api/v1:

Reading works for every kind of link: GET /links/{slug} and its /stats return a link's public shape or its stats whether the link is a redirect, a file link, a page, or a dynamic vCard. Writing is redirect-only: PATCH and DELETE both return wrong_kind on any link that isn't a plain redirect. A slug that doesn't exist, or belongs to a different account, always returns not_found, never a permission error, so the API never confirms whether someone else's link exists.

Errors

Every error response is JSON, in the same shape:

{ "error": { "code": "rate_limited", "message": "Too many requests. Please slow down and try again." } }

Rate limits

Two ceilings apply, and they're separate budgets: an overall request ceiling that covers every call you make, and a smaller creation budget that link creation shares with the ordinary create-a-link flow in the app itself (so a script and a signed-in session drawing from the same account draw from the same creation budget). Both fail open: if the rate limiter itself has trouble, your request still goes through rather than getting refused by an outage on our side. A request that's over a limit gets back 429 rate_limited with a Retry-After header telling you how many seconds to wait.

Webhooks

A webhook sends every scan to a system of yours the moment it happens. Add up to three HTTPS endpoints on your account page and Reticle POSTs one JSON event per scan, on every dynamic link the account owns. Events usually arrive within a few seconds. The first event after adding or changing an endpoint can take up to a minute. Webhooks are part of Reticle Pro.

An event is sent for every scan that Reticle records in your per-scan analytics, and only those. That means dynamic links on a Pro account, with crawler and link-preview fetches excluded: those still count toward a link's scan total, but no person looked at the code, so no event is sent. If your account leaves Pro, per-scan records stop and so do webhooks.

The event

{
  "id": "k3Yx9QpB2tLm7VcN4wRz",
  "type": "scan",
  "createdAt": "2026-08-29T17:03:12.412Z",
  "link": { "slug": "ab3Kq9", "name": "Spring menu", "kind": "redirect", "url": "https://open-qr.link/ab3Kq9" },
  "scan": {
    "at": "2026-08-29T17:03:12.104Z",
    "device": "mobile", "os": "iOS 17", "browser": "Safari",
    "country": "US", "region": "California", "city": "Oakland", "lat": 37.8, "lon": -122.27,
    "target": "destination", "referrer": "instagram.com", "returning": false
  }
}

Every field is present on every event; a value we do not have is null. Delivery is at least once, so treat a repeated id as the same scan. The event never includes the scanner's IP address or user agent; Reticle does not keep them.

Headers and signature

Each request carries Reticle-Event-Id, Reticle-Event-Type, and Reticle-Signature in the form t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 over <t>.<raw body> using the endpoint's signing secret. Verify it against the raw request bytes, compare in constant time, and reject timestamps more than five minutes old:

const crypto = require("node:crypto");
function verify(secret, rawBody, header) {
  const m = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header || "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex");
  return expected.length === m[2].length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

Responding

Answer with any 2xx status within 3 seconds and do the real work afterwards. Redirects are not followed and count as failures. After 20 failed deliveries in a row the endpoint is paused and you get one email; fix the receiver and press Resume on your account page. Deliveries are not retried. An account can send up to 1000 scans per hour to its endpoints (up to 3000 deliveries across three endpoints).

Zapier and Make

In Zapier, start a Zap with Webhooks by Zapier, trigger Catch Hook, and paste the URL it gives you as a Reticle endpoint. In Make, add a Webhooks module, Custom webhook, and do the same. Both accept events without checking the signature, so verification there is optional.

Frequently asked questions

Ready to script your codes? Upgrade to Reticle Pro, then open your account page to mint your first API key.