Beta

Generate QR codes from your own backend.

One REST endpoint takes a QR spec and returns a PNG or SVG — no UI, no rendering on your side. Sign in, create an API key from your dashboard, and you're ready to call it. Dynamic codes you can edit later are supported too.

Quick start

Send a POST request with your key in the Authorization header. The response body is the raw image — write it straight to a file.

curl -X POST https://ywhutayfwmfltrezwoll.supabase.co/functions/v1/api-qr \
  -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","url":"https://example.com"}' \
  -o qr.png

The key uses the Bearer prefix because that's the standard way to pass a token in an HTTP header — this is plain API-key auth, not OAuth. Keys are long-lived and account-level; create and revoke them under API Keys in your dashboard.

Keep your key on the server

Call the API from your own backend and keep the key in an environment variable. Never put it in browser JavaScript or a mobile app: the endpoint accepts requests from any origin, so anyone who sees the key can spend your request limits. If a key leaks, revoke it under API Keys and create a new one.

Try it

Send a real request from this page with your own key and see the result. For production, call the API from your server instead.

Sent only to the API, never stored. Each try counts as one API call. Use a key you can revoke.

Dynamic codes

Send "dynamic": true with a url (optionally ios_url, android_url, label, campaign, location) to create a code you can re-point later. They share the dynamic-code limit with your dashboard./v1/qr is an alias of the endpoint above.

# Create — counts against your plan's dynamic-code limit
curl -X POST https://qrinst.mdxtora.com/v1/qr   -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"   -H "Content-Type: application/json"   -d '{"dynamic":true,"url":"https://example.com/menu","label":"Menu"}'
# -> 201 {"code":"Ab3dEf9","redirect_url":"https://qrinst.mdxtora.com/r/Ab3dEf9","image":"<base64 PNG>", ...}

# Change where it points (printed codes keep working)
curl -X PATCH https://qrinst.mdxtora.com/v1/qr/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"   -H "Content-Type: application/json" -d '{"url":"https://example.com/new-menu"}'

curl https://qrinst.mdxtora.com/v1/qr/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"            # read
curl -X DELETE https://qrinst.mdxtora.com/v1/qr/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"  # delete

Bulk (Dev Plus)

Up to 50 static codes per request. Each valid item counts as one API call; if your remaining monthly quota can't cover the batch it is rejected and nothing is charged. Items that fail validation come back with an error at their index and are not charged.

curl -X POST https://qrinst.mdxtora.com/v1/qr/bulk   -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"   -H "Content-Type: application/json"   -d '{"items":[{"type":"url","url":"https://a.com"},{"type":"text","text":"hello"}]}'
# -> {"count":2,"charged":2,"results":[{"index":0,"ok":true,"image_format":"png","image":"<base64>"}, ...]}

Rotating codes (Dev Plus)

Up to 5 per account. Rotation runs on our servers and does not use your API quota: you create the code once. Schedule codes keep the same printed QR and send scanners to the slot that matches the local time (breakfast, lunch, closed). Token codes are for a screen: display_url shows a QR that refreshes every period_seconds (30–3600). A scan is accepted for the current window and the one before it; with single_use the first scan of a window uses it up (the second person sees "expired"). Keep display_url private: it contains the key that shows the live code. Scans through a link preview bot are ignored. Scans of rotating codes update the code's total scan count only (no detailed history yet).

# 1) Schedule: the printed QR never changes, the destination follows the clock
curl -X POST https://qrinst.mdxtora.com/v1/rotating \
  -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{
    "mode": "schedule", "timezone": "Asia/Kolkata", "label": "Cafe menu",
    "fallback_url": "https://example.com/menu/all-day",
    "slots": [
      {"from": "06:00", "to": "11:00", "url": "https://example.com/menu/breakfast"},
      {"days": [1,2,3,4,5], "from": "12:00", "to": "15:00", "url": "https://example.com/menu/lunch"}
    ]
  }'
# -> 201 {"code":"Ab3dEf9","scan_url":"https://qrinst.mdxtora.com/x/Ab3dEf9","image":"<base64 PNG of scan_url>", ...}

