API documentation

Public API v1 · OpenAPI spec

The bulkqr API generates QR codes in bulk: create a job with up to a million items, poll its status, and download a ZIP of the results. Everything the generator page can do with images, the API can do headlessly.

Authentication

Requests are authenticated with an organisation API key sent as a bearer token. Owners and admins create keys on the account page; a key is shown once at creation and can be revoked at any time. Keys grant full job access for the organisation — store them like passwords, and roll them by creating a replacement key, switching your integration over, then revoking the old one (both keys work during the overlap).

Authorization: Bearer bqk_your_key_here

Quickstart

Create a job:

curl -X POST https://bulkqr.com/api/v1/jobs \
  -H "Authorization: Bearer $BULKQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"data": "https://example.com/a"}, {"data": "https://example.com/b"}]}'

The response points at signed status and download URLs (valid 90 days, no auth needed):

{
  "jobId": "…",
  "total": 2,
  "creditsCharged": 2,
  "statusUrl": "/d/…/status?exp=…&t=…",
  "downloadUrl": "/d/…?exp=…&t=…"
}

Poll statusUrl (or GET /api/v1/jobs/{jobId} with your key) until "status": "complete", then fetch downloadUrl (or GET /api/v1/jobs/{jobId}/download) for the ZIP.

Create a job — POST /api/v1/jobs

JSON bodies carry up to 20,000 items:

Streaming (NDJSON) for large jobs

Up to 1,000,000 items / 100 MB with Content-Type: application/x-ndjson: the first line is the job meta, each following line one item.

{"format": "png", "style": {"scale": 8}}
{"data": "https://example.com/1"}
{"data": "https://example.com/2"}

Styling

The API accepts everything the generator page offers. All fields are optional and apply to every code in the job.

Centre logo

A logo hides part of the code, so raise error correction (ecLevel: "Q" or "H") and keep the ratio modest — the defaults stay comfortably scannable.

Captions

Per-item text: items[].caption overrides the job caption for that code — it works without a job-level caption and inherits the job caption's colour and fontSize. Filenames follow the same per-item pattern: items[].filename names the file (up to 120 characters), otherwise a name is derived from the data. Names are sanitised and truncated to 100 characters in the ZIP. JSON jobs suffix a name only when it collides with another item's; streaming (NDJSON) jobs append the item's index to every filename.

Example

curl -X POST https://bulkqr.com/api/v1/jobs \
  -H "Authorization: Bearer $BULKQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"data": "https://example.com", "caption": "Table 1"}],
    "format": "both",
    "style": {
      "ecLevel": "Q",
      "background": "transparent",
      "logo": {"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGN4xqANAALhARJlKxA9AAAAAElFTkSuQmCC"}
    }
  }'

That data URL is a valid 1×1 PNG — handy for trying the API before you export a real logo.

Status — GET /api/v1/jobs/{jobId}

{"id": "…", "status": "processing", "total": 50000, "completed": 31200, "failed": 0, "creditsCharged": 50000}

status is processing → zipping → complete (or failed). creditsCharged is the credits debited when the job was created. downloadUrl appears once complete.

Download — GET /api/v1/jobs/{jobId}/download

Streams the ZIP; Range requests are supported. Results are retained for 90 days.

Credits

Every job costs one credit per item, debited from the organisation that owns the key when the job is accepted. The exact amount is returned as creditsCharged on the create response and on job status. A job that cannot be paid for is rejected with 402 insufficient_credits and is never created; the 402 body carries required (what the job needed) and balance (what you have), so you can size a top-up. New accounts receive 500 credits once the owner verifies their email address. Small batches can be generated free in your browser on the generator page; the API always uses the server.

Check your balance — GET /api/v1/credits

Pre-flight a batch and alert before you run dry (rate limit 60 / minute per key):

curl https://bulkqr.com/api/v1/credits \
  -H "Authorization: Bearer $BULKQR_KEY"

{"balance": 4830}

Rate limits

Over the limit, responses are 429 with a Retry-After header.

Errors

Errors are JSON: {"error": "snake_case_code", …}.