API Documentation

Integrate QR code generation into your application in minutes.

Need help? Email us at support@scanstack.dev

Authentication

All API endpoints require an API key. Include it via header or query parameter:

curl https://api.scanstack.dev/qr/dynamic \
  -H "x-api-key: qr_your_api_key_here"

Or as a query parameter: ?api_key=qr_your_api_key_here

Get your API key from your Account Settings.

Endpoints

GET /health

Health check endpoint. No authentication required.

POST https://api.scanstack.dev/qr/static

Generate a static QR code image.

{
  "type": "url",
  "data": { "url": "https://example.com" },
  "format": "png",
  "style": {
    "width": 512,
    "foregroundColor": "#1a1a2e",
    "backgroundColor": "#FFFFFF",
    "cornerRadius": 20,
    "logoUrl": "https://example.com/logo.png",
    "logoScale": 0.2
  }
}

Supported types

Type	Data Fields
url	`url`
wifi	`ssid`, `password`, `encryption`, `hidden`
vcard	`name`, `organization`, `phone`, `email`, `url`, `address`
email	`to`, `subject`, `body`
sms	`phone`, `message`
text	`text`

POST https://api.scanstack.dev/qr/dynamic

Create a dynamic QR code with a trackable short link.

{
  "type": "url",
  "data": { "url": "https://example.com" },
  "label": "Marketing Campaign Q1",
  "format": "base64"
}

Response includes id, short_code, redirect_url, and qr_image.

PATCH https://api.scanstack.dev/qr/dynamic/:id

Update the target URL of a dynamic QR code.

{ "target_url": "https://new-destination.com" }

DELETE https://api.scanstack.dev/qr/dynamic/:id

Deactivate a dynamic QR code. The short link will stop redirecting.

GET https://api.scanstack.dev/qr/dynamic

List all your dynamic QR codes. Supports ?limit=20&offset=0.

GET https://api.scanstack.dev/analytics/:id/stats

Get scan analytics for a QR code. Supports ?days=30.

Style Options

Option	Type	Default	Description
width	number	512	Image width (64-2048)
margin	number	2	Quiet zone (0-10)
foregroundColor	string	#000000	Hex color for modules
backgroundColor	string	#FFFFFF	Hex color for background
errorCorrectionLevel	string	H	L, M, Q, or H
logoUrl	string	-	URL to logo image
logoBase64	string	-	Base64-encoded logo
logoScale	number	0.2	Logo size ratio (0.1-0.35)
cornerRadius	number	0	Rounded corners in px

v2 API — Campaigns, Routing & Webhooks

All v2 endpoints require an API key. Feature availability depends on your plan.

Conditional Redirects

Route scans to different URLs based on device, OS, country, or language. Rules are evaluated by priority (highest first). A default rule catches everything else.

Requires Starter plan or above.

POST https://api.scanstack.dev/v2/qr/:id/rules

{
  "condition_type": "os",
  "condition_value": "ios",
  "target_url": "https://apps.apple.com/your-app",
  "priority": 10
}
// condition_type: device | os | country | language | default
// device values: mobile, tablet, desktop
// os values: ios, android, windows, macos, linux

GET https://api.scanstack.dev/v2/qr/:id/rules

DELETE https://api.scanstack.dev/v2/qr/:qrId/rules/:ruleId

A/B Testing

Split traffic between multiple URL variants with configurable weights. Track scan counts per variant.

Requires Pro plan or above.

POST https://api.scanstack.dev/v2/qr/:id/ab-test

{
  "variants": [
    { "label": "Landing A", "target_url": "https://example.com/a", "weight": 50 },
    { "label": "Landing B", "target_url": "https://example.com/b", "weight": 50 }
  ]
}

GET https://api.scanstack.dev/v2/qr/:id/ab-test — includes scan_count and conversion_rate per variant

DELETE https://api.scanstack.dev/v2/qr/:id/ab-test

Bulk QR Generation

Create up to 100 dynamic QR codes in a single request.

Requires Starter plan or above.

POST https://api.scanstack.dev/v2/bulk

{
  "items": [
    { "type": "url", "data": { "url": "https://page-1.com" }, "label": "Product 1" },
    { "type": "url", "data": { "url": "https://page-2.com" }, "label": "Product 2", "campaign_id": "camp_xxx" }
  ]
}

Campaigns

Organize QR codes into named campaigns for project-level tracking.

Requires Starter plan or above.

POST https://api.scanstack.dev/v2/campaigns — { "name": "...", "description": "..." }

GET https://api.scanstack.dev/v2/campaigns

DELETE https://api.scanstack.dev/v2/campaigns/:id

POST https://api.scanstack.dev/v2/qr/:id/campaign — { "campaign_id": "..." }

Scan Webhooks

Get real-time HTTP POST notifications when QR codes are scanned. Payload is signed with HMAC-SHA256.

Requires Pro plan or above.

POST https://api.scanstack.dev/v2/webhooks

{
  "url": "https://your-server.com/webhook",
  "events": ["scan.completed"]
}
// Available events: scan.completed, qr.created, qr.updated, qr.deactivated, *
// Response includes a signing secret (x-webhook-signature header)

GET https://api.scanstack.dev/v2/webhooks

DELETE https://api.scanstack.dev/v2/webhooks/:id

Webhooks auto-disable after 10 consecutive delivery failures.

Rate Limits

Rate limits depend on your plan:

Plan	API Requests/Day	Dynamic QR Codes
Free	100	3
Starter	5,000	50
Pro	50,000	500
Business	Unlimited	Unlimited