QR + link-in-bio API
Manage QR codes, bio pages and analytics with a project API key. Send it as Authorization: Bearer qrc_…. Every answer is JSON; errors use one envelope with a closed set of codes.
- Base URL
https://qrc.adclaw.io/api/v1- Version
- 1
- Key
- Create one in Settings → API keys. It belongs to one project and is shown once.
Authentication
Send a project API key as a bearer token on every request. A key starts with qrc_, belongs to one project, and is shown once when it is created.
curl https://qrc.adclaw.io/api/v1/me \
-H "Authorization: Bearer qrc_…"Each operation below says which key it needs: a read key is enough for every GET; a change needs a read and write key. A revoked or expired key answers 401. Cookies are never read: a browser session is not a credential here.
Errors
Every error is one JSON envelope: { "error": { "code", "message", "details" } }. The code is one of a closed list, so a client can switch on it; the message is plain English, safe to show; details come only with a validation failure and name the fields, never what was sent.
| Code | Status | Message |
|---|---|---|
invalid_json | 400 | The request body is not valid JSON. |
validation_failed | 400 | Some fields are missing or not valid. |
unauthorized | 401 | A valid API key is required. |
key_revoked | 401 | This API key has been revoked. |
key_expired | 401 | This API key has expired. |
insufficient_scope | 403 | This API key cannot write. Create one with read and write access. |
feature_unavailable | 403 | API access is not available for this project. |
project_disabled | 403 | This project is disabled. Contact support to turn it back on. |
not_found | 404 | Not found. |
conflict | 409 | The request conflicts with the current state. |
link_archived | 409 | This QR code is archived. Restore it first. |
payload_too_large | 413 | The request body is too large (64 KB at most). |
unsupported_media_type | 415 | Send JSON with Content-Type: application/json. |
rate_limited | 429 | Too many requests. Try again shortly. |
internal_error | 500 | Something went wrong on our side. |
Rate limits
- Per key: 120 reads and 30 writes a minute, in separate windows, so a burst of reads never blocks a write.
- Per address: 20 failed sign-ins a minute, then
429. - Every answer with a key carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset; a429addsRetry-After.
Request ids
Send X-Request-Id (8 to 64 letters, digits, _ or -) and the answer echoes it; otherwise the answer carries one we made. Quote it when reporting a problem: every log line about the request has it.
Conventions
- List routes take
limitandcursorand answer{ items, nextCursor };nextCursorisnullon the last page. A cursor is opaque: pass back the one you were given. - Archived QR codes stay readable and can be restored; a write to one answers
409 link_archived, and their analytics answer404. - Ids are UUIDs. An id outside the key's project is a
404, never a403. - Dates are ISO 8601 in UTC, like
2026-10-12T09:30:00.000Z. - Bodies are JSON objects with exactly the documented fields; an unknown field is a validation failure.
PATCHsends only what changes.
Your key
The key and its project.
GET/me
The key and its project
/me
The key and its project
Confirms the key works and names the project it acts in. Call it first.
Read key
Response 200
| Field | Type | Description |
|---|---|---|
project | object | |
project.id | string (uuid) | |
project.name | string | |
project.slug | string | |
key | object | |
key.id | string (uuid) | |
key.name | string | |
key.prefix | string | The first 12 characters of the key, as the Settings list shows it. |
key.scopes | string[] | |
key.createdAt | string (date-time) | ISO 8601, UTC, e.g. |
key.expiresAt | string (date-time) or null | ISO 8601, UTC, e.g. |
version | stringOne of |
Errors
401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
QR codes
QR codes: create, read, edit, archive and restore.
GET/links
List QR codes
/links
List QR codes
The project's QR codes, newest first, with the QR codes page's search and tag filter. Live codes by default; status=archived or all for the rest. Paged by limit and cursor.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
qquery, optional | string | Search text: matches the title, the slug and the destination, in any case. |
tagquery, optional | string | Only codes filed under this tag. |
statusquery, optional | stringOne of Default |
|
limitquery, optional | integerDefault | Items per page, 1 to 200. |
cursorquery, optional | string | Where the previous page ended: its |
Response 200
| Field | Type | Description |
|---|---|---|
items | object[] | |
items[].id | string (uuid) | |
items[].slug | string | Set once, at creation; the printed code's address never changes. |
items[].url | string (uri) | The address the QR code encodes. |
items[].mode | stringOne of | |
items[].title | string or null | |
items[].destinationUrl | string or null | Where a redirect code sends people; null for a bio page. |
items[].isActive | boolean | |
items[].tags | string[] | |
items[].archivedAt | string (date-time) or null | Set while the code is archived; its printed code stops resolving. |
items[].createdAt | string (date-time) | ISO 8601, UTC, e.g. |
nextCursor | string or null | Pass as |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links
Create a QR code
/links
Create a QR code
A bio page or a redirect, with the same rules as the New QR code dialog: a redirect needs an http(s) destination; a slug is optional (one is derived from the title) and must be free. The project's brand kit, if any, sets the starting look.
Read and write key
Request body
title up to 120 characters; mode bio or redirect; slug optional, lower-case letters, digits and dashes; destinationUrl required for a redirect, http(s) only.
| Field | Type | Description |
|---|---|---|
titleoptional | string | |
moderequired | stringOne of | |
slugoptional | string | |
destinationUrloptional | string |
Response 201
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
slug | string | Set once, at creation; the printed code's address never changes. |
url | string (uri) | The address the QR code encodes. |
mode | stringOne of | |
title | string or null | |
subtitle | string or null | |
destinationUrl | string or null | Where a redirect code sends people; null for a bio page. |
avatarUrl | string or null | |
isActive | boolean | |
tags | string[] | |
archivedAt | string (date-time) or null | Set while the code is archived; its printed code stops resolving. |
createdAt | string (date-time) | ISO 8601, UTC, e.g. |
updatedAt | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
GET/links/{id}
Read a QR code
/links/{id}
Read a QR code
One QR code, archived or not.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
slug | string | Set once, at creation; the printed code's address never changes. |
url | string (uri) | The address the QR code encodes. |
mode | stringOne of | |
title | string or null | |
subtitle | string or null | |
destinationUrl | string or null | Where a redirect code sends people; null for a bio page. |
avatarUrl | string or null | |
isActive | boolean | |
tags | string[] | |
archivedAt | string (date-time) or null | Set while the code is archived; its printed code stops resolving. |
createdAt | string (date-time) | ISO 8601, UTC, e.g. |
updatedAt | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
PATCH/links/{id}
Edit a QR code's basics
/links/{id}
Edit a QR code's basics
Title, subtitle, mode, destination and on/off, with the Basics card's rules. The slug never changes. An archived code answers 409 link_archived.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
Only the fields to change; at least one. Absent keeps the saved value, null clears it.
| Field | Type | Description |
|---|---|---|
titleoptional | string or null | |
subtitleoptional | string or null | |
modeoptional | stringOne of | |
destinationUrloptional | string or null | Required when the code is, or becomes, a redirect. |
isActiveoptional | boolean |
Response 200
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
slug | string | Set once, at creation; the printed code's address never changes. |
url | string (uri) | The address the QR code encodes. |
mode | stringOne of | |
title | string or null | |
subtitle | string or null | |
destinationUrl | string or null | Where a redirect code sends people; null for a bio page. |
avatarUrl | string or null | |
isActive | boolean | |
tags | string[] | |
archivedAt | string (date-time) or null | Set while the code is archived; its printed code stops resolving. |
createdAt | string (date-time) | ISO 8601, UTC, e.g. |
updatedAt | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
DELETE/links/{id}
Archive a QR code
/links/{id}
Archive a QR code
A soft delete: the printed code stops resolving, the code and its analytics stay and it can be restored. Archiving an archived code is fine.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
ok | booleanOne of |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links/{id}/restore
Restore an archived QR code
/links/{id}/restore
Restore an archived QR code
Brings an archived code back; its printed code resolves again. A live code answers 409 conflict.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
slug | string | Set once, at creation; the printed code's address never changes. |
url | string (uri) | The address the QR code encodes. |
mode | stringOne of | |
title | string or null | |
subtitle | string or null | |
destinationUrl | string or null | Where a redirect code sends people; null for a bio page. |
avatarUrl | string or null | |
isActive | boolean | |
tags | string[] | |
archivedAt | string (date-time) or null | Set while the code is archived; its printed code stops resolving. |
createdAt | string (date-time) | ISO 8601, UTC, e.g. |
updatedAt | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
QR style
How a QR code looks and what it encodes.
GET/links/{id}/qr
Read a QR code's style
/links/{id}/qr
Read a QR code's style
The address the code encodes and its saved style.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
url | string (uri) | The address the QR code encodes. |
config | object | The saved style: dots, corners, colours, error correction and centre image, plus the Advanced sections |
config.dotsType | stringOne of | |
config.dotsColor | string | |
config.cornersSquareType | stringOne of | |
config.cornersSquareColor | string | |
config.cornersDotType | stringOne of | |
config.cornersDotColor | string | |
config.backgroundColor | string | A colour, or |
config.errorCorrectionLevel | stringOne of | |
config.imageUrl | string | The centre logo picture. |
config.logo | object | |
config.logo.enabled | boolean | |
config.logo.size | stringOne of | |
config.logo.spacing | stringOne of | |
config.logo.hideDots | boolean | |
config.logo.shape | stringOne of | |
config.logo.plate | stringOne of | |
config.logo.plateColor | string | |
config.frame | object | |
config.frame.enabled | boolean | |
config.frame.style | stringOne of | |
config.frame.text | string | |
config.frame.color | string | |
config.frame.textColor | string | |
config.openInApp | object | |
config.openInApp.enabled | boolean |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
PATCH/links/{id}/qr
Change a QR code's style
/links/{id}/qr
Change a QR code's style
Replaces the parts sent (the QR tab's style, the centre logo, the frame, open in app) and keeps the rest. The address never changes. An archived code answers 409 link_archived.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
Any of style, logo, frame, openInApp; at least one. Each replaces that part whole; the others stay as saved.
| Field | Type | Description |
|---|---|---|
styleoptional | object | The QR tab's settings, whole: dots, corners, colours, error correction, centre image. |
style.dotsTypeoptional | stringOne of | |
style.dotsColoroptional | string | |
style.cornersSquareTypeoptional | stringOne of | |
style.cornersSquareColoroptional | string | |
style.cornersDotTypeoptional | stringOne of | |
style.cornersDotColoroptional | string | |
style.backgroundColoroptional | string | |
style.errorCorrectionLeveloptional | stringOne of | |
style.imageUrloptional | string (uri) | |
logooptional | object | Advanced → Centre logo. |
logo.enabledrequired | boolean | |
logo.sizerequired | stringOne of | |
logo.spacingrequired | stringOne of | |
logo.hideDotsrequired | boolean | |
logo.shapeoptional | stringOne of | |
logo.plateoptional | stringOne of | |
logo.plateColoroptional | string | |
frameoptional | object | Advanced → Frame; |
frame.enabledrequired | boolean | |
frame.stylerequired | stringOne of | |
frame.textrequired | string | |
frame.coloroptional | string | |
frame.textColoroptional | string | |
openInAppoptional | object | Advanced → Open in app (redirect codes). |
openInApp.enabledrequired | boolean |
Response 200
| Field | Type | Description |
|---|---|---|
url | string (uri) | The address the QR code encodes. |
config | object | The saved style: dots, corners, colours, error correction and centre image, plus the Advanced sections |
config.dotsType | stringOne of | |
config.dotsColor | string | |
config.cornersSquareType | stringOne of | |
config.cornersSquareColor | string | |
config.cornersDotType | stringOne of | |
config.cornersDotColor | string | |
config.backgroundColor | string | A colour, or |
config.errorCorrectionLevel | stringOne of | |
config.imageUrl | string | The centre logo picture. |
config.logo | object | |
config.logo.enabled | boolean | |
config.logo.size | stringOne of | |
config.logo.spacing | stringOne of | |
config.logo.hideDots | boolean | |
config.logo.shape | stringOne of | |
config.logo.plate | stringOne of | |
config.logo.plateColor | string | |
config.frame | object | |
config.frame.enabled | boolean | |
config.frame.style | stringOne of | |
config.frame.text | string | |
config.frame.color | string | |
config.frame.textColor | string | |
config.openInApp | object | |
config.openInApp.enabled | boolean |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
Bio page look
A bio page's look.
GET/links/{id}/theme
Read a bio page's look
/links/{id}/theme
Read a bio page's look
The saved theme; {} for a page that keeps the default look.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
background | object | |
background.type | stringOne of | |
background.color | string | |
background.gradient | object | |
background.gradient.from | string | |
background.gradient.to | string | |
background.gradient.angle | number | |
background.imageUrl | string (uri) | |
background.pattern | object | |
background.pattern.emojis | string[] | |
background.pattern.size | number | |
background.pattern.gap | number | |
background.pattern.opacity | number | |
background.pattern.color | string | |
headerImageUrl | string (uri) | |
avatar | object | |
avatar.color | string | |
titleColor | string | |
subtitleColor | string | |
button | object | |
button.style | stringOne of | |
button.shape | stringOne of | |
button.color | string | |
button.textColor | string | |
fonts | object | |
fonts.page | stringOne of | |
fonts.title | stringOne of | |
fonts.subtitle | stringOne of | |
fonts.button | stringOne of | |
business | object | Advanced → Show up on Google: the business details published as search-friendly page data. Kept as stored by a save of the look; changed only in the link editor. |
business.enabled | boolean | |
business.kind | stringOne of | |
business.name | string | |
business.street | string | |
business.town | string | |
business.postcode | string | |
business.country | stringOne of | |
business.phone | string | |
business.website | string | |
business.hours | object | |
business.hours.mo | object[] | |
business.hours.mo[].opens | string | |
business.hours.mo[].closes | string | |
business.hours.tu | object[] | |
business.hours.tu[].opens | string | |
business.hours.tu[].closes | string | |
business.hours.we | object[] | |
business.hours.we[].opens | string | |
business.hours.we[].closes | string | |
business.hours.th | object[] | |
business.hours.th[].opens | string | |
business.hours.th[].closes | string | |
business.hours.fr | object[] | |
business.hours.fr[].opens | string | |
business.hours.fr[].closes | string | |
business.hours.sa | object[] | |
business.hours.sa[].opens | string | |
business.hours.sa[].closes | string | |
business.hours.su | object[] | |
business.hours.su[].opens | string | |
business.hours.su[].closes | string | |
a11y | object | |
a11y.enabled | boolean | |
a11y.lang | stringOne of | |
a11y.reading | boolean | |
poll | object | Advanced → Poll: one question with two to four answers shown on the page, and its round. Kept as stored by a save of the look; changed only in the link editor. |
poll.enabled | boolean | |
poll.question | string | |
poll.answers | string[] | |
poll.after | stringOne of | |
poll.round | integer | |
languages | object | |
languages.enabled | boolean | |
languages.second | stringOne of | |
languages.title | string | |
languages.subtitle | string | |
languages.blocks | object | |
iconRow | object | Advanced → Icon row: whether buttons set to show as a small icon are drawn in a row of icons under the title. Kept as stored by a save of the look; changed only in the link editor. |
iconRow.enabled | boolean | |
highlight | object | Advanced → Highlight a button: whether the one button set to pulse, shine or wiggle moves when the page opens. Kept as stored by a save of the look; changed only in the link editor. |
highlight.enabled | boolean | |
notice | object | Advanced → Notice at the top: one short line across the top of the page, with an optional link, colour and first and last days (read in the project's time zone). Kept as stored by a save of the look; changed only in the link editor. |
notice.enabled | boolean | |
notice.text | string | |
notice.url | string | |
notice.color | string | |
notice.from | string | |
notice.until | string | |
notice.timeZone | string | |
share | object | Advanced → Share button: a button on the page that shares the page's own address (the phone's share sheet, copy link, WhatsApp, Viber), at the top or the bottom, with optional words sent along. Kept as stored by a save of the look; changed only in the link editor. |
share.enabled | boolean | |
share.placement | stringOne of | |
share.actions | string[] | |
share.text | string | |
about | object | Advanced → About this page (PRO): a small About link that opens a sheet with only the facts the owner ticked (a short text, since which month the page exists, an official website, where to find them). Kept as stored by a save of the look; changed only in the link editor. |
about.enabled | boolean | |
about.since | booleanOne of | |
about.text | string | |
about.website | string | |
about.where | string | |
schedule | object | Advanced → Schedule: when the link works (an optional start and end, UTC instants) and what a scan outside that window gets (a short message or another http/https address). Kept as stored by a save of the look; changed only in the link editor. |
schedule.enabled | boolean | |
schedule.from | string (date-time) | |
schedule.until | string (date-time) | |
schedule.fallback | stringOne of | |
schedule.url | string | |
schedule.timeZone | string | |
buttonPictures | object | Advanced → Button pictures: the switch (off by default) that lets buttons carry a picture. Kept as stored by a save of the look; changed only in the link editor. |
buttonPictures.enabled | boolean | |
buttonSchedules | object | Advanced → Button schedules: the switch (off by default) that lets a button show only between two dates. Kept as stored by a save of the look; changed only in the link editor. |
buttonSchedules.enabled | boolean | |
buttonGroups | object | Advanced → Button groups: the switch (off by default) that lets a heading show the buttons under it as a section that opens on tap or as a grid (each heading's choice is its block's |
buttonGroups.enabled | boolean | |
redirectRules | object | Advanced → Redirect rules (redirect links only): up to 10 rules, tried top to bottom, each sending a scan that matches all its conditions (device, system, country, language, days and hours in the project's time zone) to its own http/https address; no match goes to the link's destination. Kept as stored by a save of the look; changed only in the link editor. |
redirectRules.enabled | boolean | |
redirectRules.rules | object[] | |
redirectRules.rules[].id | string | |
redirectRules.rules[].when | object | |
redirectRules.rules[].when.device | string[] | |
redirectRules.rules[].when.os | string[] | |
redirectRules.rules[].when.country | string[] | |
redirectRules.rules[].when.language | string[] | |
redirectRules.rules[].when.time | object | |
redirectRules.rules[].when.time.days | integer[] | |
redirectRules.rules[].when.time.from | string | |
redirectRules.rules[].when.time.to | string | |
redirectRules.rules[].url | string | |
redirectRules.timeZone | string | |
header | object | Advanced → Header style: the page's header as a full-width hero photo (the header banner, with the title on a dark fade) and/or the brand's logo in place of the typed title. Kept as stored by a save of the look; changed only in the link editor. |
header.enabled | boolean | |
header.layout | stringOne of | |
header.showAvatar | boolean | |
header.logoUrl | string | |
footer | object | Advanced → Footer: hides the "Powered by" line at the bottom of the page, or replaces it with a short line of the owner's own words and an optional http/https link. Kept as stored by a save of the look; changed only in the link editor. |
footer.enabled | boolean | |
footer.mode | stringOne of | |
footer.text | string | |
footer.url | string | |
buttonLocks | object | Advanced → Lock a button: the switch (off by default) that lets a button ask "I'm 18 or older", show a sensitive-content warning, or ask for a code before it opens (each button's lock is its block's |
buttonLocks.enabled | boolean | |
signupForm | object | Advanced → Sign-up form (PRO): the switch (off by default) that lets the page carry Sign-up form blocks, which collect visitors' email addresses with their consent. Kept as stored by a save of the look; changed only in the link editor. |
signupForm.enabled | boolean |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
PUT/links/{id}/theme
Replace a bio page's look
/links/{id}/theme
Replace a bio page's look
Saves the theme whole, as the Appearance tab does. The avatar colour, the accessibility settings and the second-language words stay as stored whatever the body says; the answer is the theme as saved. An archived code answers 409 link_archived.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
The bio page's look: background, header image, avatar colour, text and button colours, fonts, the accessibility settings and the second-language words (Advanced → Languages). Image addresses must be http(s).
| Field | Type | Description |
|---|---|---|
backgroundoptional | object | |
background.typerequired | stringOne of | |
background.coloroptional | string | |
background.gradientoptional | object | |
background.gradient.fromrequired | string | |
background.gradient.torequired | string | |
background.gradient.angleoptional | number | |
background.imageUrloptional | string (uri) | |
background.patternoptional | object | |
background.pattern.emojisrequired | string[] | |
background.pattern.sizeoptional | number | |
background.pattern.gapoptional | number | |
background.pattern.opacityoptional | number | |
background.pattern.coloroptional | string | |
headerImageUrloptional | string (uri) | |
avataroptional | object | |
avatar.coloroptional | string | |
titleColoroptional | string | |
subtitleColoroptional | string | |
buttonoptional | object | |
button.styleoptional | stringOne of | |
button.shapeoptional | stringOne of | |
button.coloroptional | string | |
button.textColoroptional | string | |
fontsoptional | object | |
fonts.pageoptional | stringOne of | |
fonts.titleoptional | stringOne of | |
fonts.subtitleoptional | stringOne of | |
fonts.buttonoptional | stringOne of | |
businessoptional | object | Advanced → Show up on Google: the business details published as search-friendly page data. Kept as stored by a save of the look; changed only in the link editor. |
business.enabledrequired | boolean | |
business.kindrequired | stringOne of | |
business.namerequired | string | |
business.streetoptional | string | |
business.townoptional | string | |
business.postcodeoptional | string | |
business.countryoptional | stringOne of | |
business.phoneoptional | string | |
business.websiteoptional | string | |
business.hoursoptional | object | |
business.hours.mooptional | object[] | |
business.hours.mo[].opensrequired | string | |
business.hours.mo[].closesrequired | string | |
business.hours.tuoptional | object[] | |
business.hours.tu[].opensrequired | string | |
business.hours.tu[].closesrequired | string | |
business.hours.weoptional | object[] | |
business.hours.we[].opensrequired | string | |
business.hours.we[].closesrequired | string | |
business.hours.thoptional | object[] | |
business.hours.th[].opensrequired | string | |
business.hours.th[].closesrequired | string | |
business.hours.froptional | object[] | |
business.hours.fr[].opensrequired | string | |
business.hours.fr[].closesrequired | string | |
business.hours.saoptional | object[] | |
business.hours.sa[].opensrequired | string | |
business.hours.sa[].closesrequired | string | |
business.hours.suoptional | object[] | |
business.hours.su[].opensrequired | string | |
business.hours.su[].closesrequired | string | |
a11yoptional | object | |
a11y.enabledrequired | boolean | |
a11y.langoptional | stringOne of | |
a11y.readingoptional | boolean | |
polloptional | object | Advanced → Poll: one question with two to four answers shown on the page, and its round. Kept as stored by a save of the look; changed only in the link editor. |
poll.enabledrequired | boolean | |
poll.questionrequired | string | |
poll.answersrequired | string[] | |
poll.afterrequired | stringOne of | |
poll.roundrequired | integer | |
languagesoptional | object | |
languages.enabledrequired | boolean | |
languages.secondrequired | stringOne of | |
languages.titleoptional | string | |
languages.subtitleoptional | string | |
languages.blocksoptional | object | |
iconRowoptional | object | Advanced → Icon row: whether buttons set to show as a small icon are drawn in a row of icons under the title. Kept as stored by a save of the look; changed only in the link editor. |
iconRow.enabledrequired | boolean | |
highlightoptional | object | Advanced → Highlight a button: whether the one button set to pulse, shine or wiggle moves when the page opens. Kept as stored by a save of the look; changed only in the link editor. |
highlight.enabledrequired | boolean | |
noticeoptional | object | Advanced → Notice at the top: one short line across the top of the page, with an optional link, colour and first and last days (read in the project's time zone). Kept as stored by a save of the look; changed only in the link editor. |
notice.enabledrequired | boolean | |
notice.textrequired | string | |
notice.urloptional | string | |
notice.coloroptional | string | |
notice.fromoptional | string | |
notice.untiloptional | string | |
notice.timeZoneoptional | string | |
shareoptional | object | Advanced → Share button: a button on the page that shares the page's own address (the phone's share sheet, copy link, WhatsApp, Viber), at the top or the bottom, with optional words sent along. Kept as stored by a save of the look; changed only in the link editor. |
share.enabledrequired | boolean | |
share.placementrequired | stringOne of | |
share.actionsrequired | string[] | |
share.textoptional | string | |
aboutoptional | object | Advanced → About this page (PRO): a small About link that opens a sheet with only the facts the owner ticked (a short text, since which month the page exists, an official website, where to find them). Kept as stored by a save of the look; changed only in the link editor. |
about.enabledrequired | boolean | |
about.sinceoptional | booleanOne of | |
about.textoptional | string | |
about.websiteoptional | string | |
about.whereoptional | string | |
scheduleoptional | object | Advanced → Schedule: when the link works (an optional start and end, UTC instants) and what a scan outside that window gets (a short message or another http/https address). Kept as stored by a save of the look; changed only in the link editor. |
schedule.enabledrequired | boolean | |
schedule.fromoptional | string (date-time) | |
schedule.untiloptional | string (date-time) | |
schedule.fallbackrequired | stringOne of | |
schedule.urloptional | string | |
schedule.timeZoneoptional | string | |
buttonPicturesoptional | object | Advanced → Button pictures: the switch (off by default) that lets buttons carry a picture. Kept as stored by a save of the look; changed only in the link editor. |
buttonPictures.enabledrequired | boolean | |
buttonSchedulesoptional | object | Advanced → Button schedules: the switch (off by default) that lets a button show only between two dates. Kept as stored by a save of the look; changed only in the link editor. |
buttonSchedules.enabledrequired | boolean | |
buttonGroupsoptional | object | Advanced → Button groups: the switch (off by default) that lets a heading show the buttons under it as a section that opens on tap or as a grid (each heading's choice is its block's |
buttonGroups.enabledrequired | boolean | |
redirectRulesoptional | object | Advanced → Redirect rules (redirect links only): up to 10 rules, tried top to bottom, each sending a scan that matches all its conditions (device, system, country, language, days and hours in the project's time zone) to its own http/https address; no match goes to the link's destination. Kept as stored by a save of the look; changed only in the link editor. |
redirectRules.enabledrequired | boolean | |
redirectRules.rulesrequired | object[] | |
redirectRules.rules[].idrequired | string | |
redirectRules.rules[].whenrequired | object | |
redirectRules.rules[].when.deviceoptional | string[] | |
redirectRules.rules[].when.osoptional | string[] | |
redirectRules.rules[].when.countryoptional | string[] | |
redirectRules.rules[].when.languageoptional | string[] | |
redirectRules.rules[].when.timeoptional | object | |
redirectRules.rules[].when.time.daysrequired | integer[] | |
redirectRules.rules[].when.time.fromoptional | string | |
redirectRules.rules[].when.time.tooptional | string | |
redirectRules.rules[].urlrequired | string | |
redirectRules.timeZoneoptional | string | |
headeroptional | object | Advanced → Header style: the page's header as a full-width hero photo (the header banner, with the title on a dark fade) and/or the brand's logo in place of the typed title. Kept as stored by a save of the look; changed only in the link editor. |
header.enabledrequired | boolean | |
header.layoutrequired | stringOne of | |
header.showAvataroptional | boolean | |
header.logoUrloptional | string | |
footeroptional | object | Advanced → Footer: hides the "Powered by" line at the bottom of the page, or replaces it with a short line of the owner's own words and an optional http/https link. Kept as stored by a save of the look; changed only in the link editor. |
footer.enabledrequired | boolean | |
footer.moderequired | stringOne of | |
footer.textoptional | string | |
footer.urloptional | string | |
buttonLocksoptional | object | Advanced → Lock a button: the switch (off by default) that lets a button ask "I'm 18 or older", show a sensitive-content warning, or ask for a code before it opens (each button's lock is its block's |
buttonLocks.enabledrequired | boolean | |
signupFormoptional | object | Advanced → Sign-up form (PRO): the switch (off by default) that lets the page carry Sign-up form blocks, which collect visitors' email addresses with their consent. Kept as stored by a save of the look; changed only in the link editor. |
signupForm.enabledrequired | boolean |
Response 200
| Field | Type | Description |
|---|---|---|
background | object | |
background.type | stringOne of | |
background.color | string | |
background.gradient | object | |
background.gradient.from | string | |
background.gradient.to | string | |
background.gradient.angle | number | |
background.imageUrl | string (uri) | |
background.pattern | object | |
background.pattern.emojis | string[] | |
background.pattern.size | number | |
background.pattern.gap | number | |
background.pattern.opacity | number | |
background.pattern.color | string | |
headerImageUrl | string (uri) | |
avatar | object | |
avatar.color | string | |
titleColor | string | |
subtitleColor | string | |
button | object | |
button.style | stringOne of | |
button.shape | stringOne of | |
button.color | string | |
button.textColor | string | |
fonts | object | |
fonts.page | stringOne of | |
fonts.title | stringOne of | |
fonts.subtitle | stringOne of | |
fonts.button | stringOne of | |
business | object | Advanced → Show up on Google: the business details published as search-friendly page data. Kept as stored by a save of the look; changed only in the link editor. |
business.enabled | boolean | |
business.kind | stringOne of | |
business.name | string | |
business.street | string | |
business.town | string | |
business.postcode | string | |
business.country | stringOne of | |
business.phone | string | |
business.website | string | |
business.hours | object | |
business.hours.mo | object[] | |
business.hours.mo[].opens | string | |
business.hours.mo[].closes | string | |
business.hours.tu | object[] | |
business.hours.tu[].opens | string | |
business.hours.tu[].closes | string | |
business.hours.we | object[] | |
business.hours.we[].opens | string | |
business.hours.we[].closes | string | |
business.hours.th | object[] | |
business.hours.th[].opens | string | |
business.hours.th[].closes | string | |
business.hours.fr | object[] | |
business.hours.fr[].opens | string | |
business.hours.fr[].closes | string | |
business.hours.sa | object[] | |
business.hours.sa[].opens | string | |
business.hours.sa[].closes | string | |
business.hours.su | object[] | |
business.hours.su[].opens | string | |
business.hours.su[].closes | string | |
a11y | object | |
a11y.enabled | boolean | |
a11y.lang | stringOne of | |
a11y.reading | boolean | |
poll | object | Advanced → Poll: one question with two to four answers shown on the page, and its round. Kept as stored by a save of the look; changed only in the link editor. |
poll.enabled | boolean | |
poll.question | string | |
poll.answers | string[] | |
poll.after | stringOne of | |
poll.round | integer | |
languages | object | |
languages.enabled | boolean | |
languages.second | stringOne of | |
languages.title | string | |
languages.subtitle | string | |
languages.blocks | object | |
iconRow | object | Advanced → Icon row: whether buttons set to show as a small icon are drawn in a row of icons under the title. Kept as stored by a save of the look; changed only in the link editor. |
iconRow.enabled | boolean | |
highlight | object | Advanced → Highlight a button: whether the one button set to pulse, shine or wiggle moves when the page opens. Kept as stored by a save of the look; changed only in the link editor. |
highlight.enabled | boolean | |
notice | object | Advanced → Notice at the top: one short line across the top of the page, with an optional link, colour and first and last days (read in the project's time zone). Kept as stored by a save of the look; changed only in the link editor. |
notice.enabled | boolean | |
notice.text | string | |
notice.url | string | |
notice.color | string | |
notice.from | string | |
notice.until | string | |
notice.timeZone | string | |
share | object | Advanced → Share button: a button on the page that shares the page's own address (the phone's share sheet, copy link, WhatsApp, Viber), at the top or the bottom, with optional words sent along. Kept as stored by a save of the look; changed only in the link editor. |
share.enabled | boolean | |
share.placement | stringOne of | |
share.actions | string[] | |
share.text | string | |
about | object | Advanced → About this page (PRO): a small About link that opens a sheet with only the facts the owner ticked (a short text, since which month the page exists, an official website, where to find them). Kept as stored by a save of the look; changed only in the link editor. |
about.enabled | boolean | |
about.since | booleanOne of | |
about.text | string | |
about.website | string | |
about.where | string | |
schedule | object | Advanced → Schedule: when the link works (an optional start and end, UTC instants) and what a scan outside that window gets (a short message or another http/https address). Kept as stored by a save of the look; changed only in the link editor. |
schedule.enabled | boolean | |
schedule.from | string (date-time) | |
schedule.until | string (date-time) | |
schedule.fallback | stringOne of | |
schedule.url | string | |
schedule.timeZone | string | |
buttonPictures | object | Advanced → Button pictures: the switch (off by default) that lets buttons carry a picture. Kept as stored by a save of the look; changed only in the link editor. |
buttonPictures.enabled | boolean | |
buttonSchedules | object | Advanced → Button schedules: the switch (off by default) that lets a button show only between two dates. Kept as stored by a save of the look; changed only in the link editor. |
buttonSchedules.enabled | boolean | |
buttonGroups | object | Advanced → Button groups: the switch (off by default) that lets a heading show the buttons under it as a section that opens on tap or as a grid (each heading's choice is its block's |
buttonGroups.enabled | boolean | |
redirectRules | object | Advanced → Redirect rules (redirect links only): up to 10 rules, tried top to bottom, each sending a scan that matches all its conditions (device, system, country, language, days and hours in the project's time zone) to its own http/https address; no match goes to the link's destination. Kept as stored by a save of the look; changed only in the link editor. |
redirectRules.enabled | boolean | |
redirectRules.rules | object[] | |
redirectRules.rules[].id | string | |
redirectRules.rules[].when | object | |
redirectRules.rules[].when.device | string[] | |
redirectRules.rules[].when.os | string[] | |
redirectRules.rules[].when.country | string[] | |
redirectRules.rules[].when.language | string[] | |
redirectRules.rules[].when.time | object | |
redirectRules.rules[].when.time.days | integer[] | |
redirectRules.rules[].when.time.from | string | |
redirectRules.rules[].when.time.to | string | |
redirectRules.rules[].url | string | |
redirectRules.timeZone | string | |
header | object | Advanced → Header style: the page's header as a full-width hero photo (the header banner, with the title on a dark fade) and/or the brand's logo in place of the typed title. Kept as stored by a save of the look; changed only in the link editor. |
header.enabled | boolean | |
header.layout | stringOne of | |
header.showAvatar | boolean | |
header.logoUrl | string | |
footer | object | Advanced → Footer: hides the "Powered by" line at the bottom of the page, or replaces it with a short line of the owner's own words and an optional http/https link. Kept as stored by a save of the look; changed only in the link editor. |
footer.enabled | boolean | |
footer.mode | stringOne of | |
footer.text | string | |
footer.url | string | |
buttonLocks | object | Advanced → Lock a button: the switch (off by default) that lets a button ask "I'm 18 or older", show a sensitive-content warning, or ask for a code before it opens (each button's lock is its block's |
buttonLocks.enabled | boolean | |
signupForm | object | Advanced → Sign-up form (PRO): the switch (off by default) that lets the page carry Sign-up form blocks, which collect visitors' email addresses with their consent. Kept as stored by a save of the look; changed only in the link editor. |
signupForm.enabled | boolean |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
Bio page buttons
A bio page's buttons and content.
GET/links/{id}/blocks
List a bio page's blocks
/links/{id}/blocks
List a bio page's blocks
The page's buttons, headings, texts and dividers top to bottom (hidden ones included), and the blocks removed from it (which can be restored).
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
blocks | object[] | |
blocks[].id | string (uuid) | |
blocks[].type | stringOne of | The button's service ( |
blocks[].subtype | string or null | A variant of the type, when it has one; usually null. |
blocks[].label | string | The button's text (the service's name when none was given); a heading's or text's content; an image's description; |
blocks[].value | string | Where it leads, as stored: a URL, |
blocks[].config | object | |
blocks[].config.message | string | A WhatsApp message. |
blocks[].config.subject | string | An email's subject. |
blocks[].config.body | string | An email's body. |
blocks[].config.text | string | A divider's words, shown in the middle of its line. |
blocks[].width | stringOne of |
|
blocks[].position | integer | Its place on the page: top to bottom, left to right. |
blocks[].isActive | boolean | False while it is hidden from the public page. |
removed | object[] | Blocks removed from the page; each can be restored. |
removed[].id | string (uuid) | |
removed[].type | stringOne of | The button's service ( |
removed[].label | string | |
removed[].value | string | |
removed[].removedAt | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links/{id}/blocks
Add a block
/links/{id}/blocks
Add a block
Adds a button, heading, text, image, gallery or divider at the end of the page, built with the editor's own rules: a bad input answers validation_failed with the input's path (fields.url, label, …; an image whose fields.url is not one of this project's uploaded pictures, or whose file is gone, is refused on fields.url, and a gallery picture likewise on its own fields.pictureN). An archived code answers 409 link_archived.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
| Field | Type | Description |
|---|---|---|
typerequired | stringOne of | The button's service ( |
subtypeoptional | string or null | A variant of the type, when it has one; leave out otherwise. |
labeloptional | string | The button's text (the service's name when left out or blank), a heading's (up to 80 characters) or text's (up to 500) content, or an image's description for people who can't see it (required, up to 200). A gallery ignores it: its pictures are described one by one in |
fieldsoptional | objectDefault | The type's inputs by name: |
Response 201
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
type | stringOne of | The button's service ( |
subtype | string or null | A variant of the type, when it has one; usually null. |
label | string | The button's text (the service's name when none was given); a heading's or text's content; an image's description; |
value | string | Where it leads, as stored: a URL, |
config | object | |
config.message | string | A WhatsApp message. |
config.subject | string | An email's subject. |
config.body | string | An email's body. |
config.text | string | A divider's words, shown in the middle of its line. |
width | stringOne of |
|
position | integer | Its place on the page: top to bottom, left to right. |
isActive | boolean | False while it is hidden from the public page. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
PATCH/links/{id}/blocks/{blockId}
Edit a block
/links/{id}/blocks/{blockId}
Edit a block
Its label, inputs, variant or visibility, with the editor's rules; its width is kept. A removed block answers 404.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
blockIdpath, required | string (uuid) | The block's id. |
Request body
Only the fields to change; at least one. An input left out keeps its saved value. The type never changes; the width is the layout's.
| Field | Type | Description |
|---|---|---|
subtypeoptional | string or null | A variant of the type, when it has one; leave out otherwise. |
labeloptional | string | The button's text (the service's name when left out or blank), a heading's (up to 80 characters) or text's (up to 500) content, or an image's description for people who can't see it (required, up to 200). A gallery ignores it: its pictures are described one by one in |
fieldsoptional | object | The type's inputs by name: |
isActiveoptional | boolean | Show ( |
Response 200
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
type | stringOne of | The button's service ( |
subtype | string or null | A variant of the type, when it has one; usually null. |
label | string | The button's text (the service's name when none was given); a heading's or text's content; an image's description; |
value | string | Where it leads, as stored: a URL, |
config | object | |
config.message | string | A WhatsApp message. |
config.subject | string | An email's subject. |
config.body | string | An email's body. |
config.text | string | A divider's words, shown in the middle of its line. |
width | stringOne of |
|
position | integer | Its place on the page: top to bottom, left to right. |
isActive | boolean | False while it is hidden from the public page. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
DELETE/links/{id}/blocks/{blockId}
Remove a block
/links/{id}/blocks/{blockId}
Remove a block
Takes it off the page and lists it under removed: its taps keep their history and it can be restored. The block beside it, if any, gets the line to itself. A block already removed answers 404.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
blockIdpath, required | string (uuid) | The block's id. |
Response 200
| Field | Type | Description |
|---|---|---|
ok | booleanOne of |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links/{id}/blocks/{blockId}/restore
Restore a removed block
/links/{id}/blocks/{blockId}/restore
Restore a removed block
Brings a removed block back, hidden, at the end of the page and on a line of its own, so the public page is unchanged until it is shown. A block that is not removed, or a page with no room, answers 409 conflict.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
blockIdpath, required | string (uuid) | The block's id. |
Response 200
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
type | stringOne of | The button's service ( |
subtype | string or null | A variant of the type, when it has one; usually null. |
label | string | The button's text (the service's name when none was given); a heading's or text's content; an image's description; |
value | string | Where it leads, as stored: a URL, |
config | object | |
config.message | string | A WhatsApp message. |
config.subject | string | An email's subject. |
config.body | string | An email's body. |
config.text | string | A divider's words, shown in the middle of its line. |
width | stringOne of |
|
position | integer | Its place on the page: top to bottom, left to right. |
isActive | boolean | False while it is hidden from the public page. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
PUT/links/{id}/blocks/layout
Set the page's layout
/links/{id}/blocks/layout
Set the page's layout
The order of the page's blocks and which two share a line, as the editor's arrows and drag save it. The lines must hold exactly the page's blocks (hidden ones included, removed ones left out), each once, or nothing changes (validation_failed on lines).
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
| Field | Type | Description |
|---|---|---|
linesrequired | array[] | Every block on the page once, top to bottom: |
Response 200
| Field | Type | Description |
|---|---|---|
blocks | object[] | |
blocks[].id | string (uuid) | |
blocks[].type | stringOne of | The button's service ( |
blocks[].subtype | string or null | A variant of the type, when it has one; usually null. |
blocks[].label | string | The button's text (the service's name when none was given); a heading's or text's content; an image's description; |
blocks[].value | string | Where it leads, as stored: a URL, |
blocks[].config | object | |
blocks[].config.message | string | A WhatsApp message. |
blocks[].config.subject | string | An email's subject. |
blocks[].config.body | string | An email's body. |
blocks[].config.text | string | A divider's words, shown in the middle of its line. |
blocks[].width | stringOne of |
|
blocks[].position | integer | Its place on the page: top to bottom, left to right. |
blocks[].isActive | boolean | False while it is hidden from the public page. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
Placements
Printed runs of a QR code.
GET/links/{id}/placements
List a QR code's placements
/links/{id}/placements
List a QR code's placements
The live placements with their scans in the last 30 days, as the Advanced → Placements card shows them. Archived placements are left out.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Response 200
| Field | Type | Description |
|---|---|---|
placements | object[] | |
placements[].id | string (uuid) | |
placements[].label | string | |
placements[].code | string | The short code in its address ( |
placements[].url | string (uri) | The address this placement's QR code encodes: the code's own plus |
placements[].scans | integer | Scans in the last 30 days. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links/{id}/placements
Add a placement
/links/{id}/placements
Add a placement
A new printed placement of the code, named; its code and address are made here. A name a live placement already has, or a 21th live placement, answers 409 conflict. An archived code answers 409 link_archived.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
Request body
| Field | Type | Description |
|---|---|---|
labelrequired | string | What the owner calls it ("Shop window"): 1 to 40 characters once cleaned, not "Default", and not the name of another live placement of the code. |
Response 201
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
label | string | |
code | string | The short code in its address ( |
url | string (uri) | The address this placement's QR code encodes: the code's own plus |
scans | integer | Scans in the last 30 days. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).413The body is over 64 KB (
payload_too_large).415The body is not
application/json(unsupported_media_type).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
POST/links/{id}/placements/{placementId}/archive
Archive a placement
/links/{id}/placements/{placementId}/archive
Archive a placement
Its printed code then counts as Default; its history stays. Archiving an archived placement answers the same.
Read and write key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
placementIdpath, required | string (uuid) | The placement's id. |
Response 200
| Field | Type | Description |
|---|---|---|
ok | booleanOne of |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.409The change clashes with the current state (
conflict), or the QR code is archived and must be restored first (link_archived).429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
Analytics
Scans and taps.
GET/analytics
The project's analytics
/analytics
The project's analytics
What the Analytics page shows for the window: totals against the window before, the daily series, breakdowns, the top QR codes and recent events. Archived codes are left out.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
rangequery, optional | stringOne of Default | The window in days: 7, 30 or 90 (the default). |
Response 200
| Field | Type | Description |
|---|---|---|
range | numberOne of | The window, in days. |
totals | object | |
totals.views | integer | Bio page views. |
totals.clicks | integer | Button taps. |
totals.redirects | integer | Redirect code scans. |
totals.visitors | integer | Distinct visitors. |
previousTotals | object | The same numbers for the window just before. |
previousTotals.views | integer | Bio page views. |
previousTotals.clicks | integer | Button taps. |
previousTotals.redirects | integer | Redirect code scans. |
previousTotals.visitors | integer | Distinct visitors. |
series | object[] | |
series[].date | string |
|
series[].scans | integer | |
series[].clicks | integer | |
countries | object[] | |
countries[].label | string | |
countries[].value | integer | |
devices | object[] | |
devices[].label | string | |
devices[].value | integer | |
browsers | object[] | |
browsers[].label | string | |
browsers[].value | integer | |
languages | object[] | |
languages[].label | string | |
languages[].value | integer | |
referrers | object[] | |
referrers[].label | string | |
referrers[].value | integer | |
services | object[] | Taps by the tapped button's service. |
services[].label | string | |
services[].value | integer | |
topLinks | object[] | |
topLinks[].id | string (uuid) | |
topLinks[].slug | string | |
topLinks[].title | string or null | |
topLinks[].mode | stringOne of | |
topLinks[].scans | integer | |
topLinks[].clicks | integer | |
recent | object[] | |
recent[].id | string (uuid) | |
recent[].type | stringOne of | |
recent[].slug | string | |
recent[].title | string or null | |
recent[].button | object or null | The tapped button; null for a view or a redirect. |
recent[].button.label | string | |
recent[].button.type | string | |
recent[].country | string or null | |
recent[].deviceType | string or null | |
recent[].browser | string or null | |
recent[].ts | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
GET/analytics/heatmap
The project's scan heatmap
/analytics/heatmap
The project's scan heatmap
Scans by weekday and hour over the window.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
rangequery, optional | stringOne of Default | The window in days: 7, 30 or 90 (the default). |
Response 200
| Field | Type | Description |
|---|---|---|
range | numberOne of | The window, in days. |
cells | integer[][] | Seven rows, Monday first, of 24 hours each (Europe/Athens): scans in that hour. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
GET/links/{id}/analytics
One QR code's analytics
/links/{id}/analytics
One QR code's analytics
The same picture as the project's, for one code. An archived code answers 404.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
rangequery, optional | stringOne of Default | The window in days: 7, 30 or 90 (the default). |
Response 200
| Field | Type | Description |
|---|---|---|
range | numberOne of | The window, in days. |
totals | object | |
totals.views | integer | Bio page views. |
totals.clicks | integer | Button taps. |
totals.redirects | integer | Redirect code scans. |
totals.visitors | integer | Distinct visitors. |
previousTotals | object | The same numbers for the window just before. |
previousTotals.views | integer | Bio page views. |
previousTotals.clicks | integer | Button taps. |
previousTotals.redirects | integer | Redirect code scans. |
previousTotals.visitors | integer | Distinct visitors. |
series | object[] | |
series[].date | string |
|
series[].scans | integer | |
series[].clicks | integer | |
countries | object[] | |
countries[].label | string | |
countries[].value | integer | |
devices | object[] | |
devices[].label | string | |
devices[].value | integer | |
browsers | object[] | |
browsers[].label | string | |
browsers[].value | integer | |
languages | object[] | |
languages[].label | string | |
languages[].value | integer | |
referrers | object[] | |
referrers[].label | string | |
referrers[].value | integer | |
services | object[] | Taps by the tapped button's service. |
services[].label | string | |
services[].value | integer | |
topLinks | object[] | |
topLinks[].id | string (uuid) | |
topLinks[].slug | string | |
topLinks[].title | string or null | |
topLinks[].mode | stringOne of | |
topLinks[].scans | integer | |
topLinks[].clicks | integer | |
recent | object[] | |
recent[].id | string (uuid) | |
recent[].type | stringOne of | |
recent[].slug | string | |
recent[].title | string or null | |
recent[].button | object or null | The tapped button; null for a view or a redirect. |
recent[].button.label | string | |
recent[].button.type | string | |
recent[].country | string or null | |
recent[].deviceType | string or null | |
recent[].browser | string or null | |
recent[].ts | string (date-time) | ISO 8601, UTC, e.g. |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
GET/links/{id}/analytics/buttons
One bio page's taps per button
/links/{id}/analytics/buttons
One bio page's taps per button
Each button's taps in the window against the window before. An archived code answers 404.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
rangequery, optional | stringOne of Default | The window in days: 7, 30 or 90 (the default). |
Response 200
| Field | Type | Description |
|---|---|---|
range | numberOne of | The window, in days. |
total | integer | |
live | object[] | Buttons on the page, hidden ones included: most taps first. |
live[].taps | integer | |
live[].previousTaps | integer | |
live[].share | integer | Whole percent of the page's taps in the window. |
live[].fraction | number | |
live[].delta | object | |
live[].button | object | |
live[].button.id | string (uuid) | |
live[].button.type | string | |
live[].button.label | string | |
live[].button.value | string | Its destination: a link, an address, a number. |
live[].button.position | integer | |
live[].button.isActive | boolean | |
live[].button.removedAt | string (date-time) or null | ISO 8601, UTC, e.g. |
removed | object[] | Buttons removed from the page that still have taps. |
removed[].taps | integer | |
removed[].previousTaps | integer | |
removed[].share | integer | Whole percent of the page's taps in the window. |
removed[].fraction | number | |
removed[].delta | object | |
removed[].button | object | |
removed[].button.id | string (uuid) | |
removed[].button.type | string | |
removed[].button.label | string | |
removed[].button.value | string | Its destination: a link, an address, a number. |
removed[].button.position | integer | |
removed[].button.isActive | boolean | |
removed[].button.removedAt | string (date-time) or null | ISO 8601, UTC, e.g. |
unknown | object or null | Taps of buttons deleted before taps kept their button; null when none. |
unknown.taps | integer | |
unknown.previousTaps | integer | |
unknown.share | integer | Whole percent of the page's taps in the window. |
unknown.fraction | number | |
unknown.delta | object |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
GET/links/{id}/analytics/placements
One QR code's scans by placement
/links/{id}/analytics/placements
One QR code's scans by placement
Scans in the window by printed placement. An archived code answers 404.
Read key
Parameters
| Name | Type | Description |
|---|---|---|
idpath, required | string (uuid) | The QR code's id. |
rangequery, optional | stringOne of Default | The window in days: 7, 30 or 90 (the default). |
Response 200
| Field | Type | Description |
|---|---|---|
range | numberOne of | The window, in days. |
items | object[] | Default first (scans no placement claims), then each placement; empty for a code with no placements. |
items[].label | string | |
items[].archived | boolean | |
items[].scans | integer |
Errors
400The body is not JSON (
invalid_json) or a field is missing or not valid (validation_failed, withdetails).401No usable key: missing or malformed (
unauthorized), revoked (key_revoked) or expired (key_expired). CarriesWWW-Authenticate: Bearer.403The key cannot do this: a read-only key on a write (
insufficient_scope), API access is not available for the project (feature_unavailable), or the project is disabled (project_disabled).404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.429Over the key's limit (
rate_limited). CarriesRetry-AfterandX-RateLimit-*.500Something failed on the server (
internal_error).
OpenAPI document
This document.
GET/openapi.json
The OpenAPI 3.1 description of this API
/openapi.json
The OpenAPI 3.1 description of this API
Generated from the same route definitions the server enforces, so it is always current. No key needed.
No key
Response 200
| Field | Type | Description |
|---|---|---|
openapi | stringOne of | |
info | object | |
info.title | string | |
info.version | string | |
paths | object |
Errors
404Nothing there for this key (
not_found): an id outside the key's project looks exactly like one that does not exist.500Something failed on the server (
internal_error).