scanblitz

intent

create dynamic QR codes and short links that track scans and allow destination updates after creation. use this skill when a user needs to generate QR codes for campaigns, events, or packaging, update where a QR code points after it's live, check how many times a QR code was scanned, or pull scan analytics by device, country, referrer, and date. do not use for static offline QR images, barcode generation, or decoding QR codes from images.

inputs

environment variables:

• SCANBLITZ_API_KEY (required): API key issued by ScanBlitz. keys starting with sb_api_ use the enterprise API at https://scanblitz.com/api/enterprise. older keys starting with sbz_partner_ use the partner API at https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/partner-api. obtain a key by setting up an existing account or using the self-register flow in the procedure section.
• SCANBLITZ_API_BASE (optional): override the default API base URL. defaults to https://scanblitz.com/api/enterprise for sb_api_ keys.

external connection:

• ScanBlitz API (public, no OAuth required). network calls required. subject to rate limits (429 responses). enterprise keys are recommended.

runtime dependencies:

• curl for HTTP calls.
• python3 (optional) for URL encoding when generating printable QR images.

procedure

step 1: verify or obtain API credentials

inputs: email address (if registering), or existing ScanBlitz API key.

if you have an existing key, export it:

export SCANBLITZ_API_KEY="sb_api_your_key_here"
export SCANBLITZ_API_BASE="${SCANBLITZ_API_BASE:-https://scanblitz.com/api/enterprise}"

if you do not have a key, self-register by email:

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"}'

outputs: verification code sent to inbox.

then verify and receive the API key:

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"}'

outputs: response includes api_key (shown once only). export it as SCANBLITZ_API_KEY.

step 2: determine auth method based on key type

inputs: value of SCANBLITZ_API_KEY.

if key starts with sb_api_, set headers:

AUTH_HEADER="Authorization: Bearer $SCANBLITZ_API_KEY"
API_BASE="https://scanblitz.com/api/enterprise"

if key starts with sbz_partner_, set headers:

AUTH_HEADER="X-Partner-Key: $SCANBLITZ_API_KEY"
API_BASE="https://kylpeyhiqtdonlqqguty.supabase.co/functions/v1/partner-api"

always add source header:

SOURCE_HEADER="X-Source-Type: agent"

outputs: AUTH_HEADER, API_BASE, SOURCE_HEADER ready for API calls.

step 3: create a dynamic QR code

inputs: QR code name (string), destination URL (string).

for enterprise API (sb_api_ keys):

curl -s -X POST "$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"
  }'

for partner API (sbz_partner_ keys):

curl -s -X POST "$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"
  }'

outputs: JSON response with id (uuid, needed for enterprise updates/analytics), short_id (string, used for public redirect links like https://scanblitz.com/qr/xK7mQ3), destination_url, scan_count, and is_active.

step 4: list existing QR codes (enterprise API only)

inputs: optional filters (search, active, sort_by, sort_order, page, limit).

curl -s "$API_BASE/qr-codes?page=1&limit=50&sort_by=created_at&sort_order=desc" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

example filters:

• search=launch (filter by name substring)
• active=true (only active codes)
• sort_by=scan_count (sort by scan frequency)
• sort_order=desc (descending order)

outputs: paginated array of QR code objects.

step 5: retrieve a single QR code

inputs: id (enterprise) or short_id (partner).

for enterprise API:

curl -s "$API_BASE/qr-codes/$id" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

for partner API:

curl -s "$API_BASE/$short_id" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

outputs: QR code object with all metadata and current scan count.

step 6: update a QR code destination or name

inputs: id (enterprise) or short_id (partner), new destination URL and/or name.

for enterprise API:

curl -s -X PUT "$API_BASE/qr-codes/$id" \
  -H "Content-Type: application/json" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER" \
  -d '{
    "destination_url": "https://example.com/new-page",
    "name": "Updated Launch QR"
  }'

for partner API:

curl -s -X PUT "$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"
  }'

outputs: updated QR code object reflecting the new destination.

step 7: retrieve scan analytics

inputs: id (enterprise) or short_id (partner), optional group_by param (day, week, month).

for enterprise API:

curl -s "$API_BASE/qr-codes/$id/analytics?group_by=day" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

for partner API:

curl -s "$API_BASE/analytics/$short_id" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

outputs: analytics object including total scans, device type (mobile, desktop, tablet), browser, OS, country, city, referrer, UTM parameters, and daily/weekly/monthly trends.

step 8: deactivate or delete a QR code

inputs: id (enterprise) or short_id (partner).

for enterprise API, permanent delete:

curl -s -X DELETE "$API_BASE/qr-codes/$id" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

for enterprise API, soft pause (set is_active to false):

