QR Codes API

Generate and manage QR codes for your short links.

A QR code points at the link's /qr/ short URL, for example https://trimlink.co/qr/my-link, so every scan goes through the short link and is counted as a QR click. The image comes back inside the JSON response, in the data field. There is no separate file download URL.

API keys need Pro or higher, so API-made codes never carry the TrimLink footer and can use custom colors and themed logos.

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

Create a QR code for a link. Every call creates a new code and counts toward the monthly QR limit. To change an existing code, use PATCH.

Scope: links:write

Parameters

NameTypeRequiredDescription
formatstringNo"png" (default) or "svg".
sizeintegerNoEdge length in pixels, 256 to 2048. Default 1024.
errorCorrectionstringNo"L", "M" (default), "Q" or "H". Forced to "H" when a logo is set.
foregroundColorstringNoHex color such as "#1F2937". Default "#000000".
logoPresetstringNo"trimlink" (default), "none", or a themed logo: "wifi", "globe", "cart", "restaurant".

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

Response

201Response
{
  "success": true,
  "data": {
    "id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f7a8b9",
    "format": "png",
    "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 1024,
    "errorCorrection": "H",
    "foregroundColor": "#000000",
    "logoPreset": "trimlink",
    "downloadCount": 0,
    "scanCount": 0
  }
}

Response fields

FieldMeaning
idQR code ID (UUID). Use it with the download counter.
dataThe image. A PNG comes back as a data URL (data:image/png;base64,...), an SVG as the SVG markup.
downloadCountTimes the download counter was called for this code.
scanCountClicks on the link that came through a QR scan. POST returns 0.
GET/api/v1/links/:id/qr

Get the QR code of a link, with its current scan and download counts. Returns "data": null when the link has no QR code yet.

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": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 1024,
    "errorCorrection": "H",
    "foregroundColor": "#000000",
    "logoPreset": "trimlink",
    "downloadCount": 5,
    "scanCount": 42
  }
}
PATCH/api/v1/links/:id/qr

Redraw the link's existing QR code with new options. It takes the same fields as POST, and any field you leave out goes back to its default. Updating does not count toward the monthly limit.

Scope: links:write

Parameters

NameTypeRequiredDescription
formatstringNo"png" (default) or "svg".
sizeintegerNoEdge length in pixels, 256 to 2048. Default 1024.
errorCorrectionstringNo"L", "M" (default), "Q" or "H". Forced to "H" when a logo is set.
foregroundColorstringNoHex color such as "#1F2937". Default "#000000".
logoPresetstringNo"trimlink" (default), "none", or a themed logo: "wifi", "globe", "cart", "restaurant".

Request

curl -X PATCH 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": "svg", "logoPreset": "none"}'

Response

200Response
{
  "success": true,
  "data": {
    "id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f7a8b9",
    "format": "png",
    "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 1024,
    "errorCorrection": "H",
    "foregroundColor": "#000000",
    "logoPreset": "trimlink",
    "downloadCount": 5,
    "scanCount": 42
  }
}
POST/api/v1/qr/:qrCodeId/download

Add one to the download counter of a QR code, for example when your app saves the image. It returns no image. It always answers 200, so a failed count never blocks your download.

Scope: None. This counter is public and takes no API key.

Request

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

Response

200Response
{ "success": true }

Errors

These endpoints use the standard error response format.

CodeWhen it happens
400Bad format, a size outside 256 to 2048, an unknown errorCorrection level, an invalid hex color, or a link ID that is not a UUID.
403The key lacks links:read or links:write, or a plan limit was hit: the monthly QR limit (Pro 50, Growth 150, Teams 500, Enterprise unlimited) or the custom logo, which needs Growth or higher. Limit errors include tier, limit and current.
404The link does not exist in your workspace, or PATCH was called on a link with no QR code yet.

Usage notes

  • Use svg for print, since it scales without quality loss. Use png for web and app embeds.
  • The QR encodes the link's short URL, so the printed code keeps working as long as the link is active.
  • A custom uploaded logo is set in the dashboard. The API does not upload logo files.

Error correction levels

LevelRecovery and use
LAbout 7% recovery. Densest code, for clean surfaces.
MAbout 15% recovery. Standard use and the default.
QAbout 25% recovery. Outdoor and industrial use.
HAbout 30% recovery. Used whenever a logo sits in the middle.