API & Developers

API access, tokens, OpenAPI docs, and programmatic QR creation.

Quantum SmartQR provides a REST API for creating and managing QR codes and for reading analytics programmatically. This page describes the Developers screen and the key API concepts a new integration developer usually needs first.

Developers page - sections and buttons

The Developers page is your hub for API access in environments where developer links are enabled. If you do not see it in your workspace, use this guide plus the OpenAPI docs directly. You will see:

  • Open API Docs - Opens the OpenAPI reference in a new tab. There you can explore endpoints, request and response schemas, and try requests when your environment allows it.
  • API Base - The root URL for API requests in your environment. Use the value shown in the app or provided by your onboarding contact.
  • OpenAPI - Use the public schema for Postman, client generation, and implementation planning.
  • Quickstart - Sample requests for common tasks like creating QR codes and fetching analytics.
  • Auth guide - How to authenticate with workspace API tokens.
  • Postman - Download the collection and environment for API testing.

API tokens

Create API tokens from the Developers page when developer links are enabled. Workspace admins can also review and revoke API keys from Settings -> Integrations. Use Developers when you need the full token-creation flow and scope guidance. Each token is scoped to your workspace and can have these production scopes, depending on your plan:

  • qr:read - List and read QR codes.
  • qr:write - Create, update, and delete QR codes.
  • analytics:read - Read stats and scan events.
  • analytics:export - Export analytics when included in your plan.
  • webhooks:manage - Manage webhook settings when included in your plan.
  • smart_redirect:advanced - Manage advanced Smart Redirect rules when included in your plan.
  • bulk:operations - Use bulk operations when included in your plan.
  • audit:read - Read audit records when included in your plan.

Use the token in the Authorization: Bearer <token> header. Keep tokens secret. See Developers for token creation and Workspace & Settings for workspace administration.

Always create tokens with explicit scopes. Unscoped bearer tokens are rejected on scoped API endpoints, including QR management, workspace webhooks, batch operations, exports, Smart Redirect, assets, and audit logs.

If you created an older token before scopes were required, rotate it from Developers and choose the smallest scope set needed for that integration. A read-only reporting job usually needs qr:read and analytics:read. A QR creation job usually needs qr:write. A full release-smoke token needs qr:write, analytics:read, and webhooks:manage.

Public endpoint catalog

The OpenAPI reference is the source of truth, but most integrations start with these endpoints:

  • GET /api/qr-codes?limit=25&offset=0 - list QR codes in the workspace.
  • POST /api/qr-codes - create a managed QR code.
  • GET /api/qr-codes/{code_id} - read a QR code.
  • PATCH /api/qr-codes/{code_id} - update QR metadata, destination, or style.
  • DELETE /api/qr-codes/{code_id} - delete a QR code with a token that includes qr:write.
  • GET /api/qr-codes/{code_id}/stats - read current scan totals.
  • GET /api/qr-codes/{code_id}/analytics - read chart-ready analytics.
  • GET /api/qr-codes/{code_id}/events - read paginated scan events.
  • GET /api/analytics/summary - read dashboard-level analytics for the workspace.
  • GET /api/qr-codes/{code_id}/export - export scan events when your token includes analytics:export.
  • POST /api/assets/presign and POST /api/assets/{asset_id}/finalize - upload reusable logo assets.
  • GET /api/assets and GET /api/assets/{asset_id} - list and retrieve workspace assets.
  • POST /api/batch/preview, POST /api/batch/jobs, GET /api/batch/jobs, and GET /api/batch/jobs/{job_id} - validate CSV rows and manage batch QR creation jobs.
  • GET /api/batch/jobs/{job_id}/download - download completed batch QR files.
  • GET, PUT, and POST /test under /api/enterprise/integrations/webhook - read, save, and test the workspace webhook.
  • PUT /api/qr-codes/{code_id}/smart-redirect and DELETE /api/qr-codes/{code_id}/smart-redirect - manage advanced Smart Redirect rules.
  • GET /api/account/audit-events - read workspace audit events when your token includes audit:read.

For safe retries on create/update calls, send an Idempotency-Key header with a unique value per logical operation. Reusing the same key lets the API avoid duplicate side effects when a client times out and retries.

Common API tasks

  • Create a QR code - POST /api/qr-codes with target_url, optional friendly_name, and optional style_json or webhook_url for advanced use cases.
  • List QR codes - GET /api/qr-codes?limit=25&offset=0 with limit/offset pagination.
  • Get stats - GET /api/qr-codes/{code_id}/stats for total scans and last scan time.
  • Get analytics - GET /api/qr-codes/{code_id}/analytics?days=30 for trend and summary.
  • Get scan events - GET /api/qr-codes/{code_id}/events for the raw scan list.
  • Run a batch import - preview CSV rows with POST /api/batch/preview, create with POST /api/batch/jobs, poll GET /api/batch/jobs/{job_id}, then download when ready.
  • Manage workspace webhooks - use GET/PUT /api/enterprise/integrations/webhook and POST /api/enterprise/integrations/webhook/test.
  • Upload a logo asset - presign with POST /api/assets/presign, upload to the returned URL, then finalize with POST /api/assets/{asset_id}/finalize.

Use the OpenAPI (Swagger) docs for the full schema. For advanced QR creation, the important part is the Model tab for style_json.

Advanced QR create payloads

If you want custom shapes, gradients, frame styles, logos, or Smart Redirect configuration, you are still using POST /api/qr-codes. The advanced fields live in style_json.

Common style_json fields include:

  • module_shape - QR module style such as square, rounded, dot, diamond, hexagon, star, or shield.
  • eye_shape - Finder or eye style such as square, rounded, target, gear, or flower.
  • colors.fg and colors.bg - Foreground and background colors.
  • colors.gradient - Optional gradient object with type, direction, colors, and apply_to.
  • frame.shape - Surrounding frame such as square, rounded, circle, badge, or tag.
  • logo.asset_id - Reference to a workspace logo asset you uploaded earlier.
  • smart_redirect - Rule-based redirect configuration.

Example create payload:

{
  "target_url": "https://example.com/campaign",
  "friendly_name": "Spring launch",
  "style_json": {
    "module_shape": "rounded",
    "eye_shape": "target",
    "colors": {
      "fg": "#0f172a",
      "bg": "#ffffff",
      "gradient": {
        "type": "linear",
        "direction": "diagonal-tl-br",
        "colors": ["#0f172a", "#2563eb"],
        "apply_to": "modules"
      }
    },
    "frame": {
      "shape": "badge",
      "padding_modules": 4
    }
  }
}

If you need to inspect the exact supported keys, use the OpenAPI Model view for style_json. That is more useful than the example body alone.

Analytics responses

There are three common analytics endpoint shapes developers usually need:

  • GET /api/qr-codes/{code_id}/stats - the current QR plus high-level metadata such as total_scans, last_scan_time, activation fields, style_json, tags, and webhook_url.
  • GET /api/qr-codes/{code_id}/analytics?days=30 - aggregate analytics for charts and dashboards. This includes summary, per_day, scans_by_hour, top_referrers, and whether geo_enabled is active on the current plan.
  • GET /api/qr-codes/{code_id}/events?days=30&page=1&page_size=25 - paginated recent scan events. Each row includes scan time, device type, browser, OS, geo fields, and bot confidence.

Use /stats when you want the current QR record, /analytics for charts and rollups, and /events for raw event tables or exports.

Pagination names are endpoint-specific: QR lists use limit and offset; scan events use page and page_size.

Webhooks: per QR vs workspace

There are two webhook concepts, and they are easy to confuse:

  • Per-QR webhook - send webhook_url on POST /api/qr-codes or PATCH /api/qr-codes/{code_id}. This applies to that QR code only.
  • Workspace webhook - configure a default integration webhook for the whole workspace through Settings -> Integrations, or via GET/PUT /api/enterprise/integrations/webhook.

When both are configured, the per-QR webhook_url takes precedence for that code. Webhooks are plan-gated, so Starter workspaces may see webhook controls disabled or unavailable.

Scan webhook deliveries are JSON payloads that include fields such as code_id, customer_id, scan_time, target_url, resolved_target_url, device_type, device_browser, device_os, and approximate geo fields. Scanner identifiers such as raw IP address, user agent, and visitor_id are not included. If a workspace signing secret is configured, SmartQR also adds signature headers so you can verify the payload on receipt.

Logo assets and asset IDs

Logo uploads are a separate asset workflow from QR creation itself.

  • Upload path - use POST /api/assets/presign, upload the file to the returned SAS URL, then call POST /api/assets/{asset_id}/finalize.
  • Direct upload option - some clients can also use POST /api/assets with multipart form data.
  • List and maintain - use GET /api/assets?type=logo&state=library to list logos, then move unused ones to trash or restore them later.
  • Use in a QR - reference the uploaded asset with style_json.logo.asset_id or logo_asset_id when creating or updating the QR.

The important concept is that QR create does not upload image bytes directly. It references an existing logo asset by ID.

Rate limits

API requests are rate-limited per token and per IP. If you receive a 429 response, wait before retrying. Check response headers for rate limit info such as X-RateLimit-Remaining-IP, X-RateLimit-Remaining-Tenant, and X-RateLimit-Remaining-Token when available.

Was this helpful? More help topics