# 2) Token: a screen shows a QR that changes every period; old ones expire
curl -X POST https://qrinst.mdxtora.com/v1/rotating \
  -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{"mode":"token","url":"https://example.com/check-in","period_seconds":30,"single_use":true}'
# -> 201 {"code":"Zk8mQ2p","display_url":"https://qrinst.mdxtora.com/live/Zk8mQ2p#k=...", ...}
# Open display_url full-screen on the venue's screen. Nothing else to call.

curl https://qrinst.mdxtora.com/v1/rotating -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"                # list
curl https://qrinst.mdxtora.com/v1/rotating/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"        # read
curl -X PATCH https://qrinst.mdxtora.com/v1/rotating/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" -d '{"fallback_url":"https://example.com/closed"}'
curl -X DELETE https://qrinst.mdxtora.com/v1/rotating/Ab3dEf9 -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"

Advanced branding (Dev Plus)

Add a branding object to a static request for the same styling as the dashboard: colors and gradient (fg, bg, gradientTo, gradientType, eyeColor), shapes (moduleShape, eyeFrame, eyeBall), frames (frame, frameText, frameFont, frameBorder, frameCorner) and a logo as a base64 PNG/JPEG/WebP/GIF data URL under 150 KB (with logoScale 0.14–0.30). Colors are hex. Branded codes are returned as SVG, so set "format": "svg". A logo switches error correction to the highest level; check that the result still scans.

curl -X POST https://qrinst.mdxtora.com/v1/qr \
  -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{
    "type": "url", "url": "https://example.com", "format": "svg", "size": 600,
    "branding": {
      "fg": "#1d4ed8", "gradientTo": "#9333ea", "gradientType": "linear",
      "moduleShape": "dots", "eyeFrame": "rounded", "eyeBall": "circle",
      "frame": "scanme", "frameText": "SCAN ME", "frameFont": "rounded",
      "logo": "data:image/png;base64,iVBORw0KGgo...", "logoScale": 0.22
    }
  }' -o branded.svg

Webhooks (Dev Plus)

Get an HTTPS callback when a code is created (qr.created), when your monthly tracked-scan cap is reached (qr.scan_cap_reached) or at 80% of a quota (quota.80_percent). Deliveries are signed, retried up to 6 times over about 14 hours, and answer with any 2xx. Events are delivered at least once, so de-duplicate on the event id.

# Register (secret is shown once)
curl -X POST https://qrinst.mdxtora.com/v1/webhooks \
  -H "Authorization: Bearer qri_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/qrinst","events":["qr.created","quota.80_percent"]}'
# -> 201 {"id":"...","url":"...","events":[...],"secret":"whsec_..."}

# Delivery: POST with JSON {"id","type","created_at","data"} and headers
#   X-QRinst-Event, X-QRinst-Delivery, X-QRinst-Signature: t=1700000000,v1=<hex>
# Verify: HMAC-SHA256(secret, t + "." + rawBody) must equal v1; reject old t.

curl https://qrinst.mdxtora.com/v1/webhooks -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"                     # list
curl https://qrinst.mdxtora.com/v1/webhooks/<id>/deliveries -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"     # log
curl -X DELETE https://qrinst.mdxtora.com/v1/webhooks/<id> -H "Authorization: Bearer qri_live_xxxxxxxxxxxx"

Request body

FieldRequiredNotes
typeyesOne of the 12 static types listed below.
sizenoPixels, 64–2000. Default 512.
formatno"png" (default) or "svg".
type-specificvariesEach type has its own fields — see Fields by type below for the full list per type.
urltextwifiemailphonesmsvcardwhatsappeventsociallocationbitcoin

Dashboard-only types (pdf, image, video, app, bizcard, menu) return 400 INVALID_TYPE — they need a stored record and a redirect, which this endpoint doesn't create. To get an image for a dynamic code, create it in your dashboard and send its short link (https://…/r/CODE) here as type: "url".

The API returns a plain black-and-white QR code. Logos, frames, colours and custom shapes are available in the web generator only.

Fields by type

Exact request-body fields for each static type. Omitted optional fields default to empty; unlisted fields are ignored.

url
  • url requiredBare domains get https:// prepended automatically.
text
  • text required
