QR Code API Guide

API Overview

QRForge provides a REST API that lets you generate QR codes programmatically from any application, script, or workflow. Whether you are building an e-commerce platform that generates QR codes for order tracking, a SaaS product that embeds QR code functionality, or an internal tool that automates QR creation for marketing campaigns, the API handles it. The interface is intentionally simple: one primary endpoint, JSON request and response bodies, and API key authentication. No SDKs required — any language that can make HTTP requests can use the QRForge API.

The API supports all the same QR code types available in the web interface: URLs, plain text, WiFi credentials, vCards, email addresses, phone numbers, and SMS. Both static and dynamic codes can be generated via API, and dynamic codes can be updated programmatically as well.

Authentication

All API requests require an API key passed in the X-Api-Key header. You can generate and manage API keys from your QRForge dashboard under Settings > API Keys. Each key can be independently revoked without affecting other keys, so you can use separate keys for different applications or environments.

curl -X POST https://qrforge.app/api/generate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: qrf_your_api_key" \
  -d '{"type": "url", "url": "https://example.com"}'

API keys follow the format qrf_ followed by a 32-character alphanumeric string. Store your keys securely — treat them like passwords. Never expose them in client-side JavaScript, public repositories, or browser-accessible code. If a key is compromised, revoke it immediately from the dashboard and generate a new one.

Authentication errors return HTTP 401 with a JSON body:

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked."
}

The Generate Endpoint

The primary endpoint for QR code generation is POST /api/generate. It accepts a JSON body describing the QR code you want to create and returns the generated QR code image or metadata depending on your request.

Request Format

All requests must include a Content-Type: application/json header. The request body must be valid JSON with at minimum a type field and the corresponding data field for that type.

URL QR Code

POST /api/generate
Content-Type: application/json
X-Api-Key: qrf_your_api_key

{
  "type": "url",
  "url": "https://example.com/landing-page",
  "dynamic": true,
  "fg_color": "#1a1a2e",
  "bg_color": "#ffffff"
}

WiFi QR Code

{
  "type": "wifi",
  "ssid": "GuestNetwork",
  "password": "welcome2024",
  "encryption": "WPA2",
  "hidden": false
}

vCard QR Code

{
  "type": "vcard",
  "first_name": "Jane",
  "last_name": "Smith",
  "organization": "Acme Corp",
  "email": "jane@acme.com",
  "phone": "+15551234567",
  "url": "https://acme.com"
}

Plain Text QR Code

{
  "type": "text",
  "text": "Your plain text content here"
}

Common Optional Fields

These fields can be included with any QR code type:

• dynamic (boolean) — Set to true to create a dynamic QR code that can be edited later. Default: false.
• fg_color (string) — Foreground color as a hex code. Default: #000000.
• bg_color (string) — Background color as a hex code. Default: #ffffff.
• size (integer) — Output image size in pixels (width and height). Range: 100–2000. Default: 400.
• error_correction (string) — Error correction level: L, M, Q, or H. Default: M.
• format (string) — Output format: png or svg. Default: png.

Response Format and Error Handling

Successful responses return HTTP 200 with the QR code image in the requested format. The response includes headers with metadata:

HTTP/1.1 200 OK
Content-Type: image/png
X-QR-Id: qr_abc123def456
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1712620800

If you created a dynamic code, the X-QR-Id header contains the unique identifier you will need to update the code later. Store this ID in your database.

Error responses return appropriate HTTP status codes with JSON bodies:

// 400 Bad Request — invalid parameters
{
  "error": "validation_error",
  "message": "The 'url' field must be a valid URL.",
  "field": "url"
}

// 429 Too Many Requests — rate limit exceeded
{
  "error": "rate_limit_exceeded",
  "message": "Daily API limit reached. Resets at 2026-04-09T00:00:00Z.",
  "retry_after": 3600
}

// 500 Internal Server Error — server-side issue
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please retry."
}

Always check the HTTP status code before processing the response body. Implement exponential backoff for 429 and 500 errors. The retry_after field in rate limit responses tells you how many seconds to wait before retrying.

Code Examples

Here are complete working examples in popular languages to get you started with QRForge's API.

JavaScript (Node.js)

const fs = require("fs");

async function generateQR() {
  const response = await fetch("https://qrforge.app/api/generate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.QRFORGE_API_KEY
    },
    body: JSON.stringify({
      type: "url",
      url: "https://example.com/product/12345",
      dynamic: true,
      fg_color: "#1a1a2e",
      size: 600,
      format: "png"
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error: ${error.message}`);
  }

  const qrId = response.headers.get("X-QR-Id");
  console.log("Dynamic QR ID:", qrId);

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("qr-code.png", buffer);
  console.log("QR code saved to qr-code.png");
}

generateQR();

Python

import requests
import os

response = requests.post(
    "https://qrforge.app/api/generate",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": os.environ["QRFORGE_API_KEY"]
    },
    json={
        "type": "url",
        "url": "https://example.com/product/12345",
        "dynamic": True,
        "fg_color": "#1a1a2e",
        "size": 600,
        "format": "png"
    }
)

response.raise_for_status()
qr_id = response.headers.get("X-QR-Id")
print(f"Dynamic QR ID: {qr_id}")

with open("qr-code.png", "wb") as f:
    f.write(response.content)
print("QR code saved to qr-code.png")

cURL (Bash)

curl -X POST https://qrforge.app/api/generate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $QRFORGE_API_KEY" \
  -d '{
    "type": "url",
    "url": "https://example.com/product/12345",
    "dynamic": true,
    "fg_color": "#1a1a2e"
  }' \
  -o qr-code.png -D -

API Best Practices

Follow these practices to build a reliable integration with QRForge's API:

• Store dynamic QR IDs. When you create a dynamic code, the X-QR-Id response header is your only way to update or manage that code later. Save it alongside the associated record in your database.
• Implement rate limit handling. Check the X-RateLimit-Remaining header on each response. When it approaches zero, queue requests or delay them. Never hammer the API after a 429 response — use exponential backoff.
• Use environment variables for API keys. Never hardcode API keys in source code. Use environment variables or a secrets manager. Rotate keys periodically and immediately revoke any key that may have been exposed.
• Request SVG for print, PNG for digital. SVG output scales infinitely without quality loss, making it ideal for print materials. PNG is more universally supported for digital embedding (emails, web pages, apps).
• Validate URLs before sending. The API will reject malformed URLs, but validating on your side saves a round trip and provides a better user experience.
• Handle errors gracefully. Network failures, rate limits, and server errors will happen. Your integration should handle them without crashing or leaving users in a broken state. Cache generated QR codes locally so a temporary API outage does not block your users.
• Use appropriate error correction. For QR codes that will be printed, use level Q or H. For digital-only use, level M is sufficient. Higher error correction levels make the QR pattern denser, so balance durability against scanability for small-sized codes.

Conclusion

QRForge's API is designed to make QR code generation as simple as any other API call in your stack. One endpoint, clear authentication, predictable responses, and generous rate limits. Whether you are generating a handful of codes for an internal tool or thousands for an e-commerce platform, the same API scales with you. Start with the code examples above, store your dynamic QR IDs, handle rate limits and errors gracefully, and you will have a reliable QR code integration running in under an hour. If you hit any issues or need higher rate limits, QRForge's developer support is available through the dashboard. The API documentation stays in sync with the live API, so the examples in this guide will always reflect the current interface.