API reference

GET/v1/me

The key, its workspace, plan, limits and this month's usage

Who you are calling as. A good first call: any key can make it, and it shows the key's scope, the workspace's plan and limits, and this month's usage.

• Needs a read key
• getMe

Responses

• 200The key context.

  Body: KeyContext

Errors

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/me \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/codes

List codes

The workspace's codes, newest first, a page at a time. Filters combine; deleted codes appear only with status=deleted.

• Needs a read key
• listCodes

Parameters

• limitintegerQuery

  Page size, 1–100.

  1 to 100 · default 25

• cursorstringQuery

  next_cursor from the previous page. Only valid with the same filters (limit may change).

• folder_idstringQuery

  Only codes in this folder; none = codes in no folder.

• kindstringQuery

  Only dynamic or only static codes. Default: both.

  one of dynamic, static

• statusstringQuery

  Only codes with this status. Default: active and disabled codes.

  one of active, disabled, deleted

• qstringQuery

  Case-insensitive substring of the name or slug. * is ignored.

  at most 200 characters

Responses

• 200A page of codes, newest first.

  Body: CodeList

Errors

400

A query parameter or the cursor is not valid (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/codes \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

POST/v1/codes

Create a dynamic code

Creates a dynamic code through the dashboard's own checks. Send an Idempotency-Key to retry safely: a retry with the same key and body within 24 hours replays the first response with Idempotent-Replayed: true. A replayed body is the original (an error keeps the first request's request_id); the X-Request-Id header is new. A test key (kq_test_) runs every check and saves nothing: the response has test: true.

• Needs a read-and-write key
• createCode

Parameters

• Idempotency-KeystringHeader

  1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response (Idempotent-Replayed: true); the same key with another body is 400 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.

Request body · application/json

CreateCode: A new dynamic code: POST /v1/codes's body.

• brand_kit_idstring (uuid)nullable

  Start from this brand kit (GET /v1/brand-kits), logo included. Omitted or null: no kit.

• designDesignInput

  Design fields that override the brand kit's design, or the default design without a kit.

• destinationstringrequired

  Where the code redirects: https, http, mailto or tel. A bare host gets https://. Checked against Google Web Risk before it's saved.

  not empty · e.g. https://example.com/spring

• folder_idstring (uuid)nullable

  The folder to put the code in (GET /v1/folders). Omitted or null: No folder.

• mediumstring

  qr: a code to print or show as a QR image. link: a short link to share as text. Both redirect the same way.

  one of qr, link · default qr

• namestringrequired

  The code's name in the dashboard. Trimmed; 1 to 120 characters.

  1 to 120 characters · e.g. Spring flyer

Other fields are refused.

Responses

• 201The code, as GET /v1/codes/{id} shows it, plus warnings.

  Body: CodeWriteResult

  Idempotent-Replayed

  true when this is the stored response to an earlier request with the same Idempotency-Key. The body is the original (a replayed error keeps the first request's request_id); the X-Request-Id header is new.

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

400

The body isn't a JSON object (invalid_json), a field isn't valid (invalid_parameter), the destination isn't allowed (invalid_destination), or the Idempotency-Key is invalid or was used with another request.

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

No such folder or brand kit in this workspace (folder_not_found, brand_kit_not_found).

409

The plan's dynamic-code limit is reached (plan_limit_reached), the brand kit can't be used on this plan (brand_kit_unavailable), or a request with this Idempotency-Key is still running (idempotency_in_progress).

422

Web Risk flagged the destination (unsafe_destination/destination_flagged).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

The destination couldn't be checked (destination_unverifiable), a dependency is unavailable or Redis unavailable for writes (service_unavailable), or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X POST https://api.keptqr.com/v1/codes \
  -H "Authorization: Bearer $KEPTQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/spring",
    "name": "Spring flyer"
  }'

POST/v1/codes/batch

Create up to 100 dynamic codes

Creates each item as POST /v1/codes would, in order, and answers 207 with each item's result: status 201 and the code, or the item's error (with this request's request_id). When the plan's limit is reached, the earliest items are created and the rest answer 409 plan_limit_reached. Items not started within 55 seconds answer 503 timeout, with nothing saved for them. Needs a plan with bulk creation. Each item costs one write token, all at once; a batch the write limit refuses costs none. Send an Idempotency-Key to retry safely: a replay answers the same results without spending write tokens. To finish a partly completed batch, resend only the failed items, with a new Idempotency-Key. A test key runs every check and saves nothing.

• Needs a read-and-write key
• Needs a plan that includes bulk creation
• createCodesBatch

Parameters

• Idempotency-KeystringHeader

  1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response (Idempotent-Replayed: true); the same key with another body is 400 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.

Request body · application/json

CreateCodeBatch: Up to 100 new dynamic codes: POST /v1/codes/batch's body.

• itemsarray of CreateCoderequired

  1 to 100 items, each a POST /v1/codes body. Each item is validated on its own.

  1 to 100 items

Other fields are refused.

Responses

• 207Each item's result, in order.

  Body: BatchResult

  Idempotent-Replayed

  true when this is the stored response to an earlier request with the same Idempotency-Key. The body is the original (a replayed error keeps the first request's request_id); the X-Request-Id header is new.

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

400

The body isn't a JSON object (invalid_json), items isn't an array of 1 to 100 (invalid_parameter), more than 100 items (batch_too_large), or the Idempotency-Key is invalid or was used with another request.

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access or no bulk creation on the plan (bulk_creation_required), a read-only key, or the workspace over its seat limit (seat_limit_read_only).

409

A request with this Idempotency-Key is still running (idempotency_in_progress).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

A dependency is unavailable, the request timed out, or Redis unavailable for writes (service_unavailable). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X POST https://api.keptqr.com/v1/codes/batch \
  -H "Authorization: Bearer $KEPTQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "destination": "https://example.com/spring",
        "name": "Spring flyer"
      }
    ]
  }'

GET/v1/codes/{id}

Get a code

One code by id, whatever its status, deleted dynamic codes included. A deleted static code is gone: 404.

• Needs a read key
• getCode

Parameters

• idstring (uuid)Pathrequired

  The code's id.

Responses

• 200The code.

  Body: Code

Errors

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

404

No such code in this workspace (not_found/code_not_found).

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/codes/{id} \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

PATCH/v1/codes/{id}

Edit a code

Changes any of destination (dynamic codes only), name, folder_id and design, in that order; the first refusal stops. PATCH is not transactional: if a field is refused, the fields in applied were already saved. Retry-safe: resending the same body sets the same values, and an unchanged destination is a no-op. Takes no Idempotency-Key. One write token whatever the number of fields.

• Needs a read-and-write key
• updateCode

Parameters

• idstring (uuid)Pathrequired

  The code's id.

Request body · application/json

PatchCode: The fields to change: at least one. They are applied in the order destination, name, folder_id, design.

• designDesignInput

  Merged into the stored design; the logo is kept.

• destinationstring

  Dynamic codes only. The same rules as on create; an unchanged destination is a no-op.

  not empty

• folder_idstring (uuid)nullable

  null moves the code to No folder.

• namestring

  The code's name in the dashboard. Trimmed; 1 to 120 characters.

  1 to 120 characters

Other fields are refused.

Responses

• 200The code after the edit, plus warnings.

  Body: CodeWriteResult

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

400

The body isn't valid (invalid_json, invalid_parameter, missing_parameter) or the destination isn't allowed (invalid_destination).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

No such code or folder in this workspace (code_not_found, folder_not_found).

409

The code is deleted (code_deleted), disabled (code_disabled) or static (not_dynamic), or destination edits are frozen while the workspace is over its plan (editing_frozen).

422

Web Risk flagged the destination (unsafe_destination/destination_flagged).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

The destination couldn't be checked (destination_unverifiable), a dependency is unavailable or Redis unavailable for writes (service_unavailable), or the request timed out. Retry after Retry-After.

Error body: PatchError. Codes and meanings are in the error codes table.

curl -X PATCH https://api.keptqr.com/v1/codes/{id} \
  -H "Authorization: Bearer $KEPTQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "<destination>"
  }'

DELETE/v1/codes/{id}

Delete a code

A dynamic code is soft-deleted: it stops redirecting and its slug is never reused; deleting it again answers 200. A static code is removed, so a second DELETE is 404. Never blocked by the edit freeze.

• Needs a read-and-write key
• deleteCode

Parameters

• idstring (uuid)Pathrequired

  The code's id.

Responses

• 200Deleted.

  Body: DeletedCode

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

No such code in this workspace (not_found/code_not_found).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

A dependency is unavailable, the request timed out, or Redis unavailable for writes (service_unavailable). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X DELETE https://api.keptqr.com/v1/codes/{id} \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/codes/{id}/destination-history

A dynamic code's destination history

Every change of the code's destination, newest first, a page at a time, with who made it.

• Needs a read key
• listDestinationHistory

Parameters

• idstring (uuid)Pathrequired

  The code's id.

• limitintegerQuery

  Page size, 1–100.

  1 to 100 · default 25

• cursorstringQuery

  next_cursor from the previous page. Only valid with the same filters (limit may change).

Responses

• 200Destination changes, newest first.

  Body: DestinationHistory

Errors

400

A query parameter or the cursor is not valid (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

404

No such code in this workspace (not_found/code_not_found).

409

A static code has no destination history (conflict/not_dynamic).

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/codes/{id}/destination-history \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/codes/{id}/image

Get a code's QR image

The code's QR image, drawn from its saved design the same way as the dashboard's download. A dynamic code encodes its short URL; a static code its content. SVG is 1024 × 1024; PNG takes size. Every image is decoded and checked against the code's content before it's sent: a design that doesn't scan is refused with 422 image_unscannable. A stored logo that can't be used (not a readable image) is left out, and the image is still sent with 200. The ETag covers everything the image is drawn from; send it back as If-None-Match to get 304 while the image hasn't changed.

• Needs a read key
• getCodeImage

Parameters

• idstring (uuid)Pathrequired

  The code's id.

• formatstringQuery

  The image format: svg (the default) or png.

  one of svg, png · default svg

• sizeintegerQuery

  PNG only: width and height in pixels. Default 1024. An SVG is always 1024.

  one of 512, 1024, 2048, 4096

• If-None-MatchstringHeader

  An ETag from an earlier response (or a list, or *): 304 while it still matches.

Responses

• 200The image.

  Body: image/png or image/svg+xml

  Cache-Control

  private, max-age=300

  Content-Disposition

  inline; filename="qr-{slug}.{ext}" for a dynamic code, "qr-{type}.{ext}" for a static one.

  Content-Security-Policy

  default-src 'none'; img-src data:; sandbox

  ETag

  A strong tag over everything the image is drawn from.

  X-Content-Type-Options

  nosniff

• 304If-None-Match matched the current ETag: the image hasn't changed. No body.

  Cache-Control

  private, max-age=300

  Content-Security-Policy

  default-src 'none'; img-src data:; sandbox

  ETag

  The current tag.

  X-Content-Type-Options

  nosniff

Errors

400

format or size isn't valid, or size was sent with format=svg (invalid_parameter).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

404

No such code in this workspace (not_found/code_not_found).

409

The code is deleted or disabled (conflict/code_deleted, code_disabled).

422

The image of this code's design doesn't scan, or its content doesn't fit a QR code (invalid_request/image_unscannable).

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable, the image queue is full (service_unavailable, Retry-After 5), or the request or the render timed out (timeout). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/codes/{id}/image \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/folders

List folders

The workspace's folders, newest first, a page at a time.

• Needs a read key
• listFolders

Parameters

• limitintegerQuery

  Page size, 1–100.

  1 to 100 · default 25

• cursorstringQuery

  next_cursor from the previous page. Only valid with the same filters (limit may change).

Responses

• 200A page of folders, newest first.

  Body: FolderList

Errors

400

limit or the cursor is not valid (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/folders \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

POST/v1/folders

Create a folder

Names can repeat: a second folder with the same name is a new folder.

• Needs a read-and-write key
• createFolder

Parameters

• Idempotency-KeystringHeader

  1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response (Idempotent-Replayed: true); the same key with another body is 400 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.

Request body · application/json

• namestringrequired

  Trimmed; 1 to 80 characters. Names can repeat.

  1 to 80 characters · e.g. Spring campaign

Other fields are refused.

Responses

• 201The new folder.

  Body: FolderWriteResult

  Idempotent-Replayed

  true when this is the stored response to an earlier request with the same Idempotency-Key. The body is the original (a replayed error keeps the first request's request_id); the X-Request-Id header is new.

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

400

The body is not a JSON object, a field is not valid, or the Idempotency-Key is not valid or was used with another request (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

A retry with the same Idempotency-Key whose folder has since been deleted (not_found/folder_not_found).

409

A request with this Idempotency-Key is still in progress (conflict/idempotency_in_progress).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

A dependency is unavailable, the request timed out, or Redis unavailable for writes (service_unavailable). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X POST https://api.keptqr.com/v1/folders \
  -H "Authorization: Bearer $KEPTQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring campaign"
  }'

PATCH/v1/folders/{id}

Rename a folder

Gives the folder a new name. Its codes stay in it.

• Needs a read-and-write key
• updateFolder

Parameters

• idstring (uuid)Pathrequired

  The folder's id.

Request body · application/json

• namestringrequired

  Trimmed; 1 to 80 characters. Names can repeat.

  1 to 80 characters · e.g. Spring campaign

Other fields are refused.

Responses

• 200The renamed folder.

  Body: FolderWriteResult

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

400

The body is not a JSON object or a field is not valid (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

No such folder in this workspace (not_found/folder_not_found).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

A dependency is unavailable, the request timed out, or Redis unavailable for writes (service_unavailable). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X PATCH https://api.keptqr.com/v1/folders/{id} \
  -H "Authorization: Bearer $KEPTQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring campaign"
  }'

DELETE/v1/folders/{id}

Delete a folder

Its codes move to No folder; they are not deleted.

• Needs a read-and-write key
• deleteFolder

Parameters

• idstring (uuid)Pathrequired

  The folder's id.

Responses

• 200The folder was deleted.

  Body: DeletedFolder

  RateLimit

  The request and write buckets: "requests";r={remaining};t={seconds}, "writes";r={remaining};t={seconds}.

Errors

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, a read-only key, or the workspace over its seat limit (seat_limit_read_only).

404

No such folder in this workspace (not_found/folder_not_found).

429

Per-minute rate limit, monthly quota, too many failed authentications, or writes_per_minute.

500

Something went wrong on our side.

503

A dependency is unavailable, the request timed out, or Redis unavailable for writes (service_unavailable). Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl -X DELETE https://api.keptqr.com/v1/folders/{id} \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/brand-kits

List brand kits

Every brand kit in the workspace, the default first, then by name. Not paginated. Pass a kit's id as brand_kit_id when creating a code; kits are edited in the dashboard.

• Needs a read key
• listBrandKits

Responses

• 200Every brand kit, the default first.

  Body: BrandKitList

Errors

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/brand-kits \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/codes/{id}/stats

A dynamic code's scan stats

Whole UTC days, both ends included. Default: the last 30 days.

• Needs a read key
• getCodeStats

Parameters

• idstring (uuid)Pathrequired

  The code's id.

• fromstring (date)Query

  First UTC day, included. Default: 29 days before to. Moved later to the plan's history limit and, per code, to its creation day.

  e.g. 2026-10-14

• tostring (date)Query

  Last UTC day, included. Default and latest: today (UTC).

  e.g. 2026-10-14

Responses

• 200The code's scans over the window.

  Body: CodeStats

Errors

400

A date is not valid, from is after to, or the window is over 366 days (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

404

No such code in this workspace (not_found/code_not_found).

409

A static code has no scan stats (conflict/not_dynamic).

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/codes/{id}/stats \
  -H "Authorization: Bearer $KEPTQR_API_KEY"

GET/v1/stats

The workspace's scan stats

Whole UTC days, both ends included. Default: the last 30 days.

• Needs a read key
• getWorkspaceStats

Parameters

• fromstring (date)Query

  First UTC day, included. Default: 29 days before to. Moved later to the plan's history limit and, per code, to its creation day.

  e.g. 2026-10-14

• tostring (date)Query

  Last UTC day, included. Default and latest: today (UTC).

  e.g. 2026-10-14

• topintegerQuery

  How many top codes, 1–50.

  1 to 50 · default 10

Responses

• 200The workspace's scans over the window, with its top codes.

  Body: WorkspaceStats

Errors

400

A date or top is not valid, from is after to, or the window is over 366 days (invalid_request).

401

Missing, malformed, unknown, revoked or expired key (authentication).

403

Browser call, suspended, no API access on the plan, or not allowed for this key.

429

Per-minute rate limit, monthly quota, or too many failed authentications.

500

Something went wrong on our side.

503

A dependency is unavailable or the request timed out. Retry after Retry-After.

Error body: Error. Codes and meanings are in the error codes table.

curl https://api.keptqr.com/v1/stats \
  -H "Authorization: Bearer $KEPTQR_API_KEY"