curl -s -X PUT "$API_BASE/qr-codes/$id" \
  -H "Content-Type: application/json" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER" \
  -d '{"is_active": false}'

for partner API, soft deactivate:

curl -s -X DELETE "$API_BASE/$short_id" \
  -H "$AUTH_HEADER" \
  -H "$SOURCE_HEADER"

outputs: confirmation response (success or error message).

step 9: (optional) bulk create QR codes

inputs: array of QR code objects (name, destination_url). available on paid plans only.

curl -s -X POST "$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"}
    ]
  }'

outputs: array of created QR code objects.

step 10: (optional) generate a printable PNG image

inputs: short_id from step 3 (e.g., xK7mQ3).

construct the ScanBlitz scan URL:

SCAN_URL="https://scanblitz.com/qr/xK7mQ3"

encode it for the QR generator:

ENCODED=$(python3 - <<'PY'
from urllib.parse import quote
import os
print(quote(os.environ["SCAN_URL"], safe=""))
PY
)

generate the PNG via a third-party QR service:

curl -fsSL "https://api.qrserver.com/v1/create-qr-code/?size=1024x1024&ecc=H&format=png&data=$ENCODED" \
  -o scanblitz-qr.png

outputs: PNG file at ./scanblitz-qr.png suitable for printing.

decision points

api key type: if SCANBLITZ_API_KEY starts with sb_api_, use enterprise endpoints (/qr-codes, /qr-codes/:id, etc.) and Authorization: Bearer header. if it starts with sbz_partner_, use partner endpoints (base URL root /, /:short_id, etc.) and X-Partner-Key header. if neither prefix matches, the key format is invalid; stop and request a valid key.

qr code pause vs. delete: if the user wants to pause a QR code temporarily (enterprise API), set is_active to false via PUT. if the user wants permanent removal, use DELETE. for partner API keys, DELETE is the only option (soft deactivates).

http error response: if curl returns status 401, the API key is missing or invalid. if 403, the key lacks permission for that operation. if 404, the QR code id/short_id is wrong, the base URL is incorrect for the key type, or the code is inactive/deleted. if 429, the rate limit has been exceeded; retry after 60 seconds. if 5xx, the ScanBlitz API is down; retry after checking https://scanblitz.com/status.

empty analytics: if a newly created QR code has zero scans, the analytics endpoint returns an empty result set or zero fields. this is not an error; it is expected until the code is scanned.

network timeout: if curl hangs or times out, set a timeout flag:

curl -s --connect-timeout 10 --max-time 30 ... 

list unavailable for partner keys: the partner API does not support the list endpoint. use the enterprise API if you need to enumerate QR codes.

output contract

qr code object format (both APIs):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "short_id": "xK7mQ3",
    "name": "Product Launch",
    "destination_url": "https://example.com/launch",
    "scan_count": 42,
    "is_active": true,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

analytics object format (enterprise API):

{
  "success": true,
  "data": {
    "total_scans": 42,
    "device_breakdown": {
      "mobile": 28,
      "desktop": 12,
      "tablet": 2
    },
    "country_breakdown": {
      "US": 35,
      "CA": 5,
      "UK": 2
    },
    "referrer_breakdown": {
      "direct": 15,
      "google": 20,
      "facebook": 7
    },
    "daily_trends": [
      { "date": "2025-01-15", "scans": 10 },
      { "date": "2025-01-16", "scans": 20 }
    ]
  }
}

list response format (enterprise API):

{
  "success": true,
  "data": [
    { "id": "...", "short_id": "...", "name": "...", ... },
    { "id": "...", "short_id": "...", "name": "...", ... }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150
  }
}

error response format:

{
  "success": false,
  "error": "invalid api key",
  "code": "UNAUTHORIZED"
}

generated PNG file: output to local path (e.g., ./scanblitz-qr.png) as binary PNG image, 1024x1024 pixels, high ECC level (H).

outcome signal

• create: user receives a QR code object with a short_id. the QR code is live immediately and can be shared or printed via the link https://scanblitz.com/qr/<short_id>.
• update destination: user receives a confirmation response. the QR code now points to the new destination URL. previously printed QR codes and links will redirect to the updated URL.
• view analytics: user receives a data object showing total scans, device/country/referrer breakdowns, and daily trends. this confirms the QR code is trackable and has been scanned at least once.
• delete or pause: user receives a confirmation response. paused codes (is_active: false) no longer redirect; deleted codes return 404 on access.
• list: user receives an array of all QR codes, filtered and sorted as requested. useful for confirming which codes exist and their current scan counts.
• bulk create: user receives an array of created QR code objects. all codes are live and ready to share.
• png generated: a PNG file appears at the specified output path. the image can be opened, printed, or embedded in documents. scanning the image with any smartphone camera redirects to the ScanBlitz short link, which then redirects to the final destination.