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,
  "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 — and works without a job-level caption. 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}

status is processing → zipping → complete (or failed). 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 and the free tier

Jobs of up to 100 items are free. Larger jobs cost one credit per item, debited from the organisation's balance when the job is accepted — buy credits on the account page. A job that can't be paid for is rejected with 402 insufficient_credits and costs nothing.

Rate limits

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

Errors

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