API documentation

All requests require a Bearer token API key in the Authorization header. Create and manage keys in your dashboard under /dashboard/api-keys. Keys are shown once at creation, so store them securely.

Authorization: Bearer qrop_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are created in your dashboard. API access requires an active API plan; see the pricing page for available plans.

Generate a single QR code. Consumes 1 credit.

{
  "data": "https://example.com",
  "type": "url",
  "format": "png",
  "resolution": 1024,
  "foregroundColor": "#000000",
  "backgroundColor": "#FFFFFF"
}

{
  "id": "gen_a1b2c3",
  "image": "data:image/png;base64,iVBORw0KG...",
  "format": "png",
  "resolution": 1024,
  "creditsConsumed": 1
}

curl -X POST https://www.qrop.co.za/api/v1/generate \
  -H "Authorization: Bearer qrop_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://example.com",
    "type": "url",
    "format": "png",
    "resolution": 1024
  }'

Generate up to 25 QR codes in one request. Each item consumes 1 credit; credits are reserved for the full batch up front (no partial processing).

The batch logo is per-request, not per-item. Use separate batch calls (or /api/v1/generate) if items need different logos.

{
  "items": [
    { "data": "https://example.com/1", "type": "url" },
    { "data": "https://example.com/2", "type": "url" }
  ],
  "format": "png",
  "resolution": 512,
  "logoUrl": "https://example.com/company-logo.png"
}

{
  "results": [
    { "id": "gen_x1_0", "image": "data:image/png;base64,...", "success": true },
    { "id": "gen_x2_1", "image": "data:image/png;base64,...", "success": true }
  ],
  "creditsConsumed": 2,
  "failedCount": 0
}

curl -X POST https://www.qrop.co.za/api/v1/generate/batch \
  -H "Authorization: Bearer qrop_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "data": "https://example.com/1", "type": "url" },
      { "data": "https://example.com/2", "type": "url" }
    ],
    "format": "png",
    "resolution": 512
  }'

A batch with 0 or more than 25 items returns 400.

Generating large volumes? Items in a batch are rendered one at a time server-side, so a bigger batch size wouldn't generate any faster; it would just mean a slower call and a larger response body. For volumes beyond one batch, issue multiple 25-item batch calls in parallel from your client instead, staying within your plan's rate limit (see /api/v1/usage and the Rate limits section above).

Return current period usage, remaining allocation, carried credits from previous periods, and your rate limits.

{
  "plan": "growth",
  "currentPeriodStart": "2026-06-01T00:00:00Z",
  "currentPeriodEnd": "2026-07-01T00:00:00Z",
  "includedCredits": 50000,
  "includedCreditsUsed": 12450,
  "carriedCredits": 8200,
  "topUpCredits": 0,
  "rateLimit": { "requestsPerSecond": 25, "requestsPerMinute": 1000 }
}

curl https://www.qrop.co.za/api/v1/usage \
  -H "Authorization: Bearer qrop_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rotate the calling API key. A new key is returned (shown once); the old key keeps working for a 24-hour grace period before it stops.

{
  "newKey": "qrop_live_yyyyyyyyyyyyyyyyyyyy",
  "oldKeyValidUntil": "2026-06-25T10:00:00Z"
}

curl -X POST https://www.qrop.co.za/api/v1/keys/rotate \
  -H "Authorization: Bearer qrop_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Have Qrop post tracked-code events to your own system. Add an endpoint under Settings in the dashboard or with POST /api/v1/webhooks. Webhooks need purchased credits or a plan, and each account can have up to 5 endpoints. The endpoint must use https, and Qrop will not call private or local addresses.

Events: scan.logged, scan_limit.reached, code.expiring (seven days before a code expires) and code.expired. A request carries one or more events as JSON, delivered within about a minute. Answer with any 2xx within 5 seconds. Anything else, including a redirect, counts as a failure and is retried after 1 minute, 5 minutes, then every 15 minutes, for about an hour in all. After that Qrop stops retrying that batch. An endpoint that fails for 3 days is switched off and you are emailed. Delivery is at least once, so use the event id to ignore repeats. To fetch scans you missed, use GET /api/v1/tracked/{id}/events.

Each request has a Qrop-Signature header, t=<unix seconds>,v1=<hex>. The hex is an HMAC-SHA256 of the timestamp, a dot and the raw request body, using your endpoint’s secret (shown once when you create it). Check it, and reject a timestamp more than five minutes old.

If your server was down, use Resend missed scans on the endpoint in Settings to send it the scans from the last 24 hours or 7 days. They are marked replayed and arrive within a couple of minutes.

If your server sits behind a gateway that needs its own token, add up to 5 custom headers to an endpoint, such as Authorization: Bearer your-token. Qrop sends them with every request next to the signature. They are stored encrypted, only the names are shown after you save, and you replace the set to change it. Names Qrop sets itself (such as Host, Content-Type and anything starting Qrop-) are not allowed.

import { createHmac, timingSafeEqual } from "crypto";

function isFromQrop(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}