Editable QR codes and scan analytics with the OpenQR API

If you've not set up an API key yet, start with getting started with the OpenQR API — every call here needs a free key sent as Authorization: Bearer oqr_…. The base URL is https://openqr.uk. For the conceptual difference between the two kinds of code, see static vs dynamic QR codes.

What a dynamic code actually is

When you create a dynamic code you get back a slug and a short_url of the form https://oqr.to/<slug>. That short URL is what gets encoded into the QR image. A scan hits the oqr.to redirect worker, which looks up the current destination and issues a 302 to it. Because the real destination lives server-side, you can repoint it whenever you like — the printed code never changes.

Honesty first: if you don't need to edit destinations or see analytics, a static code is simpler, free, works offline forever, and has no dependency on anyone's redirect staying online. Reach for dynamic codes when you specifically need editability or scan data. More on that in how to track QR code scans.

Create a dynamic code

POST /v1/dynamic with a JSON body of { destination, label? }. The destination must be a public http(s) URL — private or internal hosts and oqr.to self-loops are rejected as an abuse guard. A successful call returns 201 with the new code's id, slug, short_url and destination.

curl -X POST https://openqr.uk/v1/dynamic \
  -H "Authorization: Bearer oqr_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/spring-launch",
    "label": "Spring poster — bus stops",
    "theme": "Brand"
  }'

# 201 Created
# {
#   "id": "b1c2…",
#   "slug": "k7Pm2qR",
#   "short_url": "https://oqr.to/k7Pm2qR",
#   "destination": "https://example.com/spring-launch"
# }

The optional theme field takes a saved theme's id or name — a stored style (colours, dot and corner shapes, logo, gradient, frame) you've set up once on your account. The styling rides on the dynamic code rather than the printed image, so you can also restyle later with the same field on PATCH /v1/dynamic/{id} and the printed QR never changes. Save and manage themes via /v1/themes.

Now render that short_url as a QR image (via /v1/qr, covered in the getting-started guide), print it, and you're live. To generate the code image straight from the short URL:

curl "https://openqr.uk/v1/qr?data=https://oqr.to/k7Pm2qR&format=png&size=1024" \
  -H "Authorization: Bearer oqr_live_yourkey" \
  -o spring-poster.png

Repoint, rename, tag: editing a code

PATCH /v1/dynamic/{id} is the workhorse. Send only the fields you want to change. Editable fields:

The classic move is repointing after launch. Say the poster went out pointing at a holding page; once the real campaign page is ready, swap the destination — no reprint, same physical code:

curl -X PATCH https://openqr.uk/v1/dynamic/b1c2… \
  -H "Authorization: Bearer oqr_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "https://example.com/spring/live" }'

# 200 OK
# { "id": "b1c2…", "slug": "k7Pm2qR",
#   "short_url": "https://oqr.to/k7Pm2qR",
#   "destination": "https://example.com/spring/live", "label": "Spring poster — bus stops" }

List and delete

GET /v1/dynamic?limit= returns your codes newest-first (limit ≤ 500, default 200). DELETE /v1/dynamic/{id} removes one and returns { "deleted": true }; the slug immediately stops resolving.

# List
curl "https://openqr.uk/v1/dynamic?limit=50" \
  -H "Authorization: Bearer oqr_live_yourkey"
# { "codes": [ { "id", "slug", "short_url", "destination", "label", "status", "created_at" }, … ] }

# Delete
curl -X DELETE https://openqr.uk/v1/dynamic/b1c2… \
  -H "Authorization: Bearer oqr_live_yourkey"
# { "deleted": true }

Scan analytics in depth

GET /v1/dynamic/{id}/scans?days= is the analytics endpoint. days ranges 1-365 (default 30) and bounds the daily series and breakdowns; lifetime totals ignore the window. The window clamps to the account's plan, 7 days on Free. Device and referrer breakdowns are Pro: on Free those two keys are omitted from the response entirely, so a client can tell "not on your plan" from "no data". The response has two parts, a small scans summary and a fuller analytics object:

{
  "id": "b1c2…",
  "slug": "spring-sale",
  "short_url": "https://oqr.to/spring-sale",
  "destination": "https://example.com/spring/live",
  "scans": {
    "total": 1840,
    "last7": 263,
    "topCountry": "GB",
    "topDevice": "mobile"
  },
  "analytics": {
    "days_window": 30,
    "total": 1840,
    "window_total": 612,
    "daily": [ { "day": "2026-05-28", "n": 0 }, { "day": "2026-05-29", "n": 14 }, … ],
    "by_country": [ { "value": "GB", "n": 421 }, { "value": "IE", "n": 88 }, … ],
    "by_device": [ { "value": "mobile", "n": 540 }, { "value": "desktop", "n": 72 } ],
    "by_referrer": [ { "value": "Direct scan", "n": 580 }, { "value": "t.co", "n": 21 } ]
  }
}

• scans.total — lifetime scans; last7 — the trailing 7 days; topCountry / topDevice are the single leaders.
• analytics.total — lifetime (same as scans.total); window_total — scans inside the days window.
• daily — one bucket per day in the window, oldest → newest, zero-filled so you can plot it directly.
• by_country: top entries (up to 8) as { value, n }. Unknown country shows as Unknown.
• by_device / by_referrer: same shape, Pro only. A missing referrer shows as Direct scan.

Worked example: poll scans and build a summary

Here's a small Node script that reads the last 14 days for a code and prints a tidy summary — total, busiest day, and the top country and referrer. The same shape works for a cron job that posts to Slack.

const KEY = process.env.OPENQR_KEY;
const id = "b1c2…";

const res = await fetch(
  `https://openqr.uk/v1/dynamic/${id}/scans?days=14`,
  { headers: { Authorization: `Bearer ${KEY}` } }
);
const { scans, analytics } = await res.json();

const busiest = analytics.daily.reduce(
  (a, b) => (b.n > a.n ? b : a),
  { day: "—", n: 0 }
);
const top = (arr) => arr[0] ? `${arr[0].value} (${arr[0].n})` : "none";

console.log(`Lifetime: ${scans.total}  |  last 14d: ${analytics.window_total}`);
console.log(`Busiest day: ${busiest.day} (${busiest.n})`);
console.log(`Top country: ${top(analytics.by_country)}`);
console.log(`Top referrer: ${top(analytics.by_referrer)}`);

Where dynamic codes earn their keep

For minting codes at scale (one per table, seat or SKU) and organising them into folders, see bulk QR code generation. To drive all of this from an AI assistant — "create a code for the new menu and tell me last week's scans" — the same operations are exposed as tools on the OpenQR MCP server.