Create dynamic, trackable QR codes and inspect scan analytics with the ScanBlitz API. Use when a user wants QR codes whose destinations can change later, QR...
---
name: scanblitz
description: Create dynamic, trackable QR codes and inspect scan analytics with the ScanBlitz API. Use when a user wants QR codes whose destinations can change later, QR scan/click attribution, campaign QR links, or programmatic QR creation from an agent. Not for static offline-only QR images, barcode scanning, or decoding QR codes from images.
version: 1.0.0
license: MIT
metadata:
openclaw:
emoji: "📱"
homepage: https://scanblitz.com
requires:
env:
- SCANBLITZ_API_KEY
bins:
- curl
primaryEnv: SCANBLITZ_API_KEY
envVars:
- name: SCANBLITZ_API_KEY
required: true
description: ScanBlitz API key. Keys usually start with sb_api_. Older partner keys may start with sbz_partner_.
- name: SCANBLITZ_API_BASE
required: false
description: Optional override for the API base URL. Defaults to https://scanblitz.com/api/enterprise for sb_api_ keys.
---
# ScanBlitz — Dynamic QR Codes and Scan Analytics
ScanBlitz creates dynamic QR codes and short links that track scans. Use it when an agent needs to create a QR code, update the destination later, or check scan analytics such as device, country, referrer, and daily trends.
## When to Use
Use this skill when the user asks to:
- Create a QR code for a URL and track scans.
- Make a dynamic QR code whose destination can be changed later.
- Create QR links for campaigns, flyers, packages, events, or landing pages.
- Check how many times a QR code was scanned.
- Pull scan analytics by device, country, city, referrer, or date.
- Update, deactivate, or delete an existing ScanBlitz QR code.
- Generate QR codes programmatically from an agent or automation.
Do **not** use this skill for:
- Static QR images that do not need tracking or redirect updates.
- Reading or decoding QR codes from images.
- Barcode generation.
- Anything that should avoid third-party network calls.
## Setup
### Option A: Use an existing ScanBlitz API key
Set the key in OpenClaw's environment file:
```bash
mkdir -p ~/.openclaw
printf '\nSCANBLITZ_API_KEY=%s\n' 'sb_api_your_key_here' >> ~/.openclaw/.env
```
If your installation uses a custom state directory, put it in `$OPENCLAW_STATE_DIR/.env` instead.
### Option B: Self-register by email
Agents can request a verification code and receive an API key without a browser.
```bash
curl -s -X POST 'https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/agent-register' \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","agent_name":"OpenClaw Agent"}'
```
Check that inbox for the 6-digit code, then verify:
```bash
curl -s -X POST 'https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/agent-register/verify' \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","code":"123456"}'
```
Save the returned `api_key` as `SCANBLITZ_API_KEY`. The key is only shown once.
### Optional MCP server
ScanBlitz also provides an MCP server:
```json
{
"mcpServers": {
"scanblitz": {
"command": "npx",
"args": ["-y", "@scanblitz/mcp-server"],
"env": { "SCANBLITZ_API_KEY": "sb_api_..." }
}
}
}
```
## Auth and Base URLs
Recommended API keys use the `sb_api_` prefix and the public enterprise API:
```bash
SCANBLITZ_API_BASE="${SCANBLITZ_API_BASE:-https://scanblitz.com/api/enterprise}"
AUTH_HEADER="Authorization: Bearer $SCANBLITZ_API_KEY"
```
Older partner keys may start with `sbz_partner_`. If you have one, use the partner API and `X-Partner-Key` header:
```bash
SCANBLITZ_API_BASE="https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/partner-api"
AUTH_HEADER="X-Partner-Key: $SCANBLITZ_API_KEY"
```
Always include a source header so traffic is classified correctly:
```bash
SOURCE_HEADER="X-Source-Type: agent"
```
## Create a Dynamic QR Code
```bash
curl -s -X POST "$SCANBLITZ_API_BASE/qr-codes" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{
"name": "Product Launch",
"destination_url": "https://example.com/launch"
}'
```
Expected response shape:
```json
{
"success": true,
"data": {
"id": "uuid",
"short_id": "xK7mQ3",
"name": "Product Launch",
"destination_url": "https://example.com/launch",
"scan_count": 0,
"is_active": true
}
}
```
Save both:
- `id`: needed for enterprise API update/delete/analytics endpoints.
- `short_id`: useful for public redirect links like `https://scanblitz.com/qr/xK7mQ3`.
If using the older partner API, create with the base URL directly:
```bash
curl -s -X POST "$SCANBLITZ_API_BASE" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{
"name": "Product Launch",
"destination_url": "https://example.com/launch",
"partner_ref": "openclaw:product-launch"
}'
```
## List QR Codes
```bash
curl -s "$SCANBLITZ_API_BASE/qr-codes?page=1&limit=50&sort_by=created_at&sort_order=desc" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
Useful filters:
- `search=launch`
- `active=true`
- `sort_by=scan_count`
- `sort_order=desc`
## Get One QR Code
Enterprise API:
```bash
QR_ID="uuid-from-create-or-list"
curl -s "$SCANBLITZ_API_BASE/qr-codes/$QR_ID" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
Older partner API:
```bash
SHORT_ID="xK7mQ3"
curl -s "$SCANBLITZ_API_BASE/$SHORT_ID" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
## Update a QR Destination
Enterprise API:
```bash
QR_ID="uuid-from-create-or-list"
curl -s -X PUT "$SCANBLITZ_API_BASE/qr-codes/$QR_ID" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{
"destination_url": "https://example.com/new-page",
"name": "Updated Launch QR"
}'
```
Older partner API:
```bash
SHORT_ID="xK7mQ3"
curl -s -X PUT "$SCANBLITZ_API_BASE/$SHORT_ID" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{
"destination_url": "https://example.com/new-page",
"name": "Updated Launch QR"
}'
```
## Get Scan Analytics
Enterprise API:
```bash
QR_ID="uuid-from-create-or-list"
curl -s "$SCANBLITZ_API_BASE/qr-codes/$QR_ID/analytics?group_by=day" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
Older partner API:
```bash
SHORT_ID="xK7mQ3"
curl -s "$SCANBLITZ_API_BASE/analytics/$SHORT_ID" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
Analytics may include:
- total scans
- device type
- browser and OS
- country and city
- referrer
- UTM parameters
- daily, weekly, or monthly trends
## Delete or Deactivate
Enterprise API permanently deletes the QR code:
```bash
QR_ID="uuid-from-create-or-list"
curl -s -X DELETE "$SCANBLITZ_API_BASE/qr-codes/$QR_ID" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
If you only want to pause a QR code, update it instead:
```bash
curl -s -X PUT "$SCANBLITZ_API_BASE/qr-codes/$QR_ID" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{"is_active": false}'
```
Older partner API soft-deletes/deactivates by short ID:
```bash
SHORT_ID="xK7mQ3"
curl -s -X DELETE "$SCANBLITZ_API_BASE/$SHORT_ID" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
## Bulk Create
Bulk create is available on paid plans.
```bash
curl -s -X POST "$SCANBLITZ_API_BASE/qr-codes/bulk" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{
"qr_codes": [
{"name":"Store #1","destination_url":"https://example.com/store/1"},
{"name":"Store #2","destination_url":"https://example.com/store/2"}
]
}'
```
## Health Check
For older partner API keys:
```bash
curl -s 'https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/partner-api/health' \
-H "X-Partner-Key: $SCANBLITZ_API_KEY" \
-H "$SOURCE_HEADER"
```
For enterprise keys, use a lightweight authenticated call:
```bash
curl -s "$SCANBLITZ_API_BASE/usage" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER"
```
## Generate a Printable QR Image
ScanBlitz creates the trackable link. To render a PNG, encode the ScanBlitz scan URL, not the final destination URL.
```bash
SCAN_URL="https://scanblitz.com/qr/xK7mQ3"
ENCODED=$(python3 - <<'PY'
from urllib.parse import quote
import os
print(quote(os.environ["SCAN_URL"], safe=""))
PY
)
curl -fsSL "https://api.qrserver.com/v1/create-qr-code/?size=1024x1024&ecc=H&format=png&data=$ENCODED" \
-o scanblitz-qr.png
```
If you do not have Python available, paste the `SCAN_URL` into any trusted QR generator.
## Response Handling
Always check for both HTTP errors and JSON errors:
```bash
response=$(curl -sS -w '\n%{http_code}' -X POST "$SCANBLITZ_API_BASE/qr-codes" \
-H "Content-Type: application/json" \
-H "$AUTH_HEADER" \
-H "$SOURCE_HEADER" \
-d '{"name":"Test","destination_url":"https://example.com"}')
body=$(printf '%s' "$response" | sed '$d')
status=$(printf '%s' "$response" | tail -n1)
printf 'HTTP %s\n%s\n' "$status" "$body"
```
Common issues:
- `401`: missing or invalid `SCANBLITZ_API_KEY`.
- `403`: key lacks permission for that operation.
- `404`: wrong QR `id`/`short_id`, wrong base URL for the key type, or inactive/deleted code.
- `429`: rate limit exceeded.
## Quick Reference
| Task | Enterprise endpoint | Partner endpoint |
| --- | --- | --- |
| Create | `POST /qr-codes` | `POST /` |
| List | `GET /qr-codes` | Not available |
| Get | `GET /qr-codes/:id` | `GET /:short_id` |
| Update | `PUT /qr-codes/:id` | `PUT /:short_id` |
| Analytics | `GET /qr-codes/:id/analytics` | `GET /analytics/:short_id` |
| Delete/deactivate | `DELETE /qr-codes/:id` or `PUT is_active:false` | `DELETE /:short_id` |
| Usage/health | `GET /usage` | `GET /health` |
## Security Notes
- Never print or commit `SCANBLITZ_API_KEY`.
- Store credentials in environment files, shell secrets, or OpenClaw state, not in the skill folder.
- Do not create QR codes that hide malicious destinations.
- Inspect the returned `destination_url` before sharing or printing a QR code.
- Prefer `https://scanblitz.com/qr/<short_id>` for public-facing links when available.
## References
- ScanBlitz: https://scanblitz.com
- API docs: https://scanblitz.com/api-docs
- Agent reference: https://scanblitz.com/llms-full.txt
- MCP server: `npx -y @scanblitz/mcp-server`
don't have the plugin yet? install it then click "run inline in claude" again.