Skip to content

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.
Download OpenAPI JSON

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.

CodeStatusMessage
invalid_json400The request body is not valid JSON.
validation_failed400Some fields are missing or not valid.
unauthorized401A valid API key is required.
key_revoked401This API key has been revoked.
key_expired401This API key has expired.
insufficient_scope403This API key cannot write. Create one with read and write access.
feature_unavailable403API access is not available for this project.
project_disabled403This project is disabled. Contact support to turn it back on.
not_found404Not found.
conflict409The request conflicts with the current state.
link_archived409This QR code is archived. Restore it first.
payload_too_large413The request body is too large (64 KB at most).
unsupported_media_type415Send JSON with Content-Type: application/json.
rate_limited429Too many requests. Try again shortly.
internal_error500Something 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-Remaining and X-RateLimit-Reset; a 429 adds Retry-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 limit and cursor and answer { items, nextCursor }; nextCursor is null on 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 answer 404.
  • Ids are UUIDs. An id outside the key's project is a 404, never a 403.
  • 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. PATCH sends only what changes.

Your key

The key and its project.

GET

/me

The key and its project

Confirms the key works and names the project it acts in. Call it first.

Read key

Response 200

FieldTypeDescription
projectobject
project.idstring (uuid)
project.namestring
project.slugstring
keyobject
key.idstring (uuid)
key.namestring
key.prefixstring

The first 12 characters of the key, as the Settings list shows it.

key.scopesstring[]
key.createdAtstring (date-time)

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

key.expiresAtstring (date-time) or null

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

versionstring

One of v1

Errors

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something 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

The address the code encodes and its saved style.

Read key

Parameters

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Response 200

FieldTypeDescription
urlstring (uri)

The address the QR code encodes.

configobject

The saved style: dots, corners, colours, error correction and centre image, plus the Advanced sections logo, frame and openInApp when set.

config.dotsTypestring

One of square, rounded, dots, classy, classy-rounded, extra-rounded

config.dotsColorstring
config.cornersSquareTypestring

One of square, dot, extra-rounded, rounded, classy, classy-rounded

config.cornersSquareColorstring
config.cornersDotTypestring

One of square, dot, rounded, extra-rounded, classy, classy-rounded, dots

config.cornersDotColorstring
config.backgroundColorstring

A colour, or transparent.

config.errorCorrectionLevelstring

One of L, M, Q, H

config.imageUrlstring

The centre logo picture.

config.logoobject
config.logo.enabledboolean
config.logo.sizestring

One of small, medium, large

config.logo.spacingstring

One of none, tight, normal, roomy

config.logo.hideDotsboolean
config.logo.shapestring

One of original, circle, rounded

config.logo.platestring

One of none, paper, custom

config.logo.plateColorstring
config.frameobject
config.frame.enabledboolean
config.frame.stylestring

One of label-below, label-above, bubble, badge, caption

config.frame.textstring
config.frame.colorstring
config.frame.textColorstring
config.openInAppobject
config.openInApp.enabledboolean

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

PATCH

/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

NameTypeDescription
idpath, requiredstring (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.

FieldTypeDescription
styleoptionalobject

The QR tab's settings, whole: dots, corners, colours, error correction, centre image.

style.dotsTypeoptionalstring

One of square, rounded, dots, classy, classy-rounded, extra-rounded

style.dotsColoroptionalstring
style.cornersSquareTypeoptionalstring

One of square, dot, extra-rounded, rounded, classy, classy-rounded

style.cornersSquareColoroptionalstring
style.cornersDotTypeoptionalstring

One of square, dot, rounded, extra-rounded

style.cornersDotColoroptionalstring
style.backgroundColoroptionalstring
style.errorCorrectionLeveloptionalstring

One of L, M, Q, H

style.imageUrloptionalstring (uri)
logooptionalobject

Advanced → Centre logo.

logo.enabledrequiredboolean
logo.sizerequiredstring

One of small, medium, large

logo.spacingrequiredstring

One of none, tight, normal, roomy

logo.hideDotsrequiredboolean
logo.shapeoptionalstring

One of original, circle, rounded

logo.plateoptionalstring

One of none, paper, custom

logo.plateColoroptionalstring
frameoptionalobject

Advanced → Frame; text is 1 to 24 letters, digits, spaces or simple punctuation.

frame.enabledrequiredboolean
frame.stylerequiredstring

One of label-below, label-above, bubble, badge, caption

frame.textrequiredstring
frame.coloroptionalstring
frame.textColoroptionalstring
openInAppoptionalobject

Advanced → Open in app (redirect codes).

openInApp.enabledrequiredboolean

Response 200

FieldTypeDescription
urlstring (uri)

The address the QR code encodes.

configobject

The saved style: dots, corners, colours, error correction and centre image, plus the Advanced sections logo, frame and openInApp when set.

config.dotsTypestring

One of square, rounded, dots, classy, classy-rounded, extra-rounded

config.dotsColorstring
config.cornersSquareTypestring

One of square, dot, extra-rounded, rounded, classy, classy-rounded

config.cornersSquareColorstring
config.cornersDotTypestring

One of square, dot, rounded, extra-rounded, classy, classy-rounded, dots

config.cornersDotColorstring
config.backgroundColorstring

A colour, or transparent.

config.errorCorrectionLevelstring

One of L, M, Q, H

config.imageUrlstring

The centre logo picture.

config.logoobject
config.logo.enabledboolean
config.logo.sizestring

One of small, medium, large

config.logo.spacingstring

One of none, tight, normal, roomy

config.logo.hideDotsboolean
config.logo.shapestring

One of original, circle, rounded

config.logo.platestring

One of none, paper, custom

config.logo.plateColorstring
config.frameobject
config.frame.enabledboolean
config.frame.stylestring

One of label-below, label-above, bubble, badge, caption

config.frame.textstring
config.frame.colorstring
config.frame.textColorstring
config.openInAppobject
config.openInApp.enabledboolean

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

Bio page look

A bio page's look.

GET

/links/{id}/theme

Read a bio page's look

The saved theme; {} for a page that keeps the default look.

Read key

Parameters

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Response 200

FieldTypeDescription
backgroundobject
background.typestring

One of solid, gradient, image, pattern

background.colorstring
background.gradientobject
background.gradient.fromstring
background.gradient.tostring
background.gradient.anglenumber
background.imageUrlstring (uri)
background.patternobject
background.pattern.emojisstring[]
background.pattern.sizenumber
background.pattern.gapnumber
background.pattern.opacitynumber
background.pattern.colorstring
headerImageUrlstring (uri)
avatarobject
avatar.colorstring
titleColorstring
subtitleColorstring
buttonobject
button.stylestring

One of filled, outline, soft

button.shapestring

One of rounded, pill, square

button.colorstring
button.textColorstring
fontsobject
fonts.pagestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.titlestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.subtitlestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.buttonstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

businessobject

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.enabledboolean
business.kindstring

One of restaurant, cafe, shop, salon, other

business.namestring
business.streetstring
business.townstring
business.postcodestring
business.countrystring

One of GR, CY, AL, AU, AT, BE, BG, CA, HR, CZ, DK, EE, FI, FR, DE, HU, IE, IT, LV, LT, LU, MT, NL, MK, NO, PL, PT, RO, RS, SK, SI, ES, SE, CH, TR, GB, US

business.phonestring
business.websitestring
business.hoursobject
business.hours.moobject[]
business.hours.mo[].opensstring
business.hours.mo[].closesstring
business.hours.tuobject[]
business.hours.tu[].opensstring
business.hours.tu[].closesstring
business.hours.weobject[]
business.hours.we[].opensstring
business.hours.we[].closesstring
business.hours.thobject[]
business.hours.th[].opensstring
business.hours.th[].closesstring
business.hours.frobject[]
business.hours.fr[].opensstring
business.hours.fr[].closesstring
business.hours.saobject[]
business.hours.sa[].opensstring
business.hours.sa[].closesstring
business.hours.suobject[]
business.hours.su[].opensstring
business.hours.su[].closesstring
a11yobject
a11y.enabledboolean
a11y.langstring

One of el, en, de, fr, it, es, nl

a11y.readingboolean
pollobject

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.enabledboolean
poll.questionstring
poll.answersstring[]
poll.afterstring

One of results, thanks

poll.roundinteger
languagesobject
languages.enabledboolean
languages.secondstring

One of el, en

languages.titlestring
languages.subtitlestring
languages.blocksobject
iconRowobject

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.enabledboolean
highlightobject

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.enabledboolean
noticeobject

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.enabledboolean
notice.textstring
notice.urlstring
notice.colorstring
notice.fromstring
notice.untilstring
notice.timeZonestring
shareobject

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.enabledboolean
share.placementstring

One of top, bottom

share.actionsstring[]
share.textstring
aboutobject

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.enabledboolean
about.sinceboolean

One of true

about.textstring
about.websitestring
about.wherestring
scheduleobject

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.enabledboolean
schedule.fromstring (date-time)
schedule.untilstring (date-time)
schedule.fallbackstring

One of message, url

schedule.urlstring
schedule.timeZonestring
buttonPicturesobject

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.enabledboolean
buttonSchedulesobject

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.enabledboolean
buttonGroupsobject

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 groupLayout). Kept as stored by a save of the look; changed only in the link editor.

buttonGroups.enabledboolean
redirectRulesobject

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.enabledboolean
redirectRules.rulesobject[]
redirectRules.rules[].idstring
redirectRules.rules[].whenobject
redirectRules.rules[].when.devicestring[]
redirectRules.rules[].when.osstring[]
redirectRules.rules[].when.countrystring[]
redirectRules.rules[].when.languagestring[]
redirectRules.rules[].when.timeobject
redirectRules.rules[].when.time.daysinteger[]
redirectRules.rules[].when.time.fromstring
redirectRules.rules[].when.time.tostring
redirectRules.rules[].urlstring
redirectRules.timeZonestring
headerobject

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.enabledboolean
header.layoutstring

One of classic, hero

header.showAvatarboolean
header.logoUrlstring
footerobject

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.enabledboolean
footer.modestring

One of hide, words

footer.textstring
footer.urlstring
buttonLocksobject

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 lock; a code is stored only as a salted hash and never returned). Kept as stored by a save of the look; changed only in the link editor.

buttonLocks.enabledboolean
signupFormobject

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.enabledboolean

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

PUT

/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

NameTypeDescription
idpath, requiredstring (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).

FieldTypeDescription
backgroundoptionalobject
background.typerequiredstring

One of solid, gradient, image, pattern

background.coloroptionalstring
background.gradientoptionalobject
background.gradient.fromrequiredstring
background.gradient.torequiredstring
background.gradient.angleoptionalnumber
background.imageUrloptionalstring (uri)
background.patternoptionalobject
background.pattern.emojisrequiredstring[]
background.pattern.sizeoptionalnumber
background.pattern.gapoptionalnumber
background.pattern.opacityoptionalnumber
background.pattern.coloroptionalstring
headerImageUrloptionalstring (uri)
avataroptionalobject
avatar.coloroptionalstring
titleColoroptionalstring
subtitleColoroptionalstring
buttonoptionalobject
button.styleoptionalstring

One of filled, outline, soft

button.shapeoptionalstring

One of rounded, pill, square

button.coloroptionalstring
button.textColoroptionalstring
fontsoptionalobject
fonts.pageoptionalstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.titleoptionalstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.subtitleoptionalstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.buttonoptionalstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

businessoptionalobject

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.enabledrequiredboolean
business.kindrequiredstring

One of restaurant, cafe, shop, salon, other

business.namerequiredstring
business.streetoptionalstring
business.townoptionalstring
business.postcodeoptionalstring
business.countryoptionalstring

One of GR, CY, AL, AU, AT, BE, BG, CA, HR, CZ, DK, EE, FI, FR, DE, HU, IE, IT, LV, LT, LU, MT, NL, MK, NO, PL, PT, RO, RS, SK, SI, ES, SE, CH, TR, GB, US

business.phoneoptionalstring
business.websiteoptionalstring
business.hoursoptionalobject
business.hours.mooptionalobject[]
business.hours.mo[].opensrequiredstring
business.hours.mo[].closesrequiredstring
business.hours.tuoptionalobject[]
business.hours.tu[].opensrequiredstring
business.hours.tu[].closesrequiredstring
business.hours.weoptionalobject[]
business.hours.we[].opensrequiredstring
business.hours.we[].closesrequiredstring
business.hours.thoptionalobject[]
business.hours.th[].opensrequiredstring
business.hours.th[].closesrequiredstring
business.hours.froptionalobject[]
business.hours.fr[].opensrequiredstring
business.hours.fr[].closesrequiredstring
business.hours.saoptionalobject[]
business.hours.sa[].opensrequiredstring
business.hours.sa[].closesrequiredstring
business.hours.suoptionalobject[]
business.hours.su[].opensrequiredstring
business.hours.su[].closesrequiredstring
a11yoptionalobject
a11y.enabledrequiredboolean
a11y.langoptionalstring

One of el, en, de, fr, it, es, nl

a11y.readingoptionalboolean
polloptionalobject

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.enabledrequiredboolean
poll.questionrequiredstring
poll.answersrequiredstring[]
poll.afterrequiredstring

One of results, thanks

poll.roundrequiredinteger
languagesoptionalobject
languages.enabledrequiredboolean
languages.secondrequiredstring

One of el, en

languages.titleoptionalstring
languages.subtitleoptionalstring
languages.blocksoptionalobject
iconRowoptionalobject

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.enabledrequiredboolean
highlightoptionalobject

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.enabledrequiredboolean
noticeoptionalobject

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.enabledrequiredboolean
notice.textrequiredstring
notice.urloptionalstring
notice.coloroptionalstring
notice.fromoptionalstring
notice.untiloptionalstring
notice.timeZoneoptionalstring
shareoptionalobject

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.enabledrequiredboolean
share.placementrequiredstring

One of top, bottom

share.actionsrequiredstring[]
share.textoptionalstring
aboutoptionalobject

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.enabledrequiredboolean
about.sinceoptionalboolean

One of true

about.textoptionalstring
about.websiteoptionalstring
about.whereoptionalstring
scheduleoptionalobject

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.enabledrequiredboolean
schedule.fromoptionalstring (date-time)
schedule.untiloptionalstring (date-time)
schedule.fallbackrequiredstring

One of message, url

schedule.urloptionalstring
schedule.timeZoneoptionalstring
buttonPicturesoptionalobject

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.enabledrequiredboolean
buttonSchedulesoptionalobject

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.enabledrequiredboolean
buttonGroupsoptionalobject

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 groupLayout). Kept as stored by a save of the look; changed only in the link editor.

buttonGroups.enabledrequiredboolean
redirectRulesoptionalobject

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.enabledrequiredboolean
redirectRules.rulesrequiredobject[]
redirectRules.rules[].idrequiredstring
redirectRules.rules[].whenrequiredobject
redirectRules.rules[].when.deviceoptionalstring[]
redirectRules.rules[].when.osoptionalstring[]
redirectRules.rules[].when.countryoptionalstring[]
redirectRules.rules[].when.languageoptionalstring[]
redirectRules.rules[].when.timeoptionalobject
redirectRules.rules[].when.time.daysrequiredinteger[]
redirectRules.rules[].when.time.fromoptionalstring
redirectRules.rules[].when.time.tooptionalstring
redirectRules.rules[].urlrequiredstring
redirectRules.timeZoneoptionalstring
headeroptionalobject

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.enabledrequiredboolean
header.layoutrequiredstring

One of classic, hero

header.showAvataroptionalboolean
header.logoUrloptionalstring
footeroptionalobject

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.enabledrequiredboolean
footer.moderequiredstring

One of hide, words

footer.textoptionalstring
footer.urloptionalstring
buttonLocksoptionalobject

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 lock; a code is stored only as a salted hash and never returned). Kept as stored by a save of the look; changed only in the link editor.

buttonLocks.enabledrequiredboolean
signupFormoptionalobject

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.enabledrequiredboolean

Response 200

FieldTypeDescription
backgroundobject
background.typestring

One of solid, gradient, image, pattern

background.colorstring
background.gradientobject
background.gradient.fromstring
background.gradient.tostring
background.gradient.anglenumber
background.imageUrlstring (uri)
background.patternobject
background.pattern.emojisstring[]
background.pattern.sizenumber
background.pattern.gapnumber
background.pattern.opacitynumber
background.pattern.colorstring
headerImageUrlstring (uri)
avatarobject
avatar.colorstring
titleColorstring
subtitleColorstring
buttonobject
button.stylestring

One of filled, outline, soft

button.shapestring

One of rounded, pill, square

button.colorstring
button.textColorstring
fontsobject
fonts.pagestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.titlestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.subtitlestring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

fonts.buttonstring

One of manrope, commissioner, geologica, comfortaa, playpen-sans, arima, eb-garamond, literata, noto-serif-display, syne, roboto-slab, advent-pro

businessobject

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.enabledboolean
business.kindstring

One of restaurant, cafe, shop, salon, other

business.namestring
business.streetstring
business.townstring
business.postcodestring
business.countrystring

One of GR, CY, AL, AU, AT, BE, BG, CA, HR, CZ, DK, EE, FI, FR, DE, HU, IE, IT, LV, LT, LU, MT, NL, MK, NO, PL, PT, RO, RS, SK, SI, ES, SE, CH, TR, GB, US

business.phonestring
business.websitestring
business.hoursobject
business.hours.moobject[]
business.hours.mo[].opensstring
business.hours.mo[].closesstring
business.hours.tuobject[]
business.hours.tu[].opensstring
business.hours.tu[].closesstring
business.hours.weobject[]
business.hours.we[].opensstring
business.hours.we[].closesstring
business.hours.thobject[]
business.hours.th[].opensstring
business.hours.th[].closesstring
business.hours.frobject[]
business.hours.fr[].opensstring
business.hours.fr[].closesstring
business.hours.saobject[]
business.hours.sa[].opensstring
business.hours.sa[].closesstring
business.hours.suobject[]
business.hours.su[].opensstring
business.hours.su[].closesstring
a11yobject
a11y.enabledboolean
a11y.langstring

One of el, en, de, fr, it, es, nl

a11y.readingboolean
pollobject

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.enabledboolean
poll.questionstring
poll.answersstring[]
poll.afterstring

One of results, thanks

poll.roundinteger
languagesobject
languages.enabledboolean
languages.secondstring

One of el, en

languages.titlestring
languages.subtitlestring
languages.blocksobject
iconRowobject

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.enabledboolean
highlightobject

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.enabledboolean
noticeobject

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.enabledboolean
notice.textstring
notice.urlstring
notice.colorstring
notice.fromstring
notice.untilstring
notice.timeZonestring
shareobject

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.enabledboolean
share.placementstring

One of top, bottom

share.actionsstring[]
share.textstring
aboutobject

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.enabledboolean
about.sinceboolean

One of true

about.textstring
about.websitestring
about.wherestring
scheduleobject

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.enabledboolean
schedule.fromstring (date-time)
schedule.untilstring (date-time)
schedule.fallbackstring

One of message, url

schedule.urlstring
schedule.timeZonestring
buttonPicturesobject

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.enabledboolean
buttonSchedulesobject

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.enabledboolean
buttonGroupsobject

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 groupLayout). Kept as stored by a save of the look; changed only in the link editor.

buttonGroups.enabledboolean
redirectRulesobject

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.enabledboolean
redirectRules.rulesobject[]
redirectRules.rules[].idstring
redirectRules.rules[].whenobject
redirectRules.rules[].when.devicestring[]
redirectRules.rules[].when.osstring[]
redirectRules.rules[].when.countrystring[]
redirectRules.rules[].when.languagestring[]
redirectRules.rules[].when.timeobject
redirectRules.rules[].when.time.daysinteger[]
redirectRules.rules[].when.time.fromstring
redirectRules.rules[].when.time.tostring
redirectRules.rules[].urlstring
redirectRules.timeZonestring
headerobject

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.enabledboolean
header.layoutstring

One of classic, hero

header.showAvatarboolean
header.logoUrlstring
footerobject

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.enabledboolean
footer.modestring

One of hide, words

footer.textstring
footer.urlstring
buttonLocksobject

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 lock; a code is stored only as a salted hash and never returned). Kept as stored by a save of the look; changed only in the link editor.

buttonLocks.enabledboolean
signupFormobject

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.enabledboolean

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

Tags

The tags a QR code is filed under.

PUT

/links/{id}/tags

Replace a QR code's tags

Saves the list whole; the answer is the list as stored. An archived code answers 409 link_archived.

Read and write key

Parameters

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Request body

FieldTypeDescription
tagsrequiredstring[]

At most 8, each up to 24 characters: letters, digits, spaces and dashes, stored in lower case. Repeats are dropped, order kept.

Response 200

FieldTypeDescription
tagsstring[]

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something 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

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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Response 200

FieldTypeDescription
blocksobject[]
blocks[].idstring (uuid)
blocks[].typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

blocks[].subtypestring or null

A variant of the type, when it has one; usually null.

blocks[].labelstring

The button's text (the service's name when none was given); a heading's or text's content; an image's description; Gallery for a gallery.

blocks[].valuestring

Where it leads, as stored: a URL, mailto:, tel: or viber:// link; an image's address in this project's uploads (a gallery's first picture's); empty for a heading, text or divider.

blocks[].configobject
blocks[].config.messagestring

A WhatsApp message.

blocks[].config.subjectstring

An email's subject.

blocks[].config.bodystring

An email's body.

blocks[].config.textstring

A divider's words, shown in the middle of its line.

blocks[].widthstring

One of full, half

full: a line of its own. half: shares its line with the block beside it. Set by the layout.

blocks[].positioninteger

Its place on the page: top to bottom, left to right.

blocks[].isActiveboolean

False while it is hidden from the public page.

removedobject[]

Blocks removed from the page; each can be restored.

removed[].idstring (uuid)
removed[].typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

removed[].labelstring
removed[].valuestring
removed[].removedAtstring (date-time)

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

POST

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Request body

FieldTypeDescription
typerequiredstring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

subtypeoptionalstring or null

A variant of the type, when it has one; leave out otherwise.

labeloptionalstring

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 fields.

fieldsoptionalobject

Default {}

The type's inputs by name: url (a link, or an @handle for a service with a profile address; for an image, the address of one of this project's uploaded pictures, as the editor's library lists them), phone, message (WhatsApp), email, subject, body, query (a place or a Google Maps link), an image's size (full, medium, small), background (none, card) and corners (match, square, circle), each the first when left out, an image's optional link (an http or https address the whole picture goes to when tapped, counted as a tap like a button's; left empty for none), and a divider's text (the words shown in the middle of its line, up to 40 characters; blank or left out for a plain line). A gallery's pictures are picture1 … picture12 (each an uploaded picture's address, as for an image) with their descriptions alt1 … alt12 (each required, up to 200 characters) and optional links link1 … link12 (an http or https address the picture opens in a new tab when tapped, counted as a tap on the gallery; left empty for none), and its direction (ltr, rtl) and motion (swipe, auto), the first when left out. An "Add to calendar" button's (calendar) event is eventName (required, up to 120 characters), startDate (YYYY-MM-DD, required), startTime (HH:MM; left out for an all-day event), endDate and endTime (no end time lasts one hour; an end on another day needs both), location (up to 160), details (up to 1000, line breaks kept) and eventUrl (an http or https address), its times on the project's time zone. Names the type has no input for are ignored.

Response 201

FieldTypeDescription
idstring (uuid)
typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

subtypestring or null

A variant of the type, when it has one; usually null.

labelstring

The button's text (the service's name when none was given); a heading's or text's content; an image's description; Gallery for a gallery.

valuestring

Where it leads, as stored: a URL, mailto:, tel: or viber:// link; an image's address in this project's uploads (a gallery's first picture's); empty for a heading, text or divider.

configobject
config.messagestring

A WhatsApp message.

config.subjectstring

An email's subject.

config.bodystring

An email's body.

config.textstring

A divider's words, shown in the middle of its line.

widthstring

One of full, half

full: a line of its own. half: shares its line with the block beside it. Set by the layout.

positioninteger

Its place on the page: top to bottom, left to right.

isActiveboolean

False while it is hidden from the public page.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

PATCH

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

blockIdpath, requiredstring (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.

FieldTypeDescription
subtypeoptionalstring or null

A variant of the type, when it has one; leave out otherwise.

labeloptionalstring

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 fields.

fieldsoptionalobject

The type's inputs by name: url (a link, or an @handle for a service with a profile address; for an image, the address of one of this project's uploaded pictures, as the editor's library lists them), phone, message (WhatsApp), email, subject, body, query (a place or a Google Maps link), an image's size (full, medium, small), background (none, card) and corners (match, square, circle), each the first when left out, an image's optional link (an http or https address the whole picture goes to when tapped, counted as a tap like a button's; left empty for none), and a divider's text (the words shown in the middle of its line, up to 40 characters; blank or left out for a plain line). A gallery's pictures are picture1 … picture12 (each an uploaded picture's address, as for an image) with their descriptions alt1 … alt12 (each required, up to 200 characters) and optional links link1 … link12 (an http or https address the picture opens in a new tab when tapped, counted as a tap on the gallery; left empty for none), and its direction (ltr, rtl) and motion (swipe, auto), the first when left out. An "Add to calendar" button's (calendar) event is eventName (required, up to 120 characters), startDate (YYYY-MM-DD, required), startTime (HH:MM; left out for an all-day event), endDate and endTime (no end time lasts one hour; an end on another day needs both), location (up to 160), details (up to 1000, line breaks kept) and eventUrl (an http or https address), its times on the project's time zone. Names the type has no input for are ignored.

isActiveoptionalboolean

Show (true) or hide (false) it on the public page.

Response 200

FieldTypeDescription
idstring (uuid)
typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

subtypestring or null

A variant of the type, when it has one; usually null.

labelstring

The button's text (the service's name when none was given); a heading's or text's content; an image's description; Gallery for a gallery.

valuestring

Where it leads, as stored: a URL, mailto:, tel: or viber:// link; an image's address in this project's uploads (a gallery's first picture's); empty for a heading, text or divider.

configobject
config.messagestring

A WhatsApp message.

config.subjectstring

An email's subject.

config.bodystring

An email's body.

config.textstring

A divider's words, shown in the middle of its line.

widthstring

One of full, half

full: a line of its own. half: shares its line with the block beside it. Set by the layout.

positioninteger

Its place on the page: top to bottom, left to right.

isActiveboolean

False while it is hidden from the public page.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

DELETE

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

blockIdpath, requiredstring (uuid)

The block's id.

Response 200

FieldTypeDescription
okboolean

One of true

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

POST

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

blockIdpath, requiredstring (uuid)

The block's id.

Response 200

FieldTypeDescription
idstring (uuid)
typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

subtypestring or null

A variant of the type, when it has one; usually null.

labelstring

The button's text (the service's name when none was given); a heading's or text's content; an image's description; Gallery for a gallery.

valuestring

Where it leads, as stored: a URL, mailto:, tel: or viber:// link; an image's address in this project's uploads (a gallery's first picture's); empty for a heading, text or divider.

configobject
config.messagestring

A WhatsApp message.

config.subjectstring

An email's subject.

config.bodystring

An email's body.

config.textstring

A divider's words, shown in the middle of its line.

widthstring

One of full, half

full: a line of its own. half: shares its line with the block beside it. Set by the layout.

positioninteger

Its place on the page: top to bottom, left to right.

isActiveboolean

False while it is hidden from the public page.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

PUT

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Request body

FieldTypeDescription
linesrequiredarray[]

Every block on the page once, top to bottom: [id] for a line of its own, [left, right] for two side by side (two buttons, or two images). A heading, text, gallery or divider is always a line of its own; removed blocks are left out.

Response 200

FieldTypeDescription
blocksobject[]
blocks[].idstring (uuid)
blocks[].typestring

