QRay API

Generate QR codes from your own apps with a simple REST API: all 8 data types, PNG and SVG, colors, gradients, logos and frames — everything the web generator can do.

Get an API key https://stg.qray.io/api/v1

Try it now — no signup

Paste this in your terminal. You get a real QR code back in one request:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"url","fields":{"url":"https://qray.io"},"style":{"dot_style":"rounded","gradient":{"colors":["#2563EB","#A3E635"],"angle":45}}}}' \
  -o qr.png && open qr.png

Opens qr.png (macOS; on Linux use xdg-open qr.png). No key needed — the demo allows 10 requests/hour per IP.

Authentication

Every request must include your API key in the X-Api-Key header. Create and manage keys in your dashboard.

curl https://stg.qray.io/api/v1/usage \
  -H "X-Api-Key: qray_live_YOUR_KEY"

The full key is shown only once, at creation. Store it in a secret manager — we keep only a SHA-256 digest.

Quickstart

Generate a styled QR code for a URL:

curl -X POST https://stg.qray.io/api/v1/generate \
  -H "X-Api-Key: qray_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr": {
      "type": "url",
      "fields": { "url": "https://example.com" },
      "format": "png",
      "size": 512,
      "style": {
        "fg_color": "#111113",
        "dot_style": "rounded",
        "gradient": { "colors": ["#2563EB", "#A3E635"], "angle": 45 }
      }
    }
  }'

The response contains the image as base64 plus permanent URLs:

{
  "hash": "1c9a7f2b40d861e3",
  "format": "png",
  "size": 512,
  "image": "iVBORw0KGgoAAA…",          // base64
  "image_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3.png",
  "share_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3",
  "url": "/qr/1c9a7f2b40d861e3"
}

Endpoints

Endpoint	Description
`POST /api/v1/demo`	Generate a QR image with no key (keyless demo, 10/hour per IP)
`POST /api/v1/generate`	Generate a QR code; returns a base64 image and permanent URLs
`GET /api/v1/qr_codes`	List your QR codes (50 per page, ?page=N)
`GET /api/v1/qr_codes/:hash`	Metadata for one QR code
`GET /api/v1/qr_codes/:hash/image`	Binary image (PNG/SVG); the URL never expires
`DELETE /api/v1/qr_codes/:hash`	Delete a QR code
`GET /api/v1/usage`	Current plan, daily limit and usage
`GET /api/v1/api_keys`	List your API keys
`POST /api/v1/api_keys`	Create an additional key ({"name": "…"})
`DELETE /api/v1/api_keys/:id`	Revoke a key (the key authenticating the request cannot revoke itself)

Prefer a machine-readable spec? Explore it interactively or import our OpenAPI file into Postman, Insomnia or a client generator: Interactive API explorer · openapi.yaml

QR types and fields

Pass the data type in qr.type and its fields in qr.fields:

type	fields
`url`	`url`
`text`	`text`
`wifi`	`ssid`, `password`, `encryption` (WPA \| WEP \| nopass), `hidden` (true \| false)
`vcard`	`first_name`, `last_name`, `phone`, `email`, `org`, `title`, `url`
`email`	`address`, `subject`, `body`
`phone`	`number`
`sms`	`number`, `message`
`geo`	`latitude`, `longitude`

For example, a WiFi QR your guests can scan to connect:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"wifi","fields":{"ssid":"MyCafe","password":"latte123","encryption":"WPA"}}}' \
  -o wifi.png && open wifi.png

Options and styling

Parameter	Description
`format`	`png` (default) \| `svg`
`size`	`256` \| `512` (default) \| `1024` \| `2048`
`style.fg_color`, `style.bg_color`	hex, e.g. `#111113`
`style.dot_style`	`square` (default) \| `circle` \| `rounded`
`style.eye_style`	`square` (default) \| `rounded`
`style.gradient`	`{ "colors": ["#hex", "#hex", …], "angle": 0–360 }` — two or more colors; overrides fg_color
`style.frame`	`{ "type": "scan-me" \| "custom-text", "text": "…", "color": "#hex" }` — PNG only; ignored for SVG
`style.logo_data`	PNG/JPG as raw base64 (no data: prefix), max ~500 KB. Error correction is raised automatically.

Images are cached for 24 hours and transparently regenerated afterwards — image_url is permanent and safe to hotlink.

Plans and rate limits

Each key has a daily quota that resets at midnight UTC:

Plan	Requests
free	100 requests / day
pro	10 000 requests / day
enterprise	100 000 requests / day

Every response carries the current window state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Need pro or enterprise? Write to support@qray.io and we will upgrade your key.

Errors

HTTP	`error`	Description
400	`missing_parameter`	Malformed request (e.g. missing qr parameter)
401	`unauthorized`	Missing, invalid or revoked API key
404	`not_found`	QR code not found (or owned by another account)
422	`unknown_type`	Unknown qr.type
429	`rate_limited`	Daily limit exceeded — retry after midnight UTC or upgrade the plan
503	`service_unavailable`	QR generation service temporarily unavailable — retry with backoff