QR code image API

GET https://qrdx.dev/api/v1/qr returns a QR code as an SVG or PNG image, or as a vector EPS file for print and design tools. Everything is in the query string, so the URL itself is the image: paste it into a README, an <img> tag or an email template.

![QR code](https://qrdx.dev/api/v1/qr?data=https://github.com/you/repo)

No account or API key is required.

Examples

<img
  src="https://qrdx.dev/api/v1/qr?data=https://qrdx.dev&size=256&fg=155dfc"
  width="256"
  height="256"
  alt="QR code for qrdx.dev"
/>

Download a PNG with curl (quote the URL so your shell keeps the &):

curl -o qr.png "https://qrdx.dev/api/v1/qr?data=https://qrdx.dev&format=png&size=1024"

Get a vector EPS for Illustrator, InDesign or a print shop (size is the width in points, 72 per inch, so 144 is 2 inches):

curl -o qr.eps "https://qrdx.dev/api/v1/qr?data=https://qrdx.dev&format=eps&size=144"

Stylised dots with a frame:

https://qrdx.dev/api/v1/qr?data=https://qrdx.dev&body=rounded&eye=rounded&dot=rounded&template=Arrow

Parameters

Write colors without the #, or encode it as %23: a bare # starts the URL fragment and is never sent. Enum values (level, format, template) are case-insensitive.

Pattern values

• body: circle, circle-large, square, diamond, circle-mixed, pacman, rounded, small-square, vertical-line
• eye: square, rounded, gear, circle, diya, extra-rounded, message, pointy, curly
• dot: square, rounded, circle, diamond, message, message-reverse, diya, diya-reverse, rounded-triangle, star, banner
• template: default, Arrow, StandardBox, SquareBorder, StrikedBox, Halloween

These are the same styles as the qrdx React library. The MCP server can also list them with short descriptions.

Responses

A successful request returns the image with:

• Content-Type: image/svg+xml, image/png or application/postscript (EPS is sent as a qr-code.eps download)
• Cache-Control: public, max-age=31536000, immutable
• Access-Control-Allow-Origin: *, so you can fetch it from any website

Rendering is deterministic: the same query string always returns the same bytes, which is why responses can be cached for a year.

Invalid parameters return 400 with a JSON body that names each problem:

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid query parameters",
  "data": {
    "details": [
      { "param": "size", "message": "Too small: expected number to be >=64" }
    ]
  },
  "status": 400
}

Data that doesn't fit in a QR code at the chosen error correction level also returns 400 with param: "data". Use a lower level or shorter data.

Limits

• Rate limit: 300 requests per minute per IP address. Over the limit you get 429 with a Retry-After header.
• No logos or gradients. The API renders solid colors only. For logos and gradients, use the web editor or the React library.
• The data is part of the URL. Like any URL, it can end up in server logs, browser history and caches. Don't put passwords or other secrets in it.

Scanning tips

• Keep margin at 2 or more when the image sits on a dark or busy background, such as a README in GitHub's dark mode.
• Keep good contrast between fg and bg. Dark modules on a light background scan most reliably.
• The defaults (square modules, 4-module margin) scan on every reader. Stylised shapes such as circle dots look softer but some older scanners read them less reliably — check with the scan checker.
• Test the code with a few phones before printing it.

Self-hosting

The endpoint is part of the QRdx web app, so a self-hosted instance serves it at /api/v1/qr on your own domain. Rate limiting uses Upstash Redis when it is configured and is off otherwise.