API documentation

Authentication

Create a key under API keys and send it as a bearer token. Keys are shown once — store them somewhere safe. The API requires a Pro or Business plan.

# every request
curl https://qr.seabirds-games.com/api/v1/codes \
  -H "Authorization: Bearer qf_live_…"

Render a static QR code

No key needed for the image endpoints — they are rate limited per IP. Use these directly in an <img> tag.

GET https://qr.seabirds-games.com/qr.png?data=https://example.com&size=512&dark=%23111111
GET https://qr.seabirds-games.com/qr.svg?data=https://example.com&shape=dot&ecl=H

Parameter	Values
data	Content to encode (required, max 2000 chars)
size	64–4096 px (PNG), default 512
ecl	L, M, Q, H — default M
dark	Hex colour, URL-encoded (%23111111)
light	Hex background colour
shape	square, dot, rounded
eye	square, rounded, circle
margin	Quiet zone in modules, 0–16 (default 4)
gradient	Second hex colour; enables a linear gradient

Create a dynamic code

curl -X POST https://qr.seabirds-games.com/api/v1/codes \
  -H "Authorization: Bearer qf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com/menu","title":"Table tent","slug":"menu-fr"}'

→ 201
{
  "id": "K3n8QpZr2mTx",
  "slug": "menu-fr",
  "short_url": "https://qr.seabirds-games.com/r/menu-fr",
  "target": "https://example.com/menu",
  "png_url": "https://qr.seabirds-games.com/qr.png?data=https%3A%2F%2Fqr.seabirds-games.com%2Fr%2Fmenu-fr",
  "scan_count": 0
}

Re-point a code

curl -X PATCH https://qr.seabirds-games.com/api/v1/codes/K3n8QpZr2mTx \
  -H "Authorization: Bearer qf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com/winter-menu"}'

Read analytics

curl "https://qr.seabirds-games.com/api/v1/codes/K3n8QpZr2mTx/analytics?days=30" \
  -H "Authorization: Bearer qf_live_…"

→ 200
{
  "total_scans": 1284,
  "unique_scans": 977,
  "by_day": [{ "day": "2026-05-01", "n": 42 }],
  "by_device": [{ "key": "mobile", "n": 1180 }],
  "by_os": […], "by_browser": […], "by_referrer": […]
}

Endpoints

Method	Path	Purpose
GET	/api/v1/codes	List your dynamic codes
POST	/api/v1/codes	Create one
GET	/api/v1/codes/:id	Fetch one
PATCH	/api/v1/codes/:id	Update target, title, design or active flag
DELETE	/api/v1/codes/:id	Delete it and its scan history
GET	/api/v1/codes/:id/analytics	Aggregated scan data
POST	/api/v1/qr	Render a code, returns base64 PNG or SVG
GET	/api/v1/me	Plan, limits and usage this month

Errors & limits

Errors are JSON: {"error":{"code":"…","message":"…"}} with a matching HTTP status. Every response carries X-RateLimit-Remaining. Exceeding your plan's monthly call budget returns 429.