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#

id	UUID, stable for the code's lifetime
name	internal label, never shown to scanners
type	url or a page type (links, menu, vcard, …)
destination	url codes: the target URL. Page codes: the hosted page path (/p/slug), managed for you
slug	7-character short-link id
short_url	the URL the printed QR encodes; never changes
status	active or paused; paused codes keep redirecting but stop counting scans
scans	all-time scan count, near-real-time
created_at	ISO 8601 timestamp

List codes

GET/api/v1/codes

Your codes, newest first. Query: limit (default 25, max 100; larger values clamp) and offset (default 0). total counts all your codes.

# Page through every code

let offset = 0, total = Infinity;
while (offset < total) {
  const res = await fetch(
    "https://qr-tool-five.vercel.app/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
}

Get a code

GET/api/v1/codes/:id

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

Create a code

POST/api/v1/codes

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

type	optional, default url. One of: url, links, menu, vcard, video, coupon, apps, event, business, feedback, social, gallery. PDF codes are dashboard-only (422 unsupported_type)
name	optional, max 120 characters, default API QR code
destination	url codes only: an http(s) URL, checked against our malware/phishing list (422 unsafe_destination)
content	page codes only: the page payload for the type; see Page content. Omit it to create an empty page and fill it later

# Create a menu page code

curl -X POST https://qr-tool-five.vercel.app/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.

# Response shape

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 }
}

Update a code

PATCH/api/v1/codes/:id

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

name	max 120 characters; longer values are truncated
destination	url codes only. Page codes return 422 destination_not_editable; edit their content instead. Same URL validation as create
status	active or paused
content	page codes only (url and pdf return 422 content_not_editable). Replaces the page payload; see Page content

Delete a code

DELETE/api/v1/codes/:id

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.

Render the image

GET/api/v1/codes/:id/image

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

format	png (default) or svg
size	PNG pixel width, default 512, clamped to 128-2000

curl -o code.png "https://qr-tool-five.vercel.app/api/v1/codes/CODE_ID/image?size=1024" \
  -H "Authorization: Bearer qrf_YOUR_KEY"

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