QR Codes API

Overview

The Codes API is the core of qr3.app. Use it to create, update, and delete dynamic and static QR codes.

Base URL: https://qr3.app/v1/codes

Create a QR Code

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "My first QR code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'My first QR code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "My QR code" --tags marketing,q1

Response (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "status": "live",
    "is_dynamic": true,
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz" }
}

List QR Codes

`GET /v1/codes`

GET /v1/codes?limit=20&status=live&type=url

Supported query parameters: limit, cursor, status (live/paused/archived), type, tags, search.

Get a QR Code

`GET /v1/codes/:id`

GET /v1/codes/qr_a1b2c3d4

Update a QR Code

`PATCH /v1/codes/:id`

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://new-destination.com", "status": "live"}'

Landing page & external links

For dynamic url codes you can set is_landing_page: true (on create or via PATCH). A scan then renders a qr3-hosted page listing the code’s public files and external links instead of redirecting. External links are sent as a links array:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datasheet", "url": "https://example.com/datasheet.pdf" },
    { "label": "Certificate", "url": "https://example.com/certificate.pdf" }
  ]
}

0–20 links per code; label is 1–100 characters; url must be http(s) (≤ 2048 characters).
Each URL is checked with Google Web Risk — an unsafe URL returns 422.
If Web Risk is unreachable when you save, the link is still accepted but flagged for re-scan. A daily job re-checks stored links (and periodically re-checks clean ones) and automatically pauses the code if a link is later found unsafe.
Sending "links": [] clears all links. See the Landing page guide.

Delete a QR Code

`DELETE /v1/codes/:id`

Soft-deletes the code. Active scans are preserved for analytics.

QR Code Types

Type	Content encoded
`url`	URL or redirect short link
`vcard`	vCard 3.0 contact information
`wifi`	Wi-Fi connection (SSID, password, encryption)
`email`	`mailto:` with pre-filled subject and body
`sms`	`smsto:` with pre-filled message
`location`	`geo:` coordinates
`text`	Plain text
`phone`	Phone number (tel:)
`event`	Calendar event (BEGIN:VCALENDAR)

QR Code Images

Every code exposes four image URLs:

GET /v1/codes/:shortCode/qr.svg    → SVG vector (scalable)
GET /v1/codes/:shortCode/qr.png    → PNG raster
GET /v1/codes/:shortCode/qr.pdf    → Vector PDF (square by default, or A4)
GET /v1/codes/:shortCode/qr.eps    → EPS vector (pro print workflows)

Optional query params: size (2–20 modules per pixel; SVG/PNG/EPS only), format (square default — code plus its required quiet zone, no A4 whitespace — or a4 for a printable sheet), title.