How do I get started with the QRCodeStack API?

Step 1: create an API key

1. Open the dashboard and go to Settings → Developer settings → API.
2. Click New key and give it a name you will recognise later, such as the system that will use it.
3. Tick the scopes it needs. qr:read, qr:write and analytics:read are pre-ticked; add links:read and links:write if the key will touch short links.
4. Click Create key and copy the key immediately.

Step 2: make your first call

curl https://qrcodestack.com/api/v1/me \
  -H "Authorization: Bearer qrs_YOUR_KEY"

The response tells you which account the key belongs to, its plan, how many dynamic QR codes are in use against the plan limit, and how many API calls the key has made this month. If this call works, everything else is a matter of the right scope.

Step 3: create a dynamic QR code

curl -X POST https://qrcodestack.com/api/v1/qr-codes \
  -H "Authorization: Bearer qrs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring promo",
    "type": "url",
    "destination_url": "https://shop.example.com/spring",
    "render_customizations": {
      "dot_color": "#0F172A",
      "dot_shape": "rounded"
    }
  }'

You get back the code's id, its scan_url (the redirect the pattern encodes), an image_url, and the destination. Every code the API creates is dynamic — the pattern encodes the redirect, never the destination itself, which is why you can change the destination later with PATCH /qr-codes/{id} without reprinting. The API cannot create static codes.

Step 4: fetch the image

curl https://qrcodestack.com/api/v1/qr-codes/{id}/image \
  -H "Authorization: Bearer qrs_YOUR_KEY" \
  -o spring-promo.png

That returns a 512-pixel PNG in your dot and background colours. It needs the same Authorization header, so the URL will not work as an <img src> in a browser or an email — fetch it once and store the file yourself.

Read analytics, and what the limits are

GET /qr-codes/{id}/analytics returns aggregated scan data, and GET /qr-codes/{id}/scans returns the individual scan log. The log shows engaged traffic by default; add ?traffic=all to include bots and link previews. Lists are cursor-paginated, 25 items by default and 100 at most.

The full endpoint reference, including short links and custom domains, is at /api-docs.

Common problems

401 — API key required

The header is missing or malformed. It must read exactly Authorization: Bearer qrs_…, with the full key, not the 8-character prefix shown in the dashboard list.

403 — API access requires a Pro or Business plan

The key is valid but the account is on a trial, Starter, or has no active plan. The API is Pro and Business only.

403 — API key is missing required scope

The response names the scope it wanted. Scopes are fixed at creation, so revoke the key and create a new one with the right boxes ticked.

422 — Request validation failed

The response lists the offending fields. The usual causes are a destination_url without https:// and a missing type.

429 — Rate limit exceeded

Either the per-minute window or the monthly quota. The per-minute one clears within the minute; the monthly one resets at the start of the next month.

Frequently asked questions