QR Codes API

Generate and customize QR code images for any short link

Every AWSYS.CO short link has a built-in QR code endpoint that returns a PNG image. You can customize the size, foreground color, and background color via query parameters. Pro and higher accounts can also save persistent QR style settings (color, logo, error correction level) per link.

Base URL

https://awsys.co

Authentication

QR code generation (GET /api/qr/*) is public — no authentication required. QR settings endpoints (PUT /api/link/*/qr-settings) require a Bearer token.

Generate a QR Code (PNG)

Standard short link

GET /api/qr/:short

Namespaced link

GET /api/qr/:prefix/:slug

Both endpoints return a image/png response. Responses are cached for 1 hour.

Query parameters

Parameter	Type	Default	Description
`size`	integer	300	Image size in pixels (100–1000)
`color`	string	000000	Foreground hex color, without `#` (e.g. `1a56db`)
`bgColor`	string	FFFFFF	Background hex color, without `#`

Examples

# Default 300px black-on-white QR
curl https://awsys.co/api/qr/abc123 --output qr.png

# Custom: 500px, dark blue on white
curl "https://awsys.co/api/qr/abc123?size=500&color=1a56db" --output qr.png

# Namespaced link
curl "https://awsys.co/api/qr/mybrand/campaign" --output qr.png

Tip: You can embed the QR URL directly in an <img> tag in your application without downloading the file. The endpoint serves the PNG with appropriate cache headers.

Save QR Settings (Pro+)

Standard link

PUT /api/link/:short/qr-settings

Namespaced link

PUT /api/link/:prefix/:slug/qr-settings

Saves persistent QR customization settings for a specific link. These settings are used by the dashboard QR preview and by the MCP get_qr_settings tool.

Request body

{
  "size": 400,
  "color": "#1a56db",
  "bgColor": "#FFFFFF",
  "errorLevel": "M",
  "logoDataUrl": "data:image/png;base64,...",
  "logoSize": 20
}

Field	Type	Default	Description
`size`	integer	300	QR image size in pixels (100–1000)
`color`	string	#000000	Foreground hex color
`bgColor`	string	#FFFFFF	Background hex color
`errorLevel`	string	M	Error correction level: `L`, `M`, `Q`, or `H`. Use `H` if embedding a logo.
`logoDataUrl`	string	—	Base64 data URL of a logo image to embed (max 150 KB). Pass `null` to remove.
`logoSize`	integer	20	Logo size as a percentage of QR width (10–35)

Response — 200 OK

{
  "success": true,
  "qrSettings": {
    "size": 400,
    "color": "#1a56db",
    "bgColor": "#FFFFFF",
    "errorLevel": "M",
    "logoSize": 20,
    "updatedAt": "2026-05-29T12:00:00Z"
  }
}

curl example

curl -X PUT https://awsys.co/api/link/abc123/qr-settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": 400, "color": "#1a56db", "errorLevel": "H"}'

Error Codes

HTTP	Description
404	Link not found — the short code does not exist
403	Access denied — the link belongs to a different user (settings endpoint only)
500	Failed to generate QR code — internal error