QRCodeStack API

Public REST API for QRCodeStack — create, manage, and track dynamic QR codes programmatically. This repository contains the OpenAPI 3.0 specification and copy-pasteable code examples in curl, Node.js, and Python.

Why use the API

Use the API to:

• Bulk-create QR codes for print runs, packaging, or asset tracking (up to 500 per request)
• Update destinations without reprinting — dynamic QRs point to a redirect URL you control
• Pull scan analytics into your CRM or BI dashboard
• Integrate QR generation into product onboarding, marketing automation, or print workflows

The same platform 25,000+ businesses already use — exposed for your backend.

Quickstart

# 1. Sign up for a Pro or Advanced plan (the API isn't available on Starter)
#    https://qrcodestack.com/pricing
#
# 2. Generate an API key at https://qrcodestack.com/qr-dashboard/integrations
#    Keys are shown once — save them immediately.
#
# 3. Your first call:
curl https://qrcodestack.com/api/v1/me \
  -H "Authorization: Bearer qrs_YOUR_KEY"

Response:

{
  "success": true,
  "data": {
    "account_id": "...",
    "email": "you@example.com",
    "plan": "pro",
    "usage": {
      "dynamic_qr_count": 42,
      "dynamic_qr_limit": 250,
      "api_calls_this_month": 1834,
      "api_calls_monthly_limit": 5000
    }
  }
}

Authentication

Every request needs an Authorization: Bearer qrs_<your_key> header. Keys look like qrs_<64 hex chars> and are tied to a single user account.

You can manage keys (generate, list, revoke) from the dashboard: https://qrcodestack.com/qr-dashboard/integrations

Up to 5 active keys per account.

Plans and limits

Plan	Per-minute	Per-month	Bulk endpoint	Geolocation analytics
Starter	n/a	n/a	No	No
Pro	60	5,000	No	No
Advanced	600	100,000	Yes	Yes

Exceeding either window returns HTTP 429 with a Retry-After header.

Endpoints at a glance

Method	Path	Purpose	Plan
GET	/api/v1/me	Account + plan + usage	Pro+
POST	/api/v1/qr-codes	Create a dynamic QR	Pro+
GET	/api/v1/qr-codes	List QR codes (paginated)	Pro+
GET	/api/v1/qr-codes/{id}	Fetch one	Pro+
PATCH	/api/v1/qr-codes/{id}	Update destination / design	Pro+
DELETE	/api/v1/qr-codes/{id}	Soft-delete	Pro+
GET	/api/v1/qr-codes/{id}/image	Server-rendered PNG (cached 1h)	Pro+
GET	/api/v1/qr-codes/{id}/analytics	Aggregated scan stats	Pro+
GET	/api/v1/qr-codes/{id}/scans	Individual scan log	Pro+
POST	/api/v1/qr-codes/bulk	Create up to 500 in one call	Advanced only

Full reference: https://qrcodestack.com/api-docs

Examples

Copy-pasteable code for every endpoint, in three languages:

Scenario	curl	Node.js	Python
Account info	me.sh	me.js	me.py
Create a QR	create-qr.sh	create-qr.js	create-qr.py
List QRs (with pagination)	list-qrs.sh	list-qrs.js	list-qrs.py
Update destination	update-qr.sh	update-qr.js	update-qr.py
Get analytics	analytics.sh	analytics.js	analytics.py
Bulk create	bulk.sh	bulk.js	bulk.py

Every example reads your API key from the QRCS_API_KEY environment variable. Export it once:

export QRCS_API_KEY=qrs_your_key_here

OpenAPI specification

The full machine-readable spec is in this repo at openapi.yaml and mirrored at https://qrcodestack.com/openapi.yaml.

Generate a Postman collection, client SDKs, or your own docs from it:

# Postman (or use the GUI: Import → API → paste URL https://qrcodestack.com/openapi.yaml)
npx openapi-to-postmanv2 -s openapi.yaml -o qrcodestack.postman_collection.json -p

# TypeScript client
npx openapi-typescript openapi.yaml -o qrcodestack-api.d.ts

# Python client (using openapi-python-client)
openapi-python-client generate --path openapi.yaml

Error format

All errors are JSON:

{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Standard HTTP status codes:

Code	Meaning
200	Success
201	Created
204	Deleted (no body)
401	Missing or invalid API key
403	Key valid but plan doesn't allow this endpoint
404	Not found, or not owned by this account
422	Request validation failed (fields object lists per-field errors)
429	Rate-limited; check Retry-After header
5xx	Server-side error — retry with backoff

Versioning

Current version: v1. Breaking changes will ship under /v2 with a deprecation announcement. Non-breaking additions (new optional fields, new endpoints) land under v1 without notice.

Support

• Documentation: https://qrcodestack.com/api-docs
• Issues with this repo: open an issue on GitHub
• Account/billing/API help: support@qrcodestack.com or open a ticket from your dashboard

License

MIT — use this code freely in your own projects, commercial or otherwise.