QRsetter

QR code generator API

Send one POST request with a list of lines and the sheet settings, and the response is the finished file: a PDF with a grid of codes, vector SVG sheets or a ZIP with a separate file for every code. No sign-up, no payment and no API key. The API runs the same generator as the form on the home page, so the same settings give the same file.

Quick start

There is one endpoint: https://qrsetter.com/api/v1/sheets, method POST, with a JSON body. A successful response is the file itself, and an error comes back as JSON with an error code and a message. The first example builds a US Letter sheet with 3 codes and saves it as a PDF.

curl -X POST https://qrsetter.com/api/v1/sheets \
  -H "Content-Type: application/json" \
  -d '{"lines": ["https://example.com/1 Table 1", "https://example.com/2 Table 2", "https://example.com/3 Table 3"], "page_format": "letter", "output": "pdf"}' \
  -o qrsetter.pdf

The second example returns a ZIP with a separate PNG for every code. The list holds only item numbers, and url_template puts each number into the link.

curl -X POST https://qrsetter.com/api/v1/sheets \
  -H "Content-Type: application/json" \
  -d '{"lines": ["A-101", "A-102", "A-103"], "url_template": "https://example.com/item/{value}", "output": "png"}' \
  -o qrsetter-png.zip

Call the API from your server or a script. It sends no CORS headers, so a browser blocks a page on another site from reading the response.

Parameters

Only lines is required. The other fields are optional and match the settings of the form. Lengths are in centimeters (1 in = 2.54 cm), and border_width and border_radius are in millimeters. Boolean fields accept true and false, and also 1 and 0.

Field Type Default Description
lines array of strings, or one string with line breaks required The list of codes, one line per code. Empty lines are an error. For links, phones, email and EAN-13 the caption goes after a space, so write a phone number without spaces, for example +15551234567 Front desk. For text, SMS, DataMatrix and Code 128 the caption goes after "|". A Wi-Fi line has three parts separated by ";": network name, password, caption. An empty password makes an open network, otherwise the code uses WPA/WPA2 and the password needs 8 to 63 characters. A contact card line has five parts separated by ";": name, phone, email, organization, caption.
content_type string url What every line encodes: url, text, phone, sms, wifi, vcard, email, ean13, datamatrix, code128.
url_template string not set Link template with {value}. Every line of the list goes in place of {value}: A-101 with https://example.com/item/{value} becomes https://example.com/item/A-101. Used only when content_type is url.
datamatrix_gs1 boolean false GS1 DataMatrix mode: the code starts with FNC1, and the text <GS> in a line becomes the field separator. Used only when content_type is datamatrix.
output string svg Response format: pdf, svg, svg_files, png.
qr_size_cm number 2 Side of a QR or DataMatrix code in centimeters, from 1 to 15. For ean13 it sets the barcode width, from 2.9 to 7.5, 3.7 by default. For code128 it sets the width, from 3 to 13, 5 by default.
margin_edge number 1.7 Margin at the sheet edges in centimeters, from 0 to 9.
margin_between number 0.6 Gap between neighboring codes in centimeters, from 0.1 to 5.
frame_margin number 0.3 Space between the code and the frame in centimeters, from 0.1 to 10.
border_width number 0.2 Frame line width in millimeters, from 0 to 2. Zero removes the frame.
border_radius number 0.8 Corner radius of the frame in millimeters, from 0 to 5.
frame_mode string code Where the frame goes: code (around the code), code_label (around the code and the caption, and the caption inside takes qr_color), none (no frame, and frame_margin stays as empty space around the code).
cut_marks boolean false Cut marks: short strokes at the corners of the cell around every code, in the gaps and in the sheet margins. The generator draws them when margin_between is at least 0.5 and margin_edge at least 0.25, otherwise the sheet has no marks.
qr_color string #000000 Code color in HEX. With too little contrast against the background the API returns VALIDATION_ERROR.
bg_color string #ffffff Background color in HEX.
bg_transparent boolean false Transparent background instead of bg_color.
page_format string a4 Sheet format: a4, a3, a5, a6, letter.
page_orientation string portrait Sheet orientation: portrait, landscape.

Every tab of the form on the home page shows its line format next to the list field.

Response formats

A PDF always comes as one document. With svg, svg_files and png one sheet or one code comes as a single file, and two or more come in a ZIP. Check the Content-Type of the response to tell them apart.

  • pdf: one document with all the sheets, ready to print, application/pdf.
  • svg: sheets with a grid of codes. One sheet comes as qrsetter.svg (image/svg+xml), several as qrsetter.zip.
  • svg_files: a vector file for every code. One code comes as an SVG file, several as qrsetter-svg.zip.
  • png: an image for every code. One code comes as a PNG file, several as qrsetter-png.zip. A QR or DataMatrix image is 1,000 to 1,200 pixels on a side. An EAN-13 image is about 1,130 by 786 pixels. A Code 128 image is about 1,200 pixels wide, wider for long values, and its height is 40% of the width.

Files of svg_files and png are named after the line number and the caption, for example "qr-0001 Table 1.svg". Such a file holds only the code, without a sheet or a frame, so the API ignores these fields for them and does not check them: page_format, page_orientation, margin_edge, margin_between, frame_margin, border_width, border_radius, frame_mode, cut_marks. qr_size_cm does not change the size of a PNG.

A successful pdf or svg response carries four headers: X-QQkod-Total-Sheets is the number of sheets, X-QQkod-Grid is the grid of one sheet in columns and rows, for example 5x6, X-QQkod-Per-Sheet is the number of codes per sheet, X-QQkod-Items is the number of codes in the request. You get the layout without opening the file. With svg_files and png only X-QQkod-Items comes.

Errors

An error response is JSON with ok set to false. error.code is the machine-readable code from the table below, error.message is a readable explanation, and error.fields is an object with a list of messages for every field with a problem. One invalid line fails the whole request. Errors in the list itself are in error.fields.urls, and a message about a single line names it by its number, counting from 1:

{"ok": false, "error": {"code": "VALIDATION_ERROR", "message": "Check the field values", "fields": {"urls": ["Line #2: empty line, fill it in or delete it"]}, "hint": {...}}}

For common list problems error.hint carries the same tip that the form shows.

HTTP Code When
404 NOT_FOUND Any path under /api/v1/ other than /api/v1/sheets.
405 METHOD_NOT_ALLOWED The request method is not POST.
415 UNSUPPORTED_MEDIA_TYPE The Content-Type header is not application/json.
413 PAYLOAD_TOO_LARGE The request body is larger than 2 MB.
400 BAD_JSON The body is not valid JSON, or the top level is not an object.
422 VALIDATION_ERROR An unknown field, an invalid value or an invalid line in lines.
413 BATCH_LIMIT_EXCEEDED The list has too many lines or is too large, see Limits below.
429 RATE_LIMITED Too many requests from one IP address. The response has a Retry-After header.
500 INTERNAL_ERROR Any other failure on our side.

Limits

  • Up to 1,500 lines per request and 256 KB for the whole list. A link is up to 2,048 bytes, and other types have their own caps: text up to 500 characters, SMS text up to 160 characters, a Wi-Fi network name up to 32 bytes.
  • The request body is up to 2 MB.
  • One IP address gets 10 requests per minute and 300 per calendar day in UTC.

The limit is per IP address, so all clients behind one address share it. Google Apps Script, cloud functions and an office behind one router are typical cases. The API ignores the Authorization header and counts such a request against the IP limit too.

Successful responses and responses with status 400, 413, 415, 422 and 429 count toward the limit, and 404 and 405 do not. The same responses carry X-RateLimit-Limit-Minute and X-RateLimit-Remaining-Minute with the limit and what is left this minute, and X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day show the same for the day. Past the limit the API returns 429 with Retry-After in seconds. A 429 counts as well, so wait for Retry-After before the next request. If the limit is too low for your project, write to [email protected].

Terms

We put no watermarks on the codes. We delete the finished file from the server right after the response and do not log the content of the codes. A logo in the middle of the code and a preview are available only in the form. The privacy policy describes how we handle request data.