QRForge API Overview

QRForge delivers a high‑performance, enterprise‑class API designed for mission‑critical QR code generation, lifecycle management, and secure data operations at scale.
This documentation provides a comprehensive technical foundation covering capabilities, authentication, versioning, and operational standards required for robust platform integration.

---

Base URL

All production API traffic must be directed to the following fully managed, secure endpoint:

https://api.qrforge.link/v1/

All endpoints must include the API version as part of the URL path.

---

Versioning Strategy

QRForge follows a semantic, URL‑based versioning model:

• Major version → Breaking changes (/v1/, /v2/)
• Minor version → Additive, non-breaking improvements
• Patch version → Internal fixes, invisible to API consumers

The Dev Portal always documents the current stable version (v1).

---

Authentication

QRForge uses API Key authentication.

Include your API key in every request using the x-api-key header:

x-api-key: YOUR_API_KEY_HERE

Keys are scoped to:

• The owning QRForge Workspace
• The allowed permissions (read-only, write, analytics)
• The assigned environment (production, staging, dev)

Never expose API keys in client-side applications.

---

Standard Request Format

All API requests should be made using:

• HTTPS (TLS 1.2+ required)
• JSON request bodies
• Standard UTF-8 encoding

Example:

POST /v1/qr-codes
Content-Type: application/json
x-api-key: YOUR_KEY

{
  "label": "Customer QR",
  "type": "url",
  "redirect_url": "https://example.com"
}

---

Standard Response Envelope

QRForge APIs use a consistent response envelope:

Success

{
  "ok": true,
  "version": "2025-11-14-v1",
  "request_id": "UUID",
  "data": { }
}

Error

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "UUID",
  "code": "invalid_request",
  "message": "Missing required field: redirect_url"
}

---

Rate Limiting

QRForge enforces enterprise-level rate limits:

Plan	Requests / Minute	Burst Capacity
Pro	600	2×
Agency	2,000	3×
Enterprise	Custom	Custom

If a request exceeds limits:

• HTTP 429 Too Many Requests
• Retry‑After header is included

---

Core API Modules

QRForge exposes several logical modules under /v1/:

📌 QR Codes

Create, update, archive, and retrieve dynamic QR codes with full lifecycle control and enterprise‑grade metadata handling.

Endpoints include:

• POST /qr-codes
• GET /qr-codes/{id}
• GET /qr-codes/find?slug={slug}
• PATCH /qr-codes/{id} (includes archiving via status="archived")
• GET /qr-codes (listing with filtering and pagination)

📌 Projects

Organize QR codes under enterprise workspaces or sub-projects.

Endpoints include:

• GET /projects
• POST /projects

📌 Analytics

Analytics API endpoints will be introduced in API v2.
Currently not available in v1.

---

Error Codes

Common error codes:

Code	Meaning
invalid_request	Malformed input
unauthorized	Missing/invalid API key
forbidden	No permission
not_found	Resource does not exist
rate_limit_minute	Minute‑level rate limit exceeded
rate_limit_day	Daily quota exceeded
server_error	Unexpected system error

---

SDKs & Tools

Official SDKs (coming soon):

• JavaScript (Q1 release)
• Python (Q2 release)
• Go (Q2 release)
• C# (Q3 release)

A public OpenAPI 3.1 spec is maintained at:

/static/openapi/qrforge-v1.yaml

---

Next Steps

Proceed to:

👉 Authentication
👉 QR Codes API
👉 Projects

---

For operational or integration assistance, contact the QRForge Engineering Support Team at support@qrforge.link.