API Reference

Authenticate every request with an API key created in your dashboard. Pass it in any of these ways:

Authorization: Bearer nq_live_xxx      # recommended
X-Api-Key: nq_live_xxx
?api_key=nq_live_xxx                    # handy for <img> tags

Each key belongs to the workspace it was created in and only sees that workspace's saved codes. To act on a team's codes, switch to that workspace before creating the key.

Returns an image/svg+xml body — perfect to drop straight into an <img>. Add &format=json to get the SVG string plus a data URI instead.

curl -H "Authorization: Bearer nq_live_xxx" \
  "https://qr.evnk.co/api/v1/qr?data=https://acme.com&dot=rounded&eye=circle&fg=%236d5efc" \
  -o qr.svg

Send JSON for full control (including nested gradient & logo objects). Set "format": "svg" for a raw image response.

curl -X POST https://qr.evnk.co/api/v1/qr \
  -H "Authorization: Bearer nq_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://acme.com",
    "design": {
      "dot_style": "extra-rounded",
      "eye_style": "rounded",
      "foreground_gradient": { "type": "linear", "from": "#6d5efc", "to": "#22d3ee", "rotation": 45 },
      "logo": { "src": "data:image/png;base64,....", "size": 0.22 }
    }
  }'

Add a logo to the middle of any code. NookQR clears a padded backdrop behind it so the surrounding modules stay readable, and you should pair it with "ecc": "H" (30% error correction) so the code still scans with the center obscured.

curl -X POST https://qr.evnk.co/api/v1/qr \
  -H "Authorization: Bearer nq_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://acme.com",
    "design": {
      "ecc": "H",
      "logo": {
        "src": "https://acme.com/logo.png",
        "size": 0.24,
        "margin": 2,
        "round": 0.3
      }
    }
  }'

Remote src URLs are fetched and embedded server-side, so the returned SVG is self-contained and renders anywhere. URLs must be https, resolve to a public address, return an image/* content type, and be under 256 KB.

Logos are an SVG feature — the PNG output renders a standard matrix without one.

Persist codes so you can manage and re-render them from a stable URL.

• GET/api/v1/qrcodes— List your saved codes
• POST/api/v1/qrcodes— Create { name, data, design }
• GET/api/v1/qrcodes/:id— Fetch one (JSON)
• PATCH/api/v1/qrcodes/:id— Update name/data/design
• DELETE/api/v1/qrcodes/:id— Delete
• GET/api/v1/qrcodes/:id/image— Render as SVG — public by id, embed anywhere

<!-- Embed a saved code on any website -->
<img src="https://qr.evnk.co/api/v1/qrcodes/clx123abc/image?size=400" alt="Scan me" />

Generate many codes at once from one shared design. Capped by the server (default 50 per request).

• POST/api/v1/qrcodes/bulk— Render { items:[{data,name?}], design } — JSON of styled SVGs
• POST/api/v1/qrcodes/bulk?format=zip— Same, but streams a ZIP of SVG files

curl -X POST "https://qr.evnk.co/api/v1/qrcodes/bulk?format=zip" \
  -H "Authorization: Bearer $NOOKQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "data": "https://acme.com/1", "name": "flyer-1" },
      { "data": "https://acme.com/2", "name": "flyer-2" }
    ],
    "design": { "dot_style": "rounded", "eye_style": "circle" }
  }' -o qr-codes.zip

The response reports truncated when the batch exceeded the limit and a failed array for any individual payloads that could not be rendered. The dashboard Bulk tool uses this endpoint and downloads PNGs.

Errors use standard HTTP status codes with a JSON body:

{ "error": { "message": "Invalid or missing API key" } }

401 unauthorized · 404 not found · 422 validation (includes an issues array) · 400 bad request.