Version

Generate a QR code

POST

/api/v1/qrcode

Encodes data as a QR code and returns the PNG image. The service never fetches the URL you encode. Requires the qrcode.generate permission on the API key's role. Browser requests are additionally checked against the key's referrer restrictions.

Operation id: qrcode.generate
Authentication: Bearer API key
Required permission: qrcode.generate
Price: 1 credit per successful request
Rate limit: 120 requests per minute per key, 600 per workspace

Request

Field	Type	Required	Description
data	string	Yes	Content to encode (UTF-8, at most 2,048 bytes). Max length: 2048
format	string png	No	Output format. Only PNG is currently supported. Default: `png`
size	integer	No	Width and height of the image in pixels. Default: `512` Range: 64–2048
error_correction	string low \| medium \| quartile \| high	No	Error recovery level (about 7%, 15%, 25% and 30% of codewords). Default: `medium`
foreground	string	No	Default: `#000000`
background	string	No	Default: `#FFFFFF`
margin	boolean	No	Include the standard four-module quiet zone. Default: `true`

Examples

curl -X POST https://webknx.com/api/v1/qrcode \
  -H "Authorization: Bearer $WEBKNX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"https://example.com","format":"png","size":512,"error_correction":"high","foreground":"#000000","background":"#FFFFFF","margin":true}' \
  --output qrcode.png

const res = await fetch("https://webknx.com/api/v1/qrcode", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEBKNX_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"data":"https://example.com","format":"png","size":512,"error_correction":"high","foreground":"#000000","background":"#FFFFFF","margin":true}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const png = Buffer.from(await res.arrayBuffer());

import os, requests

res = requests.post(
    "https://webknx.com/api/v1/qrcode",
    headers={"Authorization": f"Bearer {os.environ['WEBKNX_SECRET_KEY']}"},
    json={"data":"https://example.com","format":"png","size":512,"error_correction":"high","foreground":"#000000","background":"#FFFFFF","margin":true},
    timeout=15,
)
res.raise_for_status()
open("qrcode.png", "wb").write(res.content)

$res = Http::withToken(getenv('WEBKNX_SECRET_KEY'))
    ->post('https://webknx.com/api/v1/qrcode', array (
  'data' => 'https://example.com',
  'format' => 'png',
  'size' => 512,
  'error_correction' => 'high',
  'foreground' => '#000000',
  'background' => '#FFFFFF',
  'margin' => true,
))
    ->throw();
file_put_contents('qrcode.png', $res->body());

Request body

{
    "data": "https://example.com",
    "format": "png",
    "size": 512,
    "error_correction": "high",
    "foreground": "#000000",
    "background": "#FFFFFF",
    "margin": true
}

Responses

200

The generated QR code. image/png

400

The body is not valid JSON. application/json

{
    "error": {
        "code": "invalid_json",
        "message": "The request body must be valid JSON.",
        "request_id": "req_01jaexample"
    }
}

401

Missing, invalid, expired or revoked API key. application/json

{
    "error": {
        "code": "unauthorized",
        "message": "A valid API key is required.",
        "request_id": "req_01jaexample"
    }
}

402

The workspace has no credits left in any allocation. application/json

{
    "error": {
        "code": "credits_exhausted",
        "message": "The workspace has insufficient credits.",
        "request_id": "req_01jaexample"
    }
}

403

The key's role lacks qrcode.generate, the key is restricted to other services, or the referrer is not allowed. application/json

{
    "error": {
        "code": "forbidden",
        "message": "This API key is not allowed to perform this operation.",
        "request_id": "req_01jaexample"
    }
}

413

The request body exceeds 16 KiB. application/json

{
    "error": {
        "code": "payload_too_large",
        "message": "The request body is too large.",
        "request_id": "req_01jaexample"
    }
}

415

The requested output format is not supported. application/json

{
    "error": {
        "code": "unsupported_format",
        "message": "Only png output is supported.",
        "request_id": "req_01jaexample"
    }
}

422

One or more options are invalid. application/json

{
    "error": {
        "code": "validation_error",
        "message": "The request is invalid.",
        "fields": {
            "size": [
                "size must be between 64 and 2048."
            ]
        },
        "request_id": "req_01jaexample"
    }
}

429

Too many requests for this key or workspace. Retry after the Retry-After header. application/json

{
    "error": {
        "code": "rate_limited",
        "message": "Too many requests.",
        "request_id": "req_01jaexample"
    }
}

500

The QR code could not be generated (for example, the data does not fit the chosen error-correction level). application/json

{
    "error": {
        "code": "generation_failed",
        "message": "The QR code could not be generated.",
        "request_id": "req_01jaexample"
    }
}

503

Credit accounting is temporarily unavailable; the request was not executed or charged. application/json

{
    "error": {
        "code": "service_unavailable",
        "message": "The service is temporarily unavailable.",
        "request_id": "req_01jaexample"
    }
}

See errors and retries for how to handle each error code.