QR Codes API

Create and manage QR codes linked to your short URLs. Customize colors, size, and error correction level. Download QR code images in PNG or SVG format for print and digital use.

The QR code object

A QR code is always associated with a link. When the QR code is scanned, the user is redirected through the short URL, so all click analytics are captured automatically.

Field	Type	Description
id	string	Unique QR code identifier (e.g. `qr_abc123`)
link_id	string	The associated link ID
short_url	string	The short URL encoded in the QR code
foreground_color	string	Hex color for the QR code modules (default: `#000000`)
background_color	string	Hex color for the background (default: `#ffffff`)
size	integer	Image size in pixels (default: 512, min: 128, max: 2048)
error_correction	string	Error correction level: `L`, `M`, `Q`, `H` (default: `M`)
logo_url	string \| null	URL of a logo image to embed in the center
scans	number	Total scan count
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

List QR codes

Retrieve a paginated list of QR codes in the workspace. Each QR code includes its associated link information and scan count.

GET/api/v1/qr-codes

Request

curl "https://mask.pk/api/v1/qr-codes?limit=10" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    {
      "id": "qr_abc123",
      "link_id": "lnk_abc123",
      "short_url": "https://mask.pk/my-link",
      "foreground_color": "#000000",
      "background_color": "#ffffff",
      "size": 512,
      "error_correction": "M",
      "logo_url": null,
      "scans": 847,
      "created_at": "2026-03-10T09:00:00Z",
      "updated_at": "2026-03-10T09:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "cursor": null
  }
}

Create a QR code

Create a new QR code for an existing link. You can customize the colors, size, error correction level, and embed a logo. If no customization is provided, a standard black-on-white 512px QR code is generated.

POST/api/v1/qr-codes

Request body

Field	Type	Required	Description
link_id	string	Yes	The link ID to generate a QR code for
foreground_color	string	No	Hex color for QR modules (default: `#000000`)
background_color	string	No	Hex color for background (default: `#ffffff`)
size	integer	No	Image size in pixels (128-2048, default: 512)
error_correction	string	No	Error correction level: L, M, Q, H (default: M). Use H when embedding a logo.
logo_url	string	No	URL of a logo to embed in the center of the QR code

Request

curl -X POST https://mask.pk/api/v1/qr-codes \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "link_id": "lnk_abc123",
    "foreground_color": "#1a1a1a",
    "background_color": "#ffffff",
    "size": 1024,
    "error_correction": "H",
    "logo_url": "https://cdn.yourbrand.com/logo.png"
  }'

Response — 201 Created

{
  "id": "qr_def456",
  "link_id": "lnk_abc123",
  "short_url": "https://mask.pk/my-link",
  "foreground_color": "#1a1a1a",
  "background_color": "#ffffff",
  "size": 1024,
  "error_correction": "H",
  "logo_url": "https://cdn.yourbrand.com/logo.png",
  "scans": 0,
  "created_at": "2026-03-24T14:00:00Z",
  "updated_at": "2026-03-24T14:00:00Z"
}

Get a QR code

Retrieve a single QR code by its ID, including configuration and scan count.

GET/api/v1/qr-codes/:id

Request

curl https://mask.pk/api/v1/qr-codes/qr_def456 \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "id": "qr_def456",
  "link_id": "lnk_abc123",
  "short_url": "https://mask.pk/my-link",
  "foreground_color": "#1a1a1a",
  "background_color": "#ffffff",
  "size": 1024,
  "error_correction": "H",
  "logo_url": "https://cdn.yourbrand.com/logo.png",
  "scans": 847,
  "created_at": "2026-03-24T14:00:00Z",
  "updated_at": "2026-03-24T14:00:00Z"
}

Download QR code image

Download the QR code as an image file. Use the format query parameter to choose between PNG (default) and SVG. The response is the raw image binary with the appropriate Content-Type header.

GET/api/v1/qr-codes/:id/image

Query parameters

Parameter	Type	Description
format	string	`png` (default) or `svg`
size	integer	Override the image size for this download (128-2048). Only applies to PNG.

Download as PNG

curl "https://mask.pk/api/v1/qr-codes/qr_def456/image?format=png&size=1024" \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -o qr-code.png

Download as SVG

curl "https://mask.pk/api/v1/qr-codes/qr_def456/image?format=svg" \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -o qr-code.svg

The PNG response has Content-Type: image/png and the SVG response has Content-Type: image/svg+xml. Use SVG for print materials where vector resolution is needed.