Getting started

The qr.new API provides a method for creating QR codes with text in the code pattern making them actually informative that your users may actually want to scan! 🤯

API Keys

Create an unrestricted API Key. This will let you create QR codes that link to any site.

If you are concerned that someone else may try to use your key (which would count against your total quota), you can create a scoped API Key, which can only make QR codes for a specific site.

Scoped API Keys

An API key can either be scoped to a specific site, meaning it can only create QR codes that link to that site (or a sub-path of that site), or it can be unrestricted, and create QR codes that link to any site.

If you aren't concerned about someone else using your API key, then you don't need to scope it.

An API key scoped to https://www.example.com/mysite/...

...could create QR codes for:
https://www.example.com/mysite/✅ Exact match
https://www.example.com/mysite/2✅ Sub-path
https://www.example.com/mysite/2/3/4/5✅ Sub-path
https://www.example.com/mysite/2/abc/example.html✅ Sub-path

...but could not create QR codes for:
http://www.example.com/mysite/❌ Different protocol (http vs https)
https://www.example.com/❌ Not a sub-path
https://www.example.com/mysite2/❌ Not a sub-path
https://www.example.co/mysite/❌ Different domain
https://qr.new/docs❌ Different domain
https://google.com/?q=www.example.com❌ Different domain

An unrestricted API key could create QR codes for...

everything.

Scoped API Key
Unrestricted API Key

Endpoints

GET
api.qr.new/v0/qr

Gets or creates a QR code linking to the provided url.

Query ParameterDescription
key
Required
Your API key.
urlOptional, but highly recommended. URL that the QR code should point to.

See Setting the url.
innerTextText that should be displayed in the QR code pattern. If omitted, the site's title information will be used for the inner text.

See Setting the inner text.
darkColorColor (in hex) for the dark pixels of the QR code. Defaults to 828282ff.
Be careful changing this - you could render the QR code unscannable.
textColorColor (in hex) for the inner text of the QR code. Defaults to 000000ff.
Be careful changing this - you could render the QR code unscannable.
lightColorColor (in hex) for the background pixels of the QR code. Defaults to ffffffff.
Be careful changing this - you could render the QR code unscannable.
formatOne of the following four values: image | link | id | redirect. Defaults to image.
image returns a PNG. link returns a fully qualified url of the form https://qr.new/{id}, id returns the id of QR code, redirect will redirect to the url.

Setting the url

If the url parameter is omitted, the value of the Referer header will be used. That is, an omitted url parameter will get or create a QR code that links to the site that is making the request. If a scoped API key is used and the key isn't scoped to the site making the request, returns an error.

The Referrer-Policy for your site has to be no-referrer-when-downgrade to use this endpoint on your site when omitting the url parameter, or the policy on the specific element should be no-referrer-when-downgrade.

<img src="" referrerpolicy="no-referrer-when-downgrade" />

All this being said, though, browsers are increasingly limiting referrer headers, so setting the url is recommended, otherwise you may be getting QR codes that merely link to the origin of the request.



Setting the inner text

The following is used as precedence for setting the inner text of a QR code - the first valid value will be used:

  1. Meta tag on the destination site (specified by url) with the name qr:innerText and the content being what you want the inner text to be, i.e.
<meta name="qr:innerText" content="hello">
  1. innerText query parameter.
  2. og:title meta tag content.
  3. twitter:title meta tag content.
  4. title tag inner text.
  5. The url itself

Note that if the qr:innerText meta tag is set on the destination url, the innerText query parameter will be ignored.

"Scan me" is not an acceptable value for any of the above fields or for innerText. If set as any of the above fields, it will be skipped.

https://api.qr.new/v0/qr?key=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGFpbXMiOlsicXI6bGluazpodHRwczovL3FyLm5ldy8iXSwiaWF0IjoxNjE1MDcyOTA2LCJhdWQiOiJhcGkucXIubmV3Iiwic3ViIjoiUTJSTmFKSzBMcWZ3bEhMS1VlTUswclF4cDY1MyIsImp0aSI6IlNiY2JUOXJrVHFXNTljSjAxRXhtIn0.UsEIWDajfh2TmCKahat58LyE0ruJvW4BQOKIzPmMvB8&innerText=API%20Docs%20%3A)&textColor=1f4acc&darkColor=00000000&url=https%3A%2F%2Fqr.new%2Fdocs
Open in new tab

Use Cases & Examples


Set the endpoint as the content of your og:image meta tag:

<meta name="og:image" content="https://api.qr.new/v0/qr?key=…">

Then, when the link is shared via text, Slack, Twitter, or elsewhere, it will be accompanied by an actually potentially useful QR code instead of a useless stock image.

Send https://qr.new/docs in a Slack message or text https://qr.new/docs to yourself or share https://qr.new/docs broadly on twitter to see an example.


Set type to link to get a short link to a given url.


Just an image of text please

Set both darkColor and lightColor to white or transparent to get just an image of text in a blocky font.

Pricing

FreeStarterProEnterprise
Price$0$6/month$30/monthContact us
Good forPersonal branding

One-off QR code creation
Small websites

Teams

Social Media usage
Large websites

Services
Sites with user generated pages/dynamic content

Inventory management
Total number of unique URLs*up to 5up to 50up to 350>350
Number of QR codes per unique URL

(i.e., different QR codes for different inner text or colors)
UnlimitedUnlimitedUnlimitedUnlimited
Number of scans/clicks per QR CodeUnlimitedUnlimitedUnlimitedUnlimited
Number of API callsUnlimitedUnlimitedUnlimitedUnlimited

*For example, if you create a QR code that links to https://example.com, any subsequent QR codes you create that link to https://example.com, regardless of other QR creation parameters, like inner text or color, will not count against your usage, since you have already created a link to that site.

If you create another QR code that links to https://mysite.com, you would then have 2 unique URLs counting against your usage, https://example.com and https://mysite.com.

You can see the unique URLs you have created codes for here.

Starter
Up to 50 unique URLs
Unlimited QR codes per unique URL
Unlimited scans
Unlimited API calls
Pro
Up to 350 unique URLs
Unlimited QR codes per unique URL
Unlimited scans
Unlimited API calls

If you don't already have one, it's highly recommended that you create an account before purchasing a subscription.