API reference

GET /v1/codes

List codes. Scope: read.

Newest first. Filters combine. Sandbox keys list only sandbox codes.

POST /v1/codes

Create a fixed or editable code. Scope: write.

Editable codes get a short link on the main short domain unless `domain_id` names another. Send an `Idempotency-Key` header to retry safely.

{
  "mode": "editable",
  "type": "url",
  "name": "Spring flyer",
  "content": {
    "url": "https://example.com/spring"
  },
  "tags": [
    "print"
  ]
}

GET /v1/codes/{id}

Get a code. Scope: read.

PATCH /v1/codes/{id}

Change content, design, rules, link settings, name or folder. Scope: write.

Live on the next scan. Fields are applied in this order: content, design, rules, link, name, folder; the first refusal stops the rest. A destination change on a high-traffic code needs confirmation in the app (403 step_up_required).

{
  "content": {
    "url": "https://example.com/summer"
  }
}

DELETE /v1/codes/{id}

Move a code to the trash. Scope: write.

The code stops working and can be restored for 30 days (POST /codes/{id}/restore); then it is purged and its short link is retired.

POST /v1/codes/{id}/turn-off

Turn an editable code off. Scope: write.

POST /v1/codes/{id}/turn-on

Turn an editable code back on. Scope: write.

POST /v1/codes/{id}/archive

Archive a code. Scope: write.

POST /v1/codes/{id}/unarchive

Bring an archived code back. Scope: write.

POST /v1/codes/{id}/restore

Restore a code from the trash. Scope: write.

GET /v1/codes/{id}/image

Download the image of a code. Scope: read.

SVG, PNG, PDF or EPS with the code design. Counts against the daily API quota.

POST /v1/codes/{id}/convert

Make an editable copy of a fixed code, or a fixed copy of an editable one. Scope: write.

A new code; the original stays as it is. A fixed copy holds the editable code's current content.

POST /v1/codes/{id}/domain

Move an editable code to another domain. Scope: write.

Its short link moves to that domain. A code that was already downloaded or exported needs `confirm_breaks_printed: true`, because printed copies stop working.

{
  "domain_id": "5ca1ab1e-c0de-4a11-8e5e-0d0c5a3b1e01"
}

GET /v1/codes/{id}/print-record

The note and print runs of a code. Scope: read.

PATCH /v1/codes/{id}/note

Set the note of a code. Scope: write.

Up to 2,000 characters; an empty note removes it.

{
  "note": "Printed for the spring fair."
}

POST /v1/codes/{id}/print-runs

Record a print run of a code. Scope: write.

{
  "quantity": 500,
  "medium": "Flyer A5",
  "printed_on": "2026-10-01",
  "printer": "City Print"
}

DELETE /v1/codes/{id}/print-runs/{run_id}

Remove a print run from a code. Scope: write.

POST /v1/codes/{id}/check-again

Ask for a new check of a held code. Scope: write.

When the automatic link check held a code, this runs it again now (10 times a day per code).

GET /v1/destinations/broken

Editable codes whose destination is down. Scope: read.

Open incidents of the daily destination check, newest first: the code, its URL, the last status or error and since when it fails. A code leaves the list when its destination answers again.

POST /v1/codes/{id}/tags

Add a tag to a code. Scope: write.

Creates the tag in the workspace when it is new.

{
  "name": "print"
}

DELETE /v1/codes/{id}/tags/{name}

Remove a tag from a code. Scope: write.

GET /v1/tags

List tags. Scope: read.

With the number of codes (outside the trash) carrying each tag.

GET /v1/codes/{id}/scans

Scan counts of a code. Scope: read.

Human scans per UTC day, or summed per country or device code, over a range of up to 366 days.

GET /v1/codes/{id}/scans/events

Raw scan events of a code. Scope: raw_events.

Newest first, one row per human scan, without any visitor identifier. Needs the raw_events scope (Business and up).

POST /v1/codes/{id}/counter/reset

Set the scan counter of an editable code back to 0. Scope: write.

The analytics history stays; only the counter (and scan limits that read it) starts again.

GET /v1/scans/export

Export the scans of the workspace. Scope: read.

CSV or XLSX for the range (default 30 days). Small exports come back at once (200); larger ones are prepared in the background (202 with the export to fetch).

GET /v1/scans/exports/{id}

Download a prepared scan export. Scope: read.

404 until it is ready, and after it expires.

GET /v1/scans/realtime

Scans of the last 60 minutes. Scope: read.

Human scans per minute and the latest scans, for the workspace or one code.

POST /v1/render

Render a static code image. Scope: render.

Encodes `text` as given, or builds the text from a typed `payload` (the same types as the generator). Returns the image bytes. Daily quota: the plan `api.render` value.

{
  "payload": {
    "type": "url",
    "url": "https://example.com/menu"
  },
  "format": "svg"
}

GET /v1/folders

List folders. Scope: read.

POST /v1/folders

Create a folder. Scope: write.

{
  "name": "Spring campaign"
}

DELETE /v1/folders/{id}

Delete a folder. Scope: write.

Codes in it move to the top level; nothing is deleted with it but its subfolders.

POST /v1/folders/{id}/restore

Bring back a deleted folder. Scope: write.

The folder, its subfolders and the codes that were in them, unless they moved since.

GET /v1/domains

List domains codes can use. Scope: read.

The oqrely short domains and the custom domains of the workspace. Add and verify custom domains in the app.

POST /v1/domains

Add a custom domain. Scope: write.

Returns the DNS record to set. The first check is queued at once; call POST /domains/{id}/check to check again. Apex domains need a provider that flattens CNAMEs (send `flattening_confirmed: true`).

{
  "hostname": "qr.example.com"
}

GET /v1/domains/{id}

Get a custom domain with its setup status. Scope: read.

DELETE /v1/domains/{id}

Remove a custom domain. Scope: write.

Printed codes on it stop working. Send the hostname as `confirm` to say you mean it.

POST /v1/domains/{id}/check

Check DNS, TLS or health now. Scope: write.

One check for the current setup step, as the setup screen runs while you wait.

POST /v1/domains/{id}/default

Make a domain the default for new codes. Scope: write.

Send `unset: true` to go back to the main short domain.

{
  "unset": false
}

PATCH /v1/domains/{id}/site

Set what the domain root and unknown links answer. Scope: write.

Modes: redirect (to `site_url`), link_list (a page with up to 20 links) or not_found.

{
  "root_mode": "redirect",
  "site_url": "https://example.com"
}

POST /v1/domains/{id}/release-slugs

Release links a previous owner retired on this domain. Scope: write.

Needs a DNS check that verified the domain since you added it, and `confirm: true`: scanners of those old printed codes then reach your links.

{
  "confirm": true
}

POST /v1/destination-domains/verify

Prove you control a destination domain. Scope: write.

Checks the DNS TXT record or the meta tag (`oqrely-verify`) on the destination site. A verified domain lifts the trial rule on new destination domains.

{
  "domain": "example.com"
}

GET /v1/workspaces

List the workspaces of the account. Scope: read.

A key works in one workspace; this lists every workspace of the same account.

POST /v1/workspaces

Create a workspace. Scope: write.

Within the plan's workspaces. The key keeps working in its own workspace; create a key in the new one to use it.

{
  "name": "Events"
}

GET /v1/workspaces/current

The workspace of this key. Scope: read.

PATCH /v1/workspaces/current

Rename the workspace of this key. Scope: write.

{
  "name": "Marketing"
}

GET /v1/clients

List client workspaces. Scope: read.

Agency plans: the client workspaces of the account with their codes, scans and members.

POST /v1/clients

Create a client workspace. Scope: write.

{
  "name": "Corner Bakery"
}

POST /v1/clients/{pub_id}/invites

Invite someone to a client workspace. Scope: write.

Returns the invitation link once.

{
  "email": "[email protected]",
  "role": "viewer"
}

POST /v1/clients/{pub_id}/brand-kit

Choose the brand kit of a client workspace. Scope: write.

Its colours and logo brand what the client's scanners see. Leave `brand_kit_id` out to clear it.

{
  "brand_kit_id": null
}

POST /v1/clients/{pub_id}/copy

Copy codes between your workspace and a client workspace. Scope: write.

Up to 50 codes per call. Copies get new short links; the originals stay.

{
  "direction": "to_client",
  "code_ids": [
    "5ca1ab1e-c0de-4a11-8e5e-0d0c5a3b1e01"
  ]
}

GET /v1/branding

The branding scanners see. Scope: read.

PATCH /v1/branding

Change the branding scanners see. Scope: write.

Display name, logo (an uploaded image file), accent colour or a brand kit, on plans with custom branding.

{
  "display_name": "Corner Bakery",
  "accent": "#0B6E4F"
}

GET /v1/integrations/ga4

The GA4 connection of the workspace. Scope: read.

Whether every human scan is sent to a GA4 web stream as a `qr_scan` event. The API secret is never shown.

POST /v1/integrations/ga4

Send scans to GA4. Scope: write.

A measurement id (G-...) and a Measurement Protocol API secret from your GA4 web stream.

{
  "measurement_id": "G-ABCD1234",
  "api_secret": "secret-from-ga4"
}

DELETE /v1/integrations/ga4

Stop sending scans to GA4. Scope: write.

GET /v1/templates

List templates. Scope: read.

Published oqrely templates and the templates of the workspace.

GET /v1/webhooks

List webhook endpoints. Scope: read.

POST /v1/webhooks

Add a webhook endpoint. Scope: write.

The response carries the signing secret once; store it. URLs must use https and reach a public address.

{
  "url": "https://hooks.example.com/oqrely",
  "events": [
    "code.created",
    "code.updated"
  ]
}

GET /v1/webhooks/{id}

Get a webhook endpoint. Scope: read.

PATCH /v1/webhooks/{id}

Change a webhook endpoint. Scope: write.

Send `enabled: true` to turn an endpoint back on after it was turned off for failing.

{
  "events": [
    "code.created",
    "code.deleted"
  ]
}

DELETE /v1/webhooks/{id}

Delete a webhook endpoint. Scope: write.

Its delivery log goes with it.

GET /v1/webhooks/{id}/deliveries

Delivery log of an endpoint. Scope: read.

Newest first, each delivery with every attempt (time, status code, duration, error). Kept 30 days.

POST /v1/webhooks/{id}/deliveries/{delivery}/replay

Send a delivery again. Scope: write.

Queues the identical body (same event id) as a new delivery, signed with a fresh timestamp.

GET /v1/pages

List hosted pages. Scope: read.

Newest change first, with whether each is published.

POST /v1/pages

Create a hosted page from structured fields. Scope: write.

A new editable code with a draft page: a title, an optional subtitle and text, and up to 20 links. Publish it with POST /pages/{id}/publish.

{
  "title": "Spring menu",
  "text": "Fresh every morning.",
  "links": [
    {
      "label": "Book a table",
      "url": "https://example.com/book"
    }
  ]
}

GET /v1/pages/{id}

Get a hosted page with its draft blocks. Scope: read.

PATCH /v1/pages/{id}

Save the draft blocks of a page. Scope: write.

Adding, changing, moving and removing blocks: send the whole block list. Scanners keep the published version until you publish.

{
  "blocks": [
    {
      "id": "hd",
      "type": "header",
      "title": "Spring menu"
    }
  ]
}

POST /v1/pages/{id}/publish

Publish the draft of a page. Scope: write.

Live on the next scan. Refused with 409 and the issues while the draft has publishing errors.

POST /v1/pages/{id}/unpublish

Take a page offline. Scope: write.

POST /v1/pages/{id}/revert

Bring back an earlier published version. Scope: write.

The chosen version becomes the live page again.

{
  "version": 1
}

PATCH /v1/pages/{id}/settings

Change the settings and theme of a page. Scope: write.

Fields you leave out keep their value. `brand_kit_id` applies a brand kit: its colour, typeface and logo.

{
  "settings": {
    "title": "Spring menu"
  },
  "theme": {
    "accent": "#0B6E4F"
  }
}

POST /v1/pages/{id}/languages

Add a language version of a page. Scope: write.

Scanners see the version in their browser language. It starts as a copy of the main language.

{
  "lang": "de"
}

PATCH /v1/pages/{id}/languages/{lang}

Set the title and description of a language version. Scope: write.

{
  "title": "Speisekarte",
  "description": "Frisch jeden Morgen."
}

DELETE /v1/pages/{id}/languages/{lang}

Remove a language version of a page. Scope: write.

