QRArchive API and webhooks

Available on the Business and Agency plans. Workspace admins and owners manage keys and webhook endpoints in Dashboard → Developers.

Authentication

Authorization: Bearer qra_abcd1234_…

• A key belongs to one workspace and can only see and change that workspace's QR codes.
• The full key is shown once when it is created. Only a SHA-256 hash is stored, so a lost key can't be recovered; revoke it and create a new one.
• Keys carry permissions (qr:read, qr:write, analytics:read) and can expire after 30, 90 or 365 days.
• Every request re-checks that the key is active, the workspace isn't suspended and the plan still includes the API. Downgrading switches keys off immediately; upgrading again switches them back on.
• Server-to-server only. No CORS headers are sent, so browsers refuse cross-origin calls. Never put a key in a website or mobile app.
• Rate limits: 120 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit you get 429 with Retry-After. Repeated invalid keys from one address are blocked for 10 minutes.
• A key stops working when the person who created it leaves the workspace or is no longer an owner or admin. Create keys from an account that will keep managing the workspace.

Errors

Every error uses the same JSON shape and an appropriate HTTP status:

{ "error": { "code": "validation_failed", "message": "destination.url: Enter a valid web address" } }

QR code object

{
  "id": "7b0c…",
  "name": "Table tent",
  "description": null,
  "type": "url",
  "destination": { "url": "https://example.com/menu" },
  "is_dynamic": true,
  "short_url": "https://qra.example/q/Ab3dE7x",
  "qr_content": "https://qra.example/q/Ab3dE7x",
  "status": "active",
  "blocked": false,
  "folder_id": null,
  "scan_count": 42,
  "last_scanned_at": "2026-10-04T12:00:00.000Z",
  "starts_at": null,
  "expires_at": null,
  "created_at": "2026-10-01T09:00:00.000Z",
  "updated_at": "2026-10-03T16:30:00.000Z"
}

qr_content is exactly what the QR code encodes. For dynamic codes it is the short URL, never the destination, so the destination can change after printing. Fields are only ever added to this object, never removed or renamed.

Endpoints

Base URL: https://www.qrarchive.com/api/v1

Single QR codes (fetch, create and update) are returned as { "data": { …QR code object… } }. The list returns { "data": [...], "next_cursor": "…" | null }. Pass next_cursor back as cursor to get the next page; the order is newest first and stays stable while you page.

Create

curl -X POST "https://www.qrarchive.com/api/v1/qr-codes" \
  -H "Authorization: Bearer $QRA_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Spring flyer", "type": "url", "destination": { "url": "https://example.com/spring" } }'

Send an Idempotency-Key header (any unique string up to 255 characters, such as a UUID) to make retries safe: for 24 hours, repeating the request with the same key and body returns the original response with Idempotent-Replayed: true instead of creating another code. Reusing a key with a different body returns 422 idempotency_key_reused, and a retry while the first request is still running returns 409 idempotency_in_progress.

New codes use the default design. Change the design in the dashboard; the image endpoint always uses the saved design. Plan limits apply exactly as in the dashboard: over the limit you get 403 limit_reached.

Update

Send only the fields you want to change. type and destination must be sent together. status is one of active, paused or archived. expires_at is an ISO-8601 date-time with an offset, or null; setting one needs a plan with expiry dates. Changes reach every scan within a few seconds.

Everything done through the API is written to the workspace audit log with the key's ID, and fires the same webhooks as the dashboard.

Webhooks

Add an https endpoint in Dashboard → Developers, pick the events, and store the signing secret (whsec_…) that's shown once.

Each delivery is an HTTP POST with a JSON body:

{ "id": "evt-uuid", "type": "scan.created", "created_at": "…", "workspace_id": "…", "data": { … } }

Headers:

This is QRArchive's own scheme, not the Standard Webhooks one, so verify it with the code below rather than a Standard Webhooks library.

Verifying signatures (Node.js)

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

export function verify(secret, headers, rawBody) {
  const ts = Number(headers["x-webhook-timestamp"]);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false; // replay window
  const expected = Buffer.from(`v1=${createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")}`);
  const given = Buffer.from(headers["x-webhook-signature"] ?? "");
  return expected.length === given.length && timingSafeEqual(expected, given);
}

Verify against the raw request body, before any JSON parsing.

Delivery rules

• Respond with any 2xx within 10 seconds. Anything else, including a redirect (redirects aren't followed), counts as a failure.
• Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: six attempts in total. Events can arrive out of order or more than once.
• An endpoint that has failed at least 20 deliveries in a row and hasn't succeeded for 24 hours is paused. Workspace owners and admins get an email, and the dashboard shows why. Turning it back on resets the count.
• Endpoints must be https on port 443 with a public hostname. The host is resolved as part of every connection and private, loopback and cloud-metadata addresses are refused, so DNS changes can't redirect deliveries to internal addresses.
• Delivery logs are kept for 30 days. Resend next to a finished delivery sends that event again straight away, with the same event ID.