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.pngThe 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" # deleteBulk (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.svgWebhooks (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
| Field | Required | Notes |
|---|---|---|
| type | yes | One of the 12 static types listed below. |
| size | no | Pixels, 64–2000. Default 512. |
| format | no | "png" (default) or "svg". |
| type-specific | varies | Each type has its own fields — see Fields by type below for the full list per type. |
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 requiredBare domains get https:// prepended automatically.
- text required
- 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.
- to required
- subject optional
- body optional
- phone required
- phone required
- message optional
- firstName optionalAt least one of firstName/lastName is required.
- lastName optional
- org optional
- title optional
- phone optional
- email optional
- website optional
- address optional
- phone required
- message optional
- title required
- start requirede.g. 2026-09-23T10:00
- end optional
- location optional
- description optional
- platform requiredinstagram | x | facebook | linkedin | tiktok | youtube | github
- handle requiredLeading @ is stripped automatically.
- 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
- 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›- 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, …" } }| Code | HTTP | When |
|---|---|---|
| METHOD_NOT_ALLOWED | 405 | Wrong method for the URL: POST /qr creates; GET, PATCH, DELETE go on /qr/{code}. |
| FEATURE_NOT_INCLUDED | 403 | Bulk, webhooks, branding and rotating codes need the Dev Plus plan. Includes an upgrade_url. |
| BULK_TOO_LARGE | 400 | More than 50 items in one bulk request. |
| ROTATING_LIMIT_REACHED | 409 | You already have 5 rotating codes. Delete one first. |
| BRANDING_REQUIRES_SVG | 400 | "branding" was sent without "format": "svg". |
| WEBHOOK_LIMIT_REACHED | 409 | You already have 5 webhooks. Delete one first. |
| WEBHOOK_NOT_FOUND | 404 | No webhook with that id on your account. |
| CODE_NOT_FOUND | 404 | No dynamic code with that id on your account. |
| CODE_LOCKED | 403 | Code is locked after a plan downgrade; it still redirects. Upgrade to edit. |
| FREE_QUOTA_EXCEEDED | 409 | Your plan's dynamic-code limit is reached. Includes an upgrade_url. |
| MISSING_API_KEY | 401 | No Authorization header, or it isn't a qri_live_ key. |
| INVALID_API_KEY | 401 | Key not found or revoked. |
| INVALID_BODY | 400 | Request body isn't valid JSON. |
| INVALID_TYPE | 400 | "type" missing or not a supported static type. |
| INVALID_FIELDS | 400 | Required fields for that type are missing or malformed. |
| EMPTY_CONTENT | 400 | Fields resolved to nothing to encode. |
| ENCODING_FAILED | 400 | Content is too long for a QR code at this size. |
| API_NOT_INCLUDED | 403 | Your plan has no API access. Includes an upgrade_url. |
| API_KEY_DISABLED | 403 | After a downgrade, keys beyond your plan's key limit pause (newest first) until you upgrade or revoke others. |
| RATE_LIMITED | 429 | Per-minute limit hit. Includes a Retry-After header and an upgrade_url. |
| MONTHLY_QUOTA_EXCEEDED | 429 | Monthly 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.
| Plan | API keys | Requests / month | Requests / minute |
|---|---|---|---|
| Free | 1 | 100 | 10 |
| Pro | Not included | ||
| Developer | 2 | 3,000 | 60 |
| Dev Plus | 5 | 15,000 | 120 |
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: