QRnaly
Sign InCreate
QRnaly Developer Docsv1.0 REST
API Keys Dashboard
OpenAPI 3.1.0 • Postman Collection v2.1.0

REST API v1 Reference

The complete machine-readable specification and official HTTP request collection for the QRnaly REST API.

Download Postman CollectionDownload OpenAPI JSONDownload OpenAPI YAMLQuickstart Guide

Architecture Guide: With API vs. Without API

QRnaly offers both a complete no-code Web Dashboard and an enterprise REST API. Resource usage and entitlement rules apply uniformly across both interfaces. Here is how they compare:

Without API (Web Studio & Dashboard)

Perfect for marketing teams, designers, and business operators who want immediate visual control.

  • Interactive frame designer, logo embedder & custom color palettes
  • Drag-and-drop PDF and image asset uploads with instant preview
  • Visual Digital Catalogue editor with section sorting & photo previews
  • High-resolution vector SVG, PDF, and PNG downloads
  • Self-serve billing, invoice PDF downloads, and seat management
With API (Programmatic REST Automation)

Designed for engineering teams integrating QR generation into apps, billing systems, or ERPs.

  • Automated QR generation per user, invoice, order, or shipping label
  • Dynamic destination updates triggered by backend lifecycle events
  • Headless digital menu and inventory sync from POS / Shopify / ERP
  • Instant 1-click in-stock / sold-out toggle from kitchen terminals
  • Real-time raw scan telemetry export to your data warehouse or BI pipeline

Governance: Rate Limits (Req/Min) vs. Monthly Resource Quotas

It is critical to distinguish between traffic rate limits and workspace resource quotas:

1. Traffic Rate Limits (Gateway Health)

Rate limits measure request frequency over 60-second sliding windows (30 req/min on Pro, 60 req/min on Business).

HTTP 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0

*Rate limits do NOT permanently consume monthly plan allowances. Wait for the window to reset and retry.

2. Resource Quotas (Workspace Allowances)

Resource quotas govern persistent database entities (e.g. 50 active dynamic QRs, 100 dynamic destination updates/mo, 1 GB storage).

HTTP 403 Forbidden / 402 Required
{ "error": "DYNAMIC_UPDATES_EXHAUSTED" }
quotaResetAt: "2026-10-01T00:00:00Z"

*Resource quotas reset on your workspace subscription billing renewal date, not the calendar month.

3. Free API Trial Semantics (50 Requests)

Free plans include 50 total requests workspace-wide during a 14-day trial at 30 req/min.

Request 49: HTTP 200 (1 left)
Request 50: HTTP 200 (0 left)
Request 51+: HTTP 403 (TRIAL_API_LIMIT_EXCEEDED)
Day 15+: HTTP 403 (API_ACCESS_REQUIRES_PAID_PLAN)

*HTTP 429 rate limit responses and 401/403 scope failures do NOT consume trial requests. 4xx validation errors on authenticated calls DO count.

All v1.0 Endpoints

50 active endpoints
GET/api/v1/meScope: None

Get authenticated workspace identity, role, and active API scopes.

GET/api/v1/usageScope: None

Retrieve dynamic QR counts, monthly dynamic updates, asset storage, and rate limits.

GET/api/v1/qrScope: qr:read

List all QR codes owned by the authenticated workspace with pagination.

POST/api/v1/qrScope: qr:write

Create a new static or dynamic QR code with atomic destination binding.

GET/api/v1/qr/:idScope: qr:read

Retrieve full QR configuration, vector SVG download link, and current destination.

PATCH/api/v1/qr/:idScope: qr:write

Update destination URL of an existing dynamic QR code (consumes 1 dynamic update).

DELETE/api/v1/qr/:idScope: qr:write

Archive or delete a QR code and deactivate its shortlink routing.

POST/api/v1/qr/:id/pauseScope: qr:write

Temporarily pause redirects for a dynamic QR code.

POST/api/v1/qr/:id/resumeScope: qr:write

Reactivate redirects for a previously paused dynamic QR code.

POST/api/v1/qr/:id/duplicateScope: qr:write

Clone an existing QR code into an independent new record.

GET/api/v1/qr/:id/historyScope: qr:read

Audit trail of every destination change for this dynamic QR code.

POST/api/v1/qr/:id/history/restoreScope: qr:write

Restore destination URL to a previous version (consumes 1 dynamic update).

GET/api/v1/foldersScope: folders:read

List campaign folders for workspace organization.

POST/api/v1/foldersScope: folders:write

Create an organizational campaign folder.

GET/api/v1/folders/:idScope: folders:read

Get campaign folder details and contained QR count.

PATCH/api/v1/folders/:idScope: folders:write

Update folder name or theme color.

DELETE/api/v1/folders/:idScope: folders:write

Delete folder. Contained QR codes return to workspace root.

GET/api/v1/templatesScope: templates:read

List design templates available in workspace.

POST/api/v1/templatesScope: templates:write

Create a reusable design template.

GET/api/v1/templates/:idScope: templates:read

Get design template styling details.

PATCH/api/v1/templates/:idScope: templates:write

Update design template configuration.

DELETE/api/v1/templates/:idScope: templates:write

Delete custom design template.

GET/api/v1/catalogsScope: catalogs:read

List workspace digital catalogues and menus with section and item counts.

POST/api/v1/catalogsScope: catalogs:write

Create a new digital catalogue with vertical template configuration.

GET/api/v1/catalogs/:idScope: catalogs:read

Retrieve full hierarchical catalogue details, sections, items, and dynamic QR link.

PATCH/api/v1/catalogs/:idScope: catalogs:write

Update catalogue metadata, business name, or settings.

DELETE/api/v1/catalogs/:idScope: catalogs:write

Permanently remove a catalogue and all its items.

POST/api/v1/catalogs/:id/publishScope: catalogs:write

Publish catalogue to live public URL (/menu/:slug or /catalog/:slug).

POST/api/v1/catalogs/:id/unpublishScope: catalogs:write

Revert catalogue to draft status, taking it offline.

POST/api/v1/catalogs/:id/duplicateScope: catalogs:write

Deep-clone catalogue, categories, items, and variants to a draft copy.

GET/api/v1/catalogs/:id/sectionsScope: catalogs:read

List all categories/sections in a catalogue.

POST/api/v1/catalogs/:id/sectionsScope: catalogs:write

Create an organizational category or section in a catalogue.

GET/api/v1/catalogs/:id/itemsScope: catalogs:read

List all items in a catalogue across sections.

POST/api/v1/catalogs/:id/itemsScope: catalogs:write

Create item with base pricing, multi-variants (var_<uuid>), and add-ons.

PATCH/api/v1/catalogs/:id/items/:itemIdScope: catalogs:write

Update item pricing, description, badge, variants, or add-ons.

DELETE/api/v1/catalogs/:id/items/:itemIdScope: catalogs:write

Permanently delete an item from the catalogue.

POST/api/v1/catalogs/:id/items/:itemId/toggle-availabilityScope: catalogs:write

Instant 1-click in-stock vs sold-out stock toggle.

GET/api/v1/social-profilesScope: qr:read

List social biolink profiles in workspace.

POST/api/v1/social-profilesScope: qr:write

Create a new social profile biolink page.

GET/api/v1/social-profiles/:idScope: qr:read

Get social profile details and links.

PATCH/api/v1/social-profiles/:idScope: qr:write

Update social profile metadata and links.

DELETE/api/v1/social-profiles/:idScope: qr:write

Delete a social profile.

GET/api/v1/documentsScope: documents:read

List all uploaded PDF menus, brochures, and images in workspace.

POST/api/v1/documentsScope: documents:write

Register or upload a document to hosted campaign storage (deducts 2 credits).

GET/api/v1/documents/:idScope: documents:read

Retrieve document metadata, file size, and linked dynamic QR id.

DELETE/api/v1/documents/:idScope: documents:write

Purge document binary from hosted storage and remove QR links.

GET/api/v1/analytics/workspaceScope: analytics:read

Workspace aggregate scan telemetry across all campaigns.

GET/api/v1/analytics/folders/:idScope: analytics:read

Aggregate scan telemetry for QR codes within a specific folder.

GET/api/v1/analytics/:idScope: analytics:read

Retrieve 30-day scan telemetry, device/OS rollups, and city metrics.

GET/api/v1/analytics/:id/exportScope: analytics:read

Export privacy-preserving scan logs in CSV or JSON format.