wifi
  • ssid required
  • password optionalRequired unless security is "nopass".
  • security optional"WPA" | "WEP" | "nopass" — WPA2/WPA3/none/open aliases accepted. Defaults to WPA if password is set, else nopass.
  • hidden optionaltrue/false, default false.
email
  • to required
  • subject optional
  • body optional
phone
  • phone required
sms
  • phone required
  • message optional
vcard
  • firstName optionalAt least one of firstName/lastName is required.
  • lastName optional
  • org optional
  • title optional
  • phone optional
  • email optional
  • website optional
  • address optional
whatsapp
  • phone required
  • message optional
event
  • title required
  • start requirede.g. 2026-09-23T10:00
  • end optional
  • location optional
  • description optional
social
  • platform requiredinstagram | x | facebook | linkedin | tiktok | youtube | github
  • handle requiredLeading @ is stripped automatically.
location
  • query optionalAlone, used as a Google Maps search. Also doubles as a label next to lat/lng.
  • lat optionalProvide together with lng for a geo: URI.
  • lng optional
bitcoin
  • address required
  • amount optional
  • label optional
  • message optional

Response

On success you get 200 with the image bytes directly — image/png or image/svg+xml, no JSON wrapper. Every response also carries the current rate-limit state in headers.

HTTP/1.1 200 OK
Content-Type: image/png
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Month: 3000
X-RateLimit-Remaining-Month: 2999

‹binary PNG data›
qr.png
  • X-RateLimit-Limit-Minute
  • X-RateLimit-Remaining-Minute
  • X-RateLimit-Limit-Month
  • X-RateLimit-Remaining-Month

Errors

Errors come back as JSON with a stable, machine-readable code — branch on that, not the message.

{ "error": { "code": "INVALID_TYPE", "message": "\"type\" must be one of: url, text, …" } }
CodeHTTPWhen
METHOD_NOT_ALLOWED405Wrong method for the URL: POST /qr creates; GET, PATCH, DELETE go on /qr/{code}.
FEATURE_NOT_INCLUDED403Bulk, webhooks, branding and rotating codes need the Dev Plus plan. Includes an upgrade_url.
BULK_TOO_LARGE400More than 50 items in one bulk request.
ROTATING_LIMIT_REACHED409You already have 5 rotating codes. Delete one first.
BRANDING_REQUIRES_SVG400"branding" was sent without "format": "svg".
WEBHOOK_LIMIT_REACHED409You already have 5 webhooks. Delete one first.
WEBHOOK_NOT_FOUND404No webhook with that id on your account.
CODE_NOT_FOUND404No dynamic code with that id on your account.
CODE_LOCKED403Code is locked after a plan downgrade; it still redirects. Upgrade to edit.
FREE_QUOTA_EXCEEDED409Your plan's dynamic-code limit is reached. Includes an upgrade_url.
MISSING_API_KEY401No Authorization header, or it isn't a qri_live_ key.
INVALID_API_KEY401Key not found or revoked.
INVALID_BODY400Request body isn't valid JSON.
INVALID_TYPE400"type" missing or not a supported static type.
INVALID_FIELDS400Required fields for that type are missing or malformed.
EMPTY_CONTENT400Fields resolved to nothing to encode.
ENCODING_FAILED400Content is too long for a QR code at this size.
API_NOT_INCLUDED403Your plan has no API access. Includes an upgrade_url.
API_KEY_DISABLED403After a downgrade, keys beyond your plan's key limit pause (newest first) until you upgrade or revoke others.
RATE_LIMITED429Per-minute limit hit. Includes a Retry-After header and an upgrade_url.
MONTHLY_QUOTA_EXCEEDED429Monthly request quota used up. Includes an upgrade_url.

Rate limits

The monthly quota is per account and shared by all your keys, so creating more keys doesn't raise it. The Free plan is for testing; the Pro plan doesn't include API access. When a limit is hit the API answers 429 with an upgrade_url and the X-RateLimit-* headers. Codes you've already created keep redirecting whatever your API usage.

PlanAPI keysRequests / monthRequests / minute
Free110010
ProNot included
Developer23,00060
Dev Plus515,000120

What's next

Dynamic QR over REST

Create a code, then change its destination and pull scan analytics from your own backend.

Sign in below, then create your API key from your dashboard.

Sign in to sync codes across devices: