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#

TaskEnterprise endpointPartner endpointCreatePOST /qr-codes``POST /ListGET /qr-codesNot availableGetGET /qr-codes/:id``GET /:short_idUpdatePUT /qr-codes/:id``PUT /:short_idAnalyticsGET /qr-codes/:id/analytics``GET /analytics/:short_idDelete/deactivateDELETE /qr-codes/:id or PUT is_active:false``DELETE /:short_idUsage/healthGET /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