Core resources

Codes

A code is one dynamic QR: a short link plus where it points. The printed image encodes the short link and never changes; everything else stays editable.

The code object#

Your codes, newest first. Query: limit (default 25, max 100; larger values clamp) and offset (default 0). To search, add q (codes whose name contains it, any case) or slug (one short link). total counts the codes that match.

let offset = 0, total = Infinity;
while (offset < total) {
  const res = await fetch(
    "https://qrvora.com/api/v1/codes?limit=100&offset=" + offset,
    { headers: { Authorization: "Bearer " + process.env.QRF_KEY } }
  );
  const page = await res.json();
  total = page.total;
  offset += page.data.length;
  // …use page.data; stay under 6 requests/second
}

One code including its all-time scans count. 404 not_found for ids that are missing or belong to another account.

Creates one dynamic code and returns it with 201. Enforces your plan's code-count limit first (403 code_limit_reached).

curl -X POST https://qrvora.com/api/v1/codes \
  -H "Authorization: Bearer qrf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "menu", "name": "Cafe menu",
    "content": {
      "title": "Cafe Aurora", "currency": "$",
      "sections": [{ "name": "Coffee", "items": [
        { "name": "Espresso", "price": "3.50", "desc": "Double shot" }
      ]}]
    }
  }'

Up to 100 codes in one call. Body: { "codes": [ { type?, name?, destination?, content? }, … ] }. Partial success is normal: valid specs are created, invalid ones and specs past your plan limit come back in errors with their array index. Always check errors.

HTTP 201 when at least one code was created, 422 when none were
{
  "created": [ { …code }, … ],
  "errors":  [ { "index": 1, "error": "invalid_type", "message": "…" } ],
  "summary": { "requested": 3, "created": 2, "failed": 1 }
}

Updates any subset of the fields below; send at least one (422 empty_patch otherwise). The printed QR keeps working through every edit.

Smart rules#

A url code can carry up to 10 rules that send some scanners to a different URL than its destination: by device, country, phone language, time of day or date. Rules are tried in order and the first match wins; a scanner no rule matches goes to destination. Available on the Pro and Business plans. After a downgrade the rules stay stored but stop applying.

curl -X PATCH https://qrvora.com/api/v1/codes/CODE_ID \
  -H "Authorization: Bearer qrf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/app",
    "routing": {
      "timezone": "Europe/London",
      "rules": [
        { "when": { "kind": "device", "values": ["ios"] },
          "url": "https://apps.apple.com/app/id000000000" },
        { "when": { "kind": "device", "values": ["android"] },
          "url": "https://play.google.com/store/apps/details?id=com.example.app" },
        { "when": { "kind": "time", "days": [1,2,3,4,5], "from": "09:00", "to": "17:00" },
          "url": "https://example.com/open-now" }
      ]
    }
  }'

Each rule comes back with an id. A rule that is malformed returns 422 invalid_routing with a message naming the problem, and every rule URL is checked against the malware/phishing list (422 unsafe_destination).

Deletes the code and its uploaded files. Returns { "deleted": true, "id" }. The short link stops working immediately and the slug is not reused. This cannot be undone.

Renders the code's QR with its saved style. The image encodes the short link, so editing the destination doesn't change the image. Responds with the binary image (image/png or image/svg+xml), not JSON. Each render counts against your quota; cache the result.

curl -o code.png "https://qrvora.com/api/v1/codes/CODE_ID/image?size=1024" \
  -H "Authorization: Bearer qrf_YOUR_KEY"

A code's scans over a period: the total, each day, and the top 10 countries, cities, devices and systems. Query: from and to as YYYY-MM-DD (default: the last 30 days; at most 366 days apart, otherwise 422 invalid_range).

{ "data": {
    "qr_id": "4a38…", "name": "Menu", "from": "2026-10-01", "to": "2026-10-07",
    "total": 8,
    "days": [ { "day": "2026-10-01", "count": 7 }, { "day": "2026-10-03", "count": 1 } ],
    "countries": [ { "name": "US", "count": 7 }, … ],
    "cities": [ … ], "devices": [ … ], "os": [ … ]
} }

Safe retries#

Send an Idempotency-Key header (any unique string up to 255 characters) with POST /api/v1/codes or /bulk. If the request is sent again with the same key within 24 hours, you get the first answer back, marked Idempotent-Replayed: true, instead of a second code. A request that failed doesn't keep its key, so a retry runs again. While the first is still running, a repeat gets 409 request_in_progress; a key reused on another endpoint gets 422 idempotency_key_reused.

Building a page code? The payload shapes live in Page content.