Public REST API v1 • OpenAPI 3.1

Developer API Reference

Generate customized QR codes programmatically with zero API keys or user accounts. Protected by sensible rate limits to keep the service fast for everyone.

View OpenAPI 3.1 JSON Spec ↗

Endpoints Overview

Method	Endpoint	Auth	Description
GET	/api/v1/health	None	Service health and supported export formats.
POST	/api/v1/qr/validate	None	Validate payload & styling, returning QR version, byte count, and scan warnings.
POST	/api/v1/qr/preview	None	Render SVG preview markup plus matrix diagnostics.
POST	/api/v1/qr/generate	None	Generate QR in JSON with base64 `data_uri` (and optional `dynamic: true`).
POST	/api/v1/qr/export	None	Download raw binary file (`png`, `svg`, `pdf`, `eps`, `webp`, `jpeg`).
POST	/api/v1/links	None	Create an anonymous dynamic short link & receive one-time ownership token.
GET	/api/v1/links/{id}/stats	Bearer Token	Inspect destination and privacy-preserving scan statistics.
PATCH	/api/v1/links/{id}	Bearer Token	Update destination URL, active status, or rotate ownership token.
DELETE	/api/v1/links/{id}	Bearer Token	Delete dynamic QR code and analytics permanently.

Anonymous Rate Limits: General API: 60 req/min · Exports: 60 req/min · Dynamic Link Creation: 20 req/hour per client.

Quickstart Examples

1. cURL — Download Customized PNG

curl -X POST "https://qubiq.herculesprojects.net/api/v1/qr/export" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wifi",
    "data": { "ssid": "Studio-5G", "encryption": "WPA", "password": "SuperSecretPassword" },
    "design": {
      "ecc": "H",
      "size": 1000,
      "foreground_mode": "linear",
      "foreground_color": "#0f172a",
      "foreground_gradient_end": "#059669",
      "module_shape": "rounded",
      "finder_outer_shape": "rounded",
      "finder_inner_shape": "circle"
    },
    "format": "png"
  }' --output wifi-qr.png

2. JavaScript (Fetch ES2022+)

const response = await fetch('https://qubiq.herculesprojects.net/api/v1/qr/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'url',
    data: { url: 'https://example.com/welcome' },
    design: { ecc: 'M', size: 512, module_shape: 'circle' },
    format: 'svg'
  })
});

const { ok, data, error } = await response.json();
if (!ok) throw new Error(error.message);
document.querySelector('#qr-target').innerHTML = data.svg;

3. PHP 8.2+ (cURL)

<?php
$ch = curl_init('https://qubiq.herculesprojects.net/api/v1/qr/generate');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'vcard',
        'data' => [
            'first_name' => 'Elena',
            'last_name' => 'Rostova',
            'email' => 'elena@example.com',
            'mobile_phone' => '+14155550199',
        ],
        'format' => 'png',
    ]),
]);
$result = json_decode((string) curl_exec($ch), true);
curl_close($ch);
// Base64 PNG ready in $result['data']['data_uri']