One of instagram, facebook, tiktok, x, youtube, whatsapp, spotify, email, phone, maps, website, custom, viber, messenger, telegram, signal, whatsappchannel, videocall, threads, pinterest, snapchat, reddit, discord, meetup, twitch, kick, bluesky, tumblr, googlereview, tripadvisor, bookingcom, airbnb, booking, calendly, tickets, form, menu, efood, wolt, box, shop, etsy, vinted, ebay, skroutz, paypal, revolut, viva, donate, soundcloud, applemusic, youtubemusic, deezer, bandcamp, vimeo, applepodcasts, onlyfans, fansly, patreon, kofi, buymeacoffee, substack, gumroad, medium, linkedin, github, behance, dribbble, appstore, googleplay, contact, calendar, header, text, image, gallery, divider, faq, findus, quotes, events, posts, signup

The button's service (instagram, whatsapp, email, website, …) or header, text, image, gallery, divider.

blocks[].subtypestring or null

A variant of the type, when it has one; usually null.

blocks[].labelstring

The button's text (the service's name when none was given); a heading's or text's content; an image's description; Gallery for a gallery.

blocks[].valuestring

Where it leads, as stored: a URL, mailto:, tel: or viber:// link; an image's address in this project's uploads (a gallery's first picture's); empty for a heading, text or divider.

blocks[].configobject
blocks[].config.messagestring

A WhatsApp message.

blocks[].config.subjectstring

An email's subject.

blocks[].config.bodystring

An email's body.

blocks[].config.textstring

A divider's words, shown in the middle of its line.

blocks[].widthstring

One of full, half

full: a line of its own. half: shares its line with the block beside it. Set by the layout.

blocks[].positioninteger

Its place on the page: top to bottom, left to right.

blocks[].isActiveboolean

False while it is hidden from the public page.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

Placements

Printed runs of a QR code.

GET

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Response 200

FieldTypeDescription
placementsobject[]
placements[].idstring (uuid)
placements[].labelstring
placements[].codestring

The short code in its address (?p=); printed, so it never changes.

placements[].urlstring (uri)

The address this placement's QR code encodes: the code's own plus ?p=.

placements[].scansinteger

Scans in the last 30 days.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

POST

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

Request body

FieldTypeDescription
labelrequiredstring

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

FieldTypeDescription
idstring (uuid)
labelstring
codestring

The short code in its address (?p=); printed, so it never changes.

urlstring (uri)

The address this placement's QR code encodes: the code's own plus ?p=.

scansinteger

Scans in the last 30 days.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 413

    The body is over 64 KB (payload_too_large).

  • 415

    The body is not application/json (unsupported_media_type).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

POST

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

placementIdpath, requiredstring (uuid)

The placement's id.

Response 200

FieldTypeDescription
okboolean

One of true

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 409

    The change clashes with the current state (conflict), or the QR code is archived and must be restored first (link_archived).

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

Analytics

Scans and taps.

GET

/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

NameTypeDescription
rangequery, optionalstring

One of 7, 30, 90

Default 30

The window in days: 7, 30 or 90 (the default).

Response 200

FieldTypeDescription
rangenumber

One of 7, 30, 90

The window, in days.

totalsobject
totals.viewsinteger

Bio page views.

totals.clicksinteger

Button taps.

totals.redirectsinteger

Redirect code scans.

totals.visitorsinteger

Distinct visitors.

previousTotalsobject

The same numbers for the window just before.

previousTotals.viewsinteger

Bio page views.

previousTotals.clicksinteger

Button taps.

previousTotals.redirectsinteger

Redirect code scans.

previousTotals.visitorsinteger

Distinct visitors.

seriesobject[]
series[].datestring

YYYY-MM-DD.

series[].scansinteger
series[].clicksinteger
countriesobject[]
countries[].labelstring
countries[].valueinteger
devicesobject[]
devices[].labelstring
devices[].valueinteger
browsersobject[]
browsers[].labelstring
browsers[].valueinteger
languagesobject[]
languages[].labelstring
languages[].valueinteger
referrersobject[]
referrers[].labelstring
referrers[].valueinteger
servicesobject[]

Taps by the tapped button's service.

services[].labelstring
services[].valueinteger
topLinksobject[]
topLinks[].idstring (uuid)
topLinks[].slugstring
topLinks[].titlestring or null
topLinks[].modestring

One of bio, redirect

topLinks[].scansinteger
topLinks[].clicksinteger
recentobject[]
recent[].idstring (uuid)
recent[].typestring

One of view, click, redirect

recent[].slugstring
recent[].titlestring or null
recent[].buttonobject or null

The tapped button; null for a view or a redirect.

recent[].button.labelstring
recent[].button.typestring
recent[].countrystring or null
recent[].deviceTypestring or null
recent[].browserstring or null
recent[].tsstring (date-time)

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

GET

/analytics/heatmap

The project's scan heatmap

Scans by weekday and hour over the window.

Read key

Parameters

NameTypeDescription
rangequery, optionalstring

One of 7, 30, 90

Default 30

The window in days: 7, 30 or 90 (the default).

Response 200

FieldTypeDescription
rangenumber

One of 7, 30, 90

The window, in days.

cellsinteger[][]

