API Reference
The authenticated REST API for QR code generation, analytics, and management. Available on the Developer and Pro plans.
Quick Start (Authenticated API)
Get started with our authenticated API in minutes
1. Get Your API Key
Sign up for the Developer or Pro plan to get your API key from the dashboard.
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://theqrcode.io/api/v1/qr-codes2. Create Your First QR Code
Use our simple API to generate QR codes programmatically.
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "url", "content": "https://example.com"}' \
https://theqrcode.io/api/v1/qr-codesAPI Features
Features for developers and integrations
RESTful API
Clean, intuitive REST API following industry standards with comprehensive documentation.
API Key Authentication
Secure API key-based authentication with rate limiting and usage tracking.
High Performance
Fast API responses backed by a global CDN and optimized infrastructure.
Enterprise Security
Bank-level security with encryption, audit logs, and compliance standards.
Real-time Analytics
Access comprehensive analytics data through our analytics API endpoints.
Webhook Support
Real-time notifications for QR code events with configurable webhook endpoints.
API Endpoints
Complete reference for all available API endpoints
/api/v1/qr-codesCreate a new QR code
Request Example
{
"name": "My QR Code",
"type": "url",
"content": "https://example.com",
"settings": {
"size": 256,
"color": {
"dark": "#000000",
"light": "#FFFFFF"
},
"frame": {
"style": "square",
"color": "#000000",
"size": 20
}
},
"isDynamic": false
}Request Parameters
namestringRequiredDisplay name for the QR code
typestringRequiredQR code type (url, text, wifi, contact, email, sms, vcard)
contentstringRequiredThe content to encode in the QR code
settingsobjectQR code appearance settings
settings.sizenumberQR code size in pixels (default: 256)
settings.colorobjectColor settings for the QR code
settings.color.darkstringDark color (hex code, default: #000000)
settings.color.lightstringLight color (hex code, default: #FFFFFF)
settings.frameobjectFrame settings for the QR code (Pro plan; ignored otherwise, with a warning in the response)
settings.frame.stylestringFrame style: square (no frame), rounded, circle, dashed
settings.frame.colorstringFrame color (hex code)
settings.frame.sizenumberFrame size in pixels
isDynamicbooleanWhether the QR code can be updated after creation (default: false)
Response Example
{
"id": "qr_123456789",
"name": "My QR Code",
"type": "url",
"content": "https://example.com",
"shortUrl": null,
"settings": {
"size": 256,
"color": {
"dark": "#000000",
"light": "#FFFFFF"
}
},
"isDynamic": false,
"qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}/api/v1/qr-codesList all QR codes with pagination and filtering
Request Example
{
"query": "?page=1&limit=20&type=url&isDynamic=false"
}Request Parameters
pagenumberPage number for pagination (default: 1)
limitnumberNumber of items per page (default: 20, max: 100)
typestringFilter by QR code type (url, text, wifi, contact, email, sms, vcard)
isDynamicbooleanFilter by dynamic QR codes (true/false)
searchstringSearch by QR code name or content
sortstringSort field (createdAt, updatedAt, name, scanCount)
orderstringSort order (asc, desc, default: desc)
Response Example
{
"data": [
{
"id": "qr_123456789",
"name": "My QR Code",
"type": "url",
"content": "https://example.com",
"shortUrl": null,
"settings": {
"size": 256
},
"isDynamic": false,
"scanCount": 42,
"lastScanned": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"pages": 1
}
}/api/v1/qr-codes/{id}Get specific QR code details with recent scans
Request Example
{}Response Example
{
"id": "qr_123456789",
"name": "My QR Code",
"type": "url",
"content": "https://example.com",
"shortUrl": null,
"settings": {
"size": 256
},
"isDynamic": false,
"scanCount": 42,
"lastScanned": "2024-01-15T10:30:00Z",
"recentScans": [
{
"id": "scan_123",
"scannedAt": "2024-01-15T10:30:00Z",
"device": "mobile",
"country": "US",
"browser": "Chrome",
"os": "iOS"
}
],
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}/api/v1/qr-codes/{id}Update QR code name, content, or settings
Request Example
{
"name": "Updated QR Code",
"content": "https://updated-example.com",
"settings": {
"size": 512,
"color": {
"dark": "#FF0000",
"light": "#FFFFFF"
}
}
}Request Parameters
namestringUpdated display name for the QR code
contentstringUpdated content to encode in the QR code
settingsobjectUpdated QR code appearance settings
settings.sizenumberUpdated QR code size in pixels
settings.colorobjectUpdated color settings for the QR code
settings.color.darkstringUpdated dark color (hex code)
settings.color.lightstringUpdated light color (hex code)
settings.frameobjectUpdated frame settings for the QR code (Pro plan; ignored otherwise, with a warning in the response)
settings.frame.stylestringUpdated frame style: square (no frame), rounded, circle, dashed
settings.frame.colorstringUpdated frame color (hex code)
settings.frame.sizenumberUpdated frame size in pixels
Response Example
{
"id": "qr_123456789",
"name": "Updated QR Code",
"type": "url",
"content": "https://updated-example.com",
"shortUrl": null,
"settings": {
"size": 512,
"color": {
"dark": "#FF0000",
"light": "#FFFFFF"
}
},
"isDynamic": false,
"qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T11:00:00Z"
}/api/v1/qr-codes/{id}Delete a QR code and all associated data
Request Example
{}Response Example
null
/api/v1/qr-codes/bulkCreate multiple QR codes in a single request (up to 100)
Request Example
{
"qrCodes": [
{
"name": "Product 1 QR",
"type": "url",
"content": "https://example.com/product1",
"settings": {
"size": 256,
"color": {
"dark": "#000000",
"light": "#FFFFFF"
}
},
"isDynamic": false
},
{
"name": "Product 2 QR",
"type": "url",
"content": "https://example.com/product2",
"settings": {
"size": 256,
"color": {
"dark": "#0000FF",
"light": "#FFFFFF"
}
},
"isDynamic": true
}
]
}Request Parameters
qrCodesarrayRequiredArray of QR codes to create (max 100)
qrCodes[].namestringRequiredDisplay name for the QR code
qrCodes[].typestringRequiredQR code type (url, text, wifi, contact, email, sms, vcard)
qrCodes[].contentstringRequiredThe content to encode in the QR code
qrCodes[].settingsobjectQR code appearance settings
qrCodes[].settings.sizenumberQR code size in pixels (default: 256)
qrCodes[].settings.colorobjectColor settings for the QR code
qrCodes[].isDynamicbooleanWhether the QR code can be updated after creation (default: false)
Response Example
{
"created": [
{
"id": "qr_123456789",
"name": "Product 1 QR",
"type": "url",
"content": "https://example.com/product1",
"shortUrl": null,
"settings": {
"size": 256,
"color": {
"dark": "#000000",
"light": "#FFFFFF"
}
},
"isDynamic": false,
"qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
},
{
"id": "qr_987654321",
"name": "Product 2 QR",
"type": "url",
"content": "https://example.com/product2",
"shortUrl": "https://qr.io/abc123",
"settings": {
"size": 256,
"color": {
"dark": "#0000FF",
"light": "#FFFFFF"
}
},
"isDynamic": true,
"qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"createdAt": "2024-01-15T10:30:01Z",
"updatedAt": "2024-01-15T10:30:01Z"
}
],
"errors": [],
"summary": {
"total": 2,
"successful": 2,
"failed": 0
}
}/api/v1/qr-codes/bulkDelete multiple QR codes in a single request (up to 100)
Request Example
{
"qrCodeIds": [
"qr_123456789",
"qr_987654321",
"qr_111222333"
]
}Request Parameters
qrCodeIdsarrayRequiredArray of QR code IDs to delete (max 100)
Response Example
{
"deleted": 2,
"notFound": [
"qr_111222333"
],
"summary": {
"total": 3,
"deleted": 2,
"notFound": 1
}
}/api/v1/analyticsGet comprehensive analytics data
Request Example
{
"query": "?qrCodeId=qr_123&timeRange=30d&includeScans=true"
}Request Parameters
qrCodeIdstringSpecific QR code ID to get analytics for
timeRangestringTime range for analytics (1h, 1d, 7d, 30d, 90d, 1y, default: 30d)
includeScansbooleanInclude individual scan data in response (default: false)
startDatestringStart date for custom range (ISO 8601 format)
endDatestringEnd date for custom range (ISO 8601 format)
groupBystringGroup analytics by (hour, day, week, month)
timezonestringTimezone for date grouping (default: UTC)
Response Example
{
"summary": {
"totalScans": 1250,
"totalQRCodes": 5,
"timeRange": "30d",
"startDate": "2024-01-01T00:00:00Z",
"endDate": "2024-01-31T23:59:59Z",
"uniqueVisitors": 850,
"avgScansPerQR": 250,
"mostActiveDay": "2024-01-15"
},
"breakdowns": {
"devices": {
"mobile": 800,
"desktop": 300,
"tablet": 150
},
"countries": {
"US": 600,
"CA": 300,
"UK": 200,
"DE": 150
},
"browsers": {
"Chrome": 700,
"Safari": 300,
"Firefox": 150,
"Edge": 100
},
"os": {
"iOS": 400,
"Android": 400,
"Windows": 300,
"macOS": 150
}
},
"distributions": {
"hourly": [
{
"hour": 0,
"count": 10
},
{
"hour": 1,
"count": 5
}
],
"weekly": [
{
"day": 0,
"count": 200
},
{
"day": 1,
"count": 180
}
]
},
"dailyScans": [
{
"date": "2024-01-01",
"count": 25
},
{
"date": "2024-01-02",
"count": 30
}
],
"topQRCodes": [
{
"id": "qr_123",
"name": "Main QR Code",
"type": "url",
"scanCount": 500,
"isDynamic": true
}
]
}/api/v1/api-keysList all API keys for the authenticated user
Request Example
{}Response Example
{
"data": [
{
"id": "ak_123456789",
"name": "Production API Key",
"permissions": [
"qr:read",
"qr:write",
"analytics:read"
],
"rateLimit": 1000,
"isActive": true,
"lastUsedAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-01T00:00:00Z"
}
]
}/api/v1/api-keysCreate a new API key with custom permissions
Request Example
{
"name": "Development API Key",
"permissions": [
"qr:read",
"qr:write"
],
"expiresAt": "2024-12-31T23:59:59Z"
}Request Parameters
namestringRequiredDisplay name for the API key
permissionsarrayRequiredArray of permissions (qr:read, qr:write, analytics:read, webhooks:manage)
expiresAtstringExpiration date for the API key (ISO 8601 format)
rateLimitnumberCustom rate limit (requests per hour, max based on plan)
descriptionstringOptional description for the API key
Response Example
{
"id": "ak_987654321",
"name": "Development API Key",
"apiKey": "qrc_1234567890abcdef...",
"permissions": [
"qr:read",
"qr:write"
],
"rateLimit": 1000,
"expiresAt": "2024-12-31T23:59:59Z",
"isActive": true,
"createdAt": "2024-01-15T10:30:00Z"
}/api/v1/webhooksList all webhooks
Request Example
{}Response Example
{
"data": [
{
"id": "wh_123456789",
"name": "Scan Notifications",
"url": "https://myapp.com/webhooks/qr-scans",
"events": [
"scan.created",
"scan.updated"
],
"isActive": true,
"lastTriggeredAt": "2024-01-15T10:30:00Z",
"failureCount": 0,
"eventCount": 150,
"createdAt": "2024-01-01T00:00:00Z"
}
]
}/api/v1/webhooksCreate a new webhook
Request Example
{
"name": "QR Code Events",
"url": "https://myapp.com/webhooks/qr-events",
"events": [
"qr.created",
"qr.updated",
"qr.deleted"
]
}Request Parameters
namestringRequiredDisplay name for the webhook
urlstringRequiredWebhook endpoint URL (must be a public HTTPS address)
eventsarrayRequiredEvents to subscribe to: scan.created, qr.created, qr.updated, qr.deleted
Response Example
{
"id": "wh_987654321",
"name": "QR Code Events",
"url": "https://myapp.com/webhooks/qr-events",
"events": [
"qr.created",
"qr.updated",
"qr.deleted"
],
"secret": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"isActive": true,
"createdAt": "2024-01-15T10:30:00Z"
}Webhooks
Get real-time notifications when QR codes are created, updated, or scanned. Useful for building reactive systems and keeping your data in sync.
Available Events
QR Code Events
Availableqr.createdNew QR code createdqr.updatedQR code content updatedqr.deletedQR code deletedScan Events
Availablescan.createdQR code scannedscan.updatedScan data updatedGetting Started
1. Create a Webhook
POST /api/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"name": "My Webhook",
"url": "https://myapp.com/webhooks/qr-events",
"events": ["qr.created", "scan.created"]
}2. Handle Incoming Events
// Verify webhook signature
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
// Generate expected signature
const expectedSignature = hmac('sha256', secret)
.update(payload)
.digest('hex');
if (signature === expectedSignature) {
// Process webhook event
const event = req.body;
console.log('Event type:', event.type);
console.log('Data:', event.data);
}Requirements
- •HTTPS endpoint required: All webhook URLs must use HTTPS for security
- •Fast response expected: Your endpoint should respond with 2xx status within 10 seconds
- •Retry policy: Failed webhooks will be retried up to 3 times with exponential backoff
Simple, transparent pricing
API access is included on the Developer and Pro plans. No hidden fees.
Free
Good for trying out QR codes
- 10 QR codes
- 1 dynamic (editable) code
- 1,000 scans per month
- Dashboard only, no API access
Starter
Dynamic codes and full analytics
- 100 QR codes
- Every code can be dynamic
- Full analytics: geo, device, time
- Dashboard only, no API access
Developer
Headless Pro: full API access, no dashboard
- 500 QR codes
- REST API: 5,000 req/hr
- API keys (production + sandbox)
- Analytics API
- Webhooks
- Authenticated MCP (Claude, Cursor)
Pro
Visual dashboard plus full API access
- 500 QR codes
- REST API: 5,000 req/hr
- Webhooks
- Bulk management UI
- Real-time visual analytics
- Priority support
Ready to start building?
Get your API key and start integrating QR codes into your applications today.