GET /v1/pages/{id}/submissions

List the form responses of a page. Scope: read.

Newest first. Needs the analytics permission in the workspace, like the responses inbox.

GET /v1/files

List uploaded files. Scope: read.

PDFs and images of the workspace, newest first. Upload new files in the app.

POST /v1/files

Upload a PDF or an image. Scope: write.

The file as base64 in JSON. It is checked for malware and type before it can be used (status processing, then ready). Uploading the same bytes again returns the existing file with status 200.

{
  "name": "menu.png",
  "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGD4DwABBAEAwS2OUAAAAABJRU5ErkJggg=="
}

DELETE /v1/files/{id}

Delete a file. Scope: write.

It leaves the file list and the storage meter; pages that still show it keep working until it is purged.

GET /v1/files/{id}/link

Get a short-lived link to a file. Scope: read.

A signed link to view (or with `download=true`, download) a ready file.

GET /v1/members

List the members of the workspace. Scope: read.

GET /v1/members/invites

List open invitations. Scope: read.

POST /v1/members/invites

Invite someone to the workspace. Scope: write.

Returns the invitation link once. It works for that e-mail address only, once, for 7 days.

{
  "email": "[email protected]",
  "role": "editor"
}

DELETE /v1/members/invites/{id}

Withdraw an invitation. Scope: write.

PATCH /v1/members/{user_id}

Change the role of a member. Scope: write.

{
  "role": "viewer"
}

DELETE /v1/members/{user_id}

Remove a member. Scope: write.

Their codes move to you; their API keys and assistant connections in this workspace stop.

PATCH /v1/members/{user_id}/folders

Limit a member to some folders. Scope: write.

An empty list gives the member the whole workspace again.

{
  "folder_ids": []
}

GET /v1/bulk

List bulk jobs. Scope: read.

POST /v1/bulk

Create many codes in one job. Scope: write.

Rows of url, name and tags. A request larger than the plan's bulk rows is refused before anything is created.

{
  "mode": "editable",
  "rows": [
    {
      "url": "https://example.com/a",
      "name": "Table 1"
    }
  ]
}

GET /v1/bulk/{id}

Get a bulk job with its counts. Scope: read.

POST /v1/bulk/{id}/cancel

Stop a running bulk job. Scope: write.

Rows already done stay done.

POST /v1/bulk/preview

Check rows before a bulk job. Scope: write.

Validates every row against the plan's bulk rows and the code rules, without creating anything. Then POST /bulk (or with `dry_run: true`, a dry run you apply later).

{
  "mode": "editable",
  "rows": [
    {
      "url": "https://example.com/a",
      "name": "Table 1"
    }
  ]
}

POST /v1/bulk/{id}/apply

Apply a dry run. Scope: write.

Runs the planned rows of a finished dry run for real.

POST /v1/bulk/{id}/undo

Undo a bulk update. Scope: write.

Puts back what an update job changed, within 24 hours of the run.

GET /v1/bulk/{id}/report

The rows of a bulk job with their result. Scope: read.

GET /v1/bulk/{id}/files/{name}

Download the ZIP of codes or the print sheet of a job. Scope: read.

`name` is codes.zip or sheet.pdf, as the job made them.

GET /v1/brand-kits

List brand kits. Scope: read.

Colors, logos and style the workspace applies to new codes. Pass a kit's design to codes.create as `design`.

POST /v1/brand-kits

Create a brand kit. Scope: write.

{
  "name": "Main brand",
  "colors": {
    "brand": "#0B6E4F",
    "background": "#FFFFFF",
    "accent": "#F2A541",
    "light": "#E8F5EE"
  },
  "frameId": null,
  "domainId": null
}

PATCH /v1/brand-kits/{id}

Change a brand kit. Scope: write.

Send the whole kit, as for create.

{
  "name": "Main brand",
  "colors": {
    "brand": "#0B6E4F",
    "background": "#FFFFFF",
    "accent": "#F2A541",
    "light": "#E8F5EE"
  },
  "frameId": null,
  "domainId": null
}

DELETE /v1/brand-kits/{id}

Delete a brand kit. Scope: write.

Codes keep their design.

POST /v1/brand-kits/{id}/default

Make a brand kit the default for new codes. Scope: write.