Seven rows, Monday first, of 24 hours each (Europe/Athens): scans in that hour.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

GET

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

rangequery, optionalstring

One of 7, 30, 90

Default 30

The window in days: 7, 30 or 90 (the default).

Response 200

FieldTypeDescription
rangenumber

One of 7, 30, 90

The window, in days.

totalsobject
totals.viewsinteger

Bio page views.

totals.clicksinteger

Button taps.

totals.redirectsinteger

Redirect code scans.

totals.visitorsinteger

Distinct visitors.

previousTotalsobject

The same numbers for the window just before.

previousTotals.viewsinteger

Bio page views.

previousTotals.clicksinteger

Button taps.

previousTotals.redirectsinteger

Redirect code scans.

previousTotals.visitorsinteger

Distinct visitors.

seriesobject[]
series[].datestring

YYYY-MM-DD.

series[].scansinteger
series[].clicksinteger
countriesobject[]
countries[].labelstring
countries[].valueinteger
devicesobject[]
devices[].labelstring
devices[].valueinteger
browsersobject[]
browsers[].labelstring
browsers[].valueinteger
languagesobject[]
languages[].labelstring
languages[].valueinteger
referrersobject[]
referrers[].labelstring
referrers[].valueinteger
servicesobject[]

Taps by the tapped button's service.

services[].labelstring
services[].valueinteger
topLinksobject[]
topLinks[].idstring (uuid)
topLinks[].slugstring
topLinks[].titlestring or null
topLinks[].modestring

One of bio, redirect

topLinks[].scansinteger
topLinks[].clicksinteger
recentobject[]
recent[].idstring (uuid)
recent[].typestring

One of view, click, redirect

recent[].slugstring
recent[].titlestring or null
recent[].buttonobject or null

The tapped button; null for a view or a redirect.

recent[].button.labelstring
recent[].button.typestring
recent[].countrystring or null
recent[].deviceTypestring or null
recent[].browserstring or null
recent[].tsstring (date-time)

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

GET

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

rangequery, optionalstring

One of 7, 30, 90

Default 30

The window in days: 7, 30 or 90 (the default).

Response 200

FieldTypeDescription
rangenumber

One of 7, 30, 90

The window, in days.

totalinteger
liveobject[]

Buttons on the page, hidden ones included: most taps first.

live[].tapsinteger
live[].previousTapsinteger
live[].shareinteger

Whole percent of the page's taps in the window.

live[].fractionnumber
live[].deltaobject
live[].buttonobject
live[].button.idstring (uuid)
live[].button.typestring
live[].button.labelstring
live[].button.valuestring

Its destination: a link, an address, a number.

live[].button.positioninteger
live[].button.isActiveboolean
live[].button.removedAtstring (date-time) or null

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

removedobject[]

Buttons removed from the page that still have taps.

removed[].tapsinteger
removed[].previousTapsinteger
removed[].shareinteger

Whole percent of the page's taps in the window.

removed[].fractionnumber
removed[].deltaobject
removed[].buttonobject
removed[].button.idstring (uuid)
removed[].button.typestring
removed[].button.labelstring
removed[].button.valuestring

Its destination: a link, an address, a number.

removed[].button.positioninteger
removed[].button.isActiveboolean
removed[].button.removedAtstring (date-time) or null

ISO 8601, UTC, e.g. 2026-10-12T09:30:00.000Z.

unknownobject or null

Taps of buttons deleted before taps kept their button; null when none.

unknown.tapsinteger
unknown.previousTapsinteger
unknown.shareinteger

Whole percent of the page's taps in the window.

unknown.fractionnumber
unknown.deltaobject

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

GET

/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

NameTypeDescription
idpath, requiredstring (uuid)

The QR code's id.

rangequery, optionalstring

One of 7, 30, 90

Default 30

The window in days: 7, 30 or 90 (the default).

Response 200

FieldTypeDescription
rangenumber

One of 7, 30, 90

The window, in days.

itemsobject[]

Default first (scans no placement claims), then each placement; empty for a code with no placements.

items[].labelstring
items[].archivedboolean
items[].scansinteger

Errors

  • 400

    The body is not JSON (invalid_json) or a field is missing or not valid (validation_failed, with details).

  • 401

    No usable key: missing or malformed (unauthorized), revoked (key_revoked) or expired (key_expired). Carries WWW-Authenticate: Bearer.

  • 403

    The 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).

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 429

    Over the key's limit (rate_limited). Carries Retry-After and X-RateLimit-*.

  • 500

    Something failed on the server (internal_error).

OpenAPI document

This document.

GET

/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

FieldTypeDescription
openapistring

One of 3.1.0

infoobject
info.titlestring
info.versionstring
pathsobject

Errors

  • 404

    Nothing there for this key (not_found): an id outside the key's project looks exactly like one that does not exist.

  • 500

    Something failed on the server (internal_error).