API Documentation

Create QR short links and change where they lead from your own systems. The API is free and available to every team. It works on the same data as the dashboard, so a code created through the API shows up there right away.

• Authentication
• The link object
• List
• Create
• Get one
• Update
• Delete
• Statistics
• Errors
• Limits
• What a scan returns

Authentication

Base URL: https://qr-redirect-vercel.vercel.app. All endpoints live under /api/v1, accept and return JSON, and need an API key in the Authorization header:

Authorization: Bearer qr_your_key

The team owner creates and revokes keys in the dashboard: Settings → Developer API. A key is shown once, when it is created. Only its hash is stored, so a lost key cannot be recovered: revoke it and create a new one. A key gives access to every QR code of the team. When a person leaves the team, the keys they created stop working.

The link object

QR designs (colors, logo) are edited in the dashboard only. The API ignores qr_style.

List links

GET /api/v1/links returns the team's links, newest first. Deleted links are never returned.

curl "https://qr-redirect-vercel.vercel.app/api/v1/links?limit=50&offset=0" \
  -H "Authorization: Bearer qr_your_key"

Response 200:

{ "links": [ { "short_id": "menu", "short_url": "https://qr-redirect-vercel.vercel.app/menu", "target_url": "https://example.com/menu",
    "label": "Menu", "status": "active", "tags": null, "expires_at": null, "expiry_behavior": "inactive",
    "expired": false, "created_at": "2026-09-18T09:14:27.203Z", "updated_at": "2026-09-18T09:14:27.203Z" } ] }

Anything that is not a whole number answers 400 invalid_pagination.

Create a link

POST /api/v1/links

curl -X POST https://qr-redirect-vercel.vercel.app/api/v1/links \
  -H "Authorization: Bearer qr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/menu","label":"Menu","custom_slug":"menu"}'

Response 201:

{ "short_id": "menu", "short_url": "https://qr-redirect-vercel.vercel.app/menu", "target_url": "https://example.com/menu",
  "status": "active", "label": "Menu", "expires_at": null }

Print the QR code only after you have scanned short_url with a phone and seen the right page.

Get one link

GET /api/v1/links/{id} returns { "link": { … } } with every field of the link object. A deleted link, or a link of another team, answers 404 not_found.

curl https://qr-redirect-vercel.vercel.app/api/v1/links/menu -H "Authorization: Bearer qr_your_key"

Update a link

PATCH /api/v1/links/{id} changes where a printed code leads. The code itself stays the same, and the change applies from the next scan. Send only the fields you want to change:

curl -X PATCH https://qr-redirect-vercel.vercel.app/api/v1/links/menu \
  -H "Authorization: Bearer qr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/winter-menu"}'

Fields: target_url (or long_url), label, status (active, paused, archived), expires_at, expiry_behavior, default_utm, append_utm, pass_through_query, tags. The rules are the same as for creating. Two differences: expires_at may be in the past (the response then carries "expired": true), and null or an empty string clears expires_at, default_utm or tags. The short id cannot be changed.

Response 200: { "link": { … } } with the updated object. A body without any of these fields answers 400 empty_update. Bringing an archived link back counts against the active-code limit and can answer 403 limit_reached. Every change of target, status, label or expiry is written to the link's history in the dashboard, marked as made by the API.

Delete a link

DELETE /api/v1/links/{id} answers 200 { "ok": true }. The link disappears from lists, and the printed code shows the inactive page. Its scan history is kept. The short id is retired for good: nobody, including you, can register it again. To switch a code off for a while, use "status": "paused". To keep it out of the way and free a slot, use "archived". Both can be undone.

Statistics

GET /api/v1/links/{short_id}/stats returns the scan report of one code, GET /api/v1/analytics the report of the whole team. Both take the same query parameters as the dashboard: range=7|30|90|all or from=YYYY-MM-DD&to=YYYY-MM-DD, tz=<IANA timezone> (default: the team timezone, else UTC) and bots=1 to include bots and link previews. Numbers count people only unless bots=1 is given.

curl "https://qr-redirect-vercel.vercel.app/api/v1/links/aB3k9x/stats?range=30&tz=Asia/Dubai" \
  -H "Authorization: Bearer qr_your_key"

Response fields: totals (total, uniques, last24h, bots, inactive), daily and hourly series (zero-filled), and breakdowns byCountry, byCity, byChannel, byDevice, byOs, byBrowser, byReferrer, byOutcome. The team report adds top (codes by scans).

Rate limit: 120 requests per minute per key. Above that the API answers 429 with Retry-After.

Errors

Every error is JSON with a readable message and a stable machine code:

{ "error": "Slug is taken", "code": "slug_taken" }

Fair-use limits

QR Service is free. To protect the shared infrastructure, a team can hold up to 1,000 active QR codes and 25 members. Archived and deleted codes do not count. Reaching the limit answers 403 limit_reached, and existing codes keep working. A team can have up to 50 API keys. One list request returns at most 200 links. Keep automated traffic reasonable: we may rate-limit clients that put the service at risk. If you need more room, write to hello@beizstudio.com.

What a scan returns

A QR code encodes https://qr-redirect-vercel.vercel.app/<short_id>. What a scanner gets back:

Every case except 302 shows the branded page "This QR code is not active". Preview it at /inactive?reason=paused (also unknown, expired, archived, deleted); the preview always answers 200. HEAD requests return the same status and are not counted as scans. Custom ids are not case-sensitive: /Menu finds /menu.

Help

Questions and bug reports: hello@beizstudio.com.

← Create a key in the dashboard