Getting started

The sw.ink API provides a method for creating swinks and QR codes with text in the code pattern.

API Keys

Create an unrestricted API Key. This will let you create swinks and 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 swinks for a specific domain.

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 swinks 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 swinks 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://sw.ink/docs❌ Different domain
https://google.com/?q=www.example.com❌ Different domain

An unrestricted API key could create swinks for...

everything.

Endpoints

GET
api.sw.ink/v0/swink

Gets or creates a swink linking to the provided url.

Query ParameterDescription
key
Required
Your API key.
urlOptional, but highly recommended. URL that the swink 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: qr | strictQr | absoluteQr | link | id | redirect. Defaults to qr.

qr returns a PNG.
strictQr returns a PNG using a strict font without partially filled in blocks.
absoluteQr returns the binary string representation of a smaller QR that does not have inner text.
link returns a fully qualified url of the form https://sw.ink/{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 swink 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 swinks 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.sw.ink/v0/swink?key=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGFpbXMiOlsicXI6bGluazpodHRwczovL3N3Lmluay8iXSwiaWF0IjoxNjIwMDYyODE0LCJhdWQiOiJhcGkucXIubmV3Iiwic3ViIjoiUTJSTmFKSzBMcWZ3bEhMS1VlTUswclF4cDY1MyIsImp0aSI6ImlDNG4zVTA5VTU2TE9PWWZyNGNuIn0.WlROknkKQ0DMV567aRltOeEzGLaKXLyNgTit6PxsgC4&innerText=API%20Docs%20%3A)&textColor=1f4acc&darkColor=00000000&url=https%3A%2F%2Fsw.ink%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.sw.ink/v0/swink?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://sw.ink/docs in a Slack message or text https://sw.ink/docs to yourself or share https://sw.ink/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.