Branded QR codes
After this page, every QR code your workspace makes carries your colours and app icon, and your server can fetch a print-ready code for any link.
On this page 7
- Time
- About 10 minutes
- You need
- A link to print. For the app icon, an icon set in Settings → How your link pages look. For the API, a secret key.
- Works on
- Dashboard, or any server (curl, Node, Python, PHP, Java, Go)
A QR code is the link drawn as squares. Strait draws every code from one workspace style, so a code you download from the dashboard and one your server makes through the API look the same. Scans count as the qr channel in Analytics unless you turn that off.
1. Set your workspace's QR style
Open Dashboard → Settings → QR codes and choose:
- Code colour: the squares. Empty means black.
- Background: behind the squares. Empty means white.
- Put my app icon in the middle: uses the app icon from How your link pages look. The code then uses the highest error correction level (H), so it still scans with the middle covered.
The colours must pass one rule: the code must be darker than its background, with a contrast of at least 3:1. Phone cameras look for dark squares on a light background, so light-on-dark codes and pale colour pairs are refused, in the dashboard and in the API. The form shows the contrast as you type. Then press Save QR style. Owners, admins and members can change it; viewers can only look.
You should see: the preview in your colours, a line under the colour fields like "Contrast 21.0:1: phone cameras will read it", and "Saved ✓" after you save.
2. Download a code from the dashboard
Go to Dashboard → Links and press QR on any link. The dialog shows the code in your style and the exact URL it opens. Keep Count scans as the qr channel in Analytics ticked to add utm_source=qr to the code, then pick a download:
| Button | You get |
|---|---|
| Download PNG | 1024 × 1024 px, for screens and documents |
| PNG for print | 2048 × 2048 px |
| Download SVG | Vector, sharp at any print size |
You should see: a file named after the link in your downloads (summer-qr.png, summer-qr-2048.png or summer-qr.svg), and the code opening the link when you scan it with a phone.
3. Make codes from your server
Call GET /v1/links/{slug}/qr with a secret key. It answers with the image itself, in the workspace style unless you override it for this one code:
| Query parameter | Values | Default |
|---|---|---|
format |
png or svg |
png |
size |
128 to 2048 px | 1024 |
margin |
0 to 16 modules of quiet zone | 2 |
color, background |
hex, like 1f2937 |
the workspace style |
logo |
true or false |
the workspace style |
track |
true adds utm_source=qr |
true |
curl "https://strait.link/v1/links/summer/qr?format=svg&color=1f2937" \
-H "Authorization: Bearer $SECRET_KEY" \
--fail -o summer-qr.svgimport { writeFile } from 'node:fs/promises';
const res = await fetch('https://strait.link/v1/links/summer/qr?format=png&size=2048', {
headers: { Authorization: `Bearer ${process.env.SECRET_KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
await writeFile('summer-qr.png', Buffer.from(await res.arrayBuffer()));
console.log(res.headers.get('x-strait-qr-url'), res.headers.get('x-strait-qr-logo'));Two response headers tell you what you got: X-Strait-Qr-Url is the exact URL in the code, and X-Strait-Qr-Logo says whether the icon went in (embedded, off, no_icon, unavailable or png_needs_png_icon). Python, PHP, Java and Go versions are on the endpoint page. Write the colours without #, or as %23 (a raw # starts the URL's fragment).
You should see: summer-qr.svg on disk, and X-Strait-Qr-Url: https://hilltop.strait.link/summer?utm_source=qr.
4. Saved styles, and a whole campaign at once
For a second look (packaging in brand colours, a black-and-white flyer), save it as a style. In Dashboard → Settings → QR codes, set the colours, then under Saved styles type a name and press Save as a style. A workspace keeps up to 12, and each one passes the same 3:1 contrast rule. Pick a style in the QR dialog, or pass its id as preset to the API; color, background and logo still override it.
To print every link of a campaign, filter Dashboard → Links by the campaign and press QR ZIP for this campaign. From a server, call GET /v1/qr.zip: one code per live link, named <slug>-qr.svg (or .png), sorted by slug. GET /v1/workspace lists your saved styles (qrStyles) with their ids.
curl "https://strait.link/v1/qr.zip?campaign=diwali_sale&preset=p-packaging" \
-H "Authorization: Bearer $SECRET_KEY" \
--fail -o diwali-sale-qr-codes.zipA ZIP holds up to 500 SVG codes, or 50 PNG codes at up to 1024 px; a workspace can make 3 ZIPs a minute. Your AI tool can do the same with the MCP server (get_campaign_qr_zip).
You should see: diwali-sale-qr-codes.zip on disk, and X-Strait-Qr-Count in the response saying how many codes it holds.
5. Check scans in Analytics
Scan a downloaded code with a phone, then open Dashboard → Analytics.
You should see: the tap under the qr channel, with where it went (app, store or website), like any other tap.
Common errors
400"the QR colours are too close to scan reliably" or "the QR colour must be darker than its background". The code must be darker than its background with a contrast of 3:1 or more (light-on-dark codes are refused because many phone cameras miss them). Darken the code, lighten the background or swap them; plain black on white is always fine.400"unknown preset", or404from/v1/qr.zip. The style id doesn't exist (GET /v1/workspacelists the ids), or no live link has that campaign (check the spelling in Dashboard → Links; paused links are left out).X-Strait-Qr-Logo: png_needs_png_icon. Your app icon is a JPEG or WebP, and PNG codes can only embed a PNG icon. Ask forformat=svg, or upload a PNG icon in Settings.
Next steps
- Analytics: how we count: what a tap is, and how the qr channel is decided.
- Get a branded QR code (API reference): every parameter, the rate limit and all six languages.