Static QR API documentation

curl -X GET https://api.webqr.io/v1/usage \
  -H "X-API-Key: wq_xxxxxxxxxx_your_secret"

<?php
$ch = curl_init('https://api.webqr.io/v1/usage');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: wq_xxxxxxxxxx_your_secret',
  ],
]);
echo curl_exec($ch);

const res = await fetch('https://api.webqr.io/v1/usage', {
  headers: {
    'X-API-Key': 'wq_xxxxxxxxxx_your_secret',
  },
});
const data = await res.json();
console.log(data);

import requests

r = requests.get(
  "https://api.webqr.io/v1/usage",
  headers={
    "X-API-Key": "wq_xxxxxxxxxx_your_secret",
  },
)
print(r.json())

Returns the current usage snapshot for the account behind the key. Does not consume generation quota. The `usage` object matches the block returned by POST /v1/generate.

• a7k2m9 Square
• b3n5p1 Square indent
• c8q4r6 Squircle
• d1s7t9 Rounded connected
• e6u2v4 Sharp connected
• f9w5x7 Dot
• g2y8z0 Rounded dot
• h4a6b8 Dot (horizontal)
• i0c2d4 Dot (vertical)
• j6e8f0 Diamond
• k2g4h6 Star
• l8i0j2 Star pixel
• m4k6l8 Heart
• n0o2p4 Plus
• p6q8r0 Plus rounded
• q1r3s5 Square round
• s1r3s5 Square round

• r2s4t6 Square
• u8v0w2 Rounded square
• x4y6z8 Circle
• a1b3c5 Diamond
• d7e9f1 D-shape
• g3h5i7 D-shape inverted
• j9k1l3 Leaf
• m5n7o9 Leaf circle
• p1q3r5 Leaf circle rotated
• s7t9u1 Leaf variant
• v3w5x7 Square circle
• y9z1a3 Rounded pointed
• b5c7d9 Squircle
• e1f3g5 Droplet

• h7i9j1 Square
• k3l5m7 Squircle
• n9o1p3 Circle
• q5r7s9 Skewed square
• t1u3v5 D-shape
• w7x9y1 D-shape inverted
• z3a5b7 Leaf
• c9d1e3 Star
• f5g7h9 Diamond
• i1j3k5 X shape
• l7m9n1 Plus
• o3p5q7 Clover
• r9s1t3 Rounded X
• u5v7w9 Heart

• n0f1r2 No frame
• t7r8d9 Thick rounded frame
• l4b5t6 Label bottom
• b3n4t5 Banner top
• b7b8d9 Badge bottom
• b5d6t7 Badge top
• b9b0t1 Bar bottom
• b2t3p4 Bar top
• w4t5p6 Wide bar top
• w1d2b3 Wide bar bottom
• p0l1b2 Pill bottom
• p8t9p0 Pill top
• s6b7g8 Shopping bag

• La1b2c Facebook
• Ld3e4f Messenger
• Lg5h6i Instagram
• Lj7k8l LinkedIn
• Lm9n0o YouTube
• Ls3t4u Phone
• Lv5w6x Telegram
• Ly7z8a SMS
• Lb9c0d Email
• Le1f2g Wi‑Fi
• Lh3i4j Restaurant
• Lk5l6m Location
• Ln7o8p Gallery
• Lq9r0s Profile
• Lt1u2v WhatsApp
• Lw3x4y Link
• Lz5a6b Promo
• Lc7d8e Lock

• horizontal
• vertical
• diagonal
• inverse_diagonal
• radial

• One successful generate = +1 used_count. Validation errors and 4xx/5xx do not count.
• GET /v1/usage is for dashboards and alerts — same counters, zero spend.
• If overage billing is connected and status is payment_failed, all Static QR API calls are blocked (including included quota) until payment is resolved.
• Localized hint strings (what_counts_toward_limit, included_quota_note, …) are for humans; automate on numeric fields and error.code.

Fields present on the `usage` object in generate and usage responses:

• period
• used_count
• included_limit
• paid_count
• charged_cents
• spending_cap_cents
• included_quota_resets_at
• what_counts_toward_limit
• what_does_not_count
• included_quota_note
• overage_linear_floor_hint

API billing in cabinet

• Keep the API key on your server only — never in browsers, mobile apps, or public repos.
• Call api.* from your backend. Browser CORS is not intended for Static QR API — use your server or the API Builder in the cabinet.
• Optionally restrict each key to your server IPs (or fixed CDN egress). Empty allowlist = any IP; empty array of rules can block all.
• Optionally require HMAC signing per key in the cabinet. When enabled, every route needs X-WebQR-Timestamp and X-WebQR-Signature — including GET /v1/usage.

1714412345
POST
/v1/generate
<sha256_hex_of_raw_body>

1714412345
GET
/v1/usage
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# Build signature on your server, then attach headers to curl
TS=$(date +%s)
BODY='{"data":"https://webqr.io"}'
BODY_HASH=$(printf %s "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SECRET="${API_KEY##*_}"  # 40 chars after the second underscore
CANON=$(printf '%s\nPOST\n/v1/generate\n%s' "$TS" "$BODY_HASH")
SIG=$(printf %s "$CANON" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X POST https://api.webqr.io/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-WebQR-Timestamp: $TS" \
  -H "X-WebQR-Signature: $SIG" \
  -d "$BODY"

<?php
$apiKey = getenv('WEBQR_API_KEY');
$secret = substr($apiKey, strrpos($apiKey, '_') + 1);
$ts = (string) time();
$body = json_encode(['data' => 'https://webqr.io'], JSON_UNESCAPED_SLASHES);
$canonical = $ts . "\nPOST\n/v1/generate\n" . hash('sha256', $body);
$signature = hash_hmac('sha256', $canonical, $secret);

$ch = curl_init('https://api.webqr.io/v1/generate');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
    'X-WebQR-Timestamp: ' . $ts,
    'X-WebQR-Signature: ' . $signature,
  ],
  CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);

import crypto from 'node:crypto';

const apiKey = process.env.WEBQR_API_KEY;
const secret = apiKey.slice(apiKey.lastIndexOf('_') + 1);
const ts = String(Math.floor(Date.now() / 1000));
const body = JSON.stringify({ data: 'https://webqr.io' });
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const canonical = `${ts}\nPOST\n/v1/generate\n${bodyHash}`;
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

const res = await fetch('https://api.webqr.io/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-WebQR-Timestamp': ts,
    'X-WebQR-Signature': signature,
  },
  body,
});
console.log(await res.json());

import hashlib, hmac, json, os, time, urllib.request

api_key = os.environ["WEBQR_API_KEY"]
secret = api_key.rsplit("_", 1)[-1]
ts = str(int(time.time()))
body = json.dumps({"data": "https://webqr.io"}, separators=(",", ":"))
body_hash = hashlib.sha256(body.encode()).hexdigest()
canonical = f"{ts}\nPOST\n/v1/generate\n{body_hash}"
signature = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()

req = urllib.request.Request("https://api.webqr.io/v1/generate", data=body.encode(), method="POST")
req.add_header("Content-Type", "application/json")
req.add_header("X-API-Key", api_key)
req.add_header("X-WebQR-Timestamp", ts)
req.add_header("X-WebQR-Signature", signature)
print(urllib.request.urlopen(req).read().decode())

curl -X POST https://api.webqr.io/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wq_xxxxxxxxxx_your_secret" \
  -H "X-WebQR-Timestamp: 1714412345" \
  -H "X-WebQR-Signature: 64_hex_chars_lowercase_hmac_sha256_placeholder_do_not_use_as_is" \
  -d '{
    "data": "https://webqr.io",
    "design": {
        "size": 512,
        "color": "#000000",
        "backgroundColor": "#FFFFFF",
        "styleType": "a7k2m9",
        "eyeType": "r2s4t6",
        "showColorGradient": false
    }
}'

<?php
$ch = curl_init('https://api.webqr.io/v1/generate');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: wq_xxxxxxxxxx_your_secret',
    'X-WebQR-Timestamp: 1714412345',
    'X-WebQR-Signature: 64_hex_chars_lowercase_hmac_sha256_placeholder_do_not_use_as_is'
  ],
  CURLOPT_POSTFIELDS => '{
    "data": "https://webqr.io",
    "design": {
        "size": 512,
        "color": "#000000",
        "backgroundColor": "#FFFFFF",
        "styleType": "a7k2m9",
        "eyeType": "r2s4t6",
        "showColorGradient": false
    }
}',
]);
echo curl_exec($ch);

const res = await fetch('https://api.webqr.io/v1/generate', {
  method: 'POST',
  headers: {
      "Content-Type": "application/json",
      "X-API-Key": "wq_xxxxxxxxxx_your_secret",
      "X-WebQR-Timestamp": "1714412345",
      "X-WebQR-Signature": "64_hex_chars_lowercase_hmac_sha256_placeholder_do_not_use_as_is"
  },
  body: JSON.stringify({
    "data": "https://webqr.io",
    "design": {
        "size": 512,
        "color": "#000000",
        "backgroundColor": "#FFFFFF",
        "styleType": "a7k2m9",
        "eyeType": "r2s4t6",
        "showColorGradient": false
    }
}),
});
const data = await res.json();
console.log(data);

import requests

r = requests.post(
  "https://api.webqr.io/v1/generate",
  headers={
      "Content-Type": "application/json",
      "X-API-Key": "wq_xxxxxxxxxx_your_secret",
      "X-WebQR-Timestamp": "1714412345",
      "X-WebQR-Signature": "64_hex_chars_lowercase_hmac_sha256_placeholder_do_not_use_as_is"
  },
  json={
      "data": "https://webqr.io",
      "design": {
          "size": 512,
          "color": "#000000",
          "backgroundColor": "#FFFFFF",
          "styleType": "a7k2m9",
          "eyeType": "r2s4t6",
          "showColorGradient": false
      }
  },
)
print(r.json())