QR Codes API

Generate and manage QR codes for your short links.

Every short link can have a QR code that encodes its short URL. Because the QR encodes the short URL rather than the destination, you can repoint the link later without reprinting the code — scans keep working. The QR Codes API lets you generate a code (choosing format, size, and error-correction level), read its current scan and download counts, and download the rendered image.

Generate returns the image inline as base64 in the data field, while the download endpoint streams a ready-to-save file with the correct content type.

POST/api/v1/links/:id/qr

Generate a QR code for a link.

Scope: links:write

Parameters

Name	Type	Default	Description
`format`	string	"png"	"png" or "svg"
`size`	number	1024	256-2048 pixels
`errorCorrection`	string	"M"	"L", "M", "Q", or "H"

Request

curl -X POST https://trimlink.co/api/v1/links/9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c/qr \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "size": 1024,
    "errorCorrection": "M"
  }'

Response

201Response

{
  "success": true,
  "data": {
    "id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f7a8b9",
    "format": "png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 1024,
    "downloadCount": 0,
    "scanCount": 0
  }
}

Response Fields

Field	Type	Description
`id`	string	QR code identifier (UUID); use it with the download endpoint.
`format`	string	`png` or `svg`.
`data`	string	The rendered QR image, base64-encoded.
`size`	number	Edge length in pixels.
`downloadCount`	number	Times the file has been downloaded via the API.
`scanCount`	number	Times the QR has been scanned (clicks attributed to the QR source).

GET/api/v1/links/:id/qr

Get existing QR code for a link.

Scope: links:read

Request

curl https://trimlink.co/api/v1/links/9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c/qr \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response

{
  "success": true,
  "data": {
    "id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f7a8b9",
    "format": "png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 1024,
    "downloadCount": 5,
    "scanCount": 42
  }
}

POST/api/v1/qr/:qrCodeId/download

Record a QR-code download — increments the download counter and updates the last-download timestamp for analytics. This endpoint does not return the image; fetch the image (PNG/SVG data) from the generate endpoint above (GET /api/v1/links/:id/qr).

Public endpoint — no API key or scope required.

Request

curl -X POST https://trimlink.co/api/v1/qr/3a4b5c6d-7e8f-4901-a2b3-c4d5e6f7a8b9/download

Response

Returns 200 OK on success. Errors are intentionally swallowed (still 200) so a failed track never blocks the user's download.

Errors

These endpoints use the standard error response format. Common QR-specific failures:

Code	When it happens
`400`	Invalid `format`, a `size` outside 256–2048, or an unknown `errorCorrection` level.
`403`	Key is missing the required `links:read` / `links:write` scope.
`404`	The link ID (or QR code ID on download) does not exist or belongs to another account.

Usage Notes

Prefer svg for print — it scales to any size without quality loss; use png for web and app embeds.
Higher error-correction levels (Q, H) survive damage and logo overlays but produce denser codes — see the table below.
The QR encodes the link's short URL, so editing the destination later does not invalidate already-printed codes.

Error Correction Levels

Level	Recovery	Use Case
`L`	~7%	High density, clean environments
`M`	~15%	Standard use (default)
`Q`	~25%	Industrial, outdoor use
`H`	~30%	Logo overlay, damaged codes