{ "openapi": "3.1.0", "info": { "title": "GenQR.it API", "version": "1.0.0", "description": "API for generating high-quality QR codes with custom designs.\n\n# Getting Started\n\nWelcome to the GenQR.it API! Generate high-quality QR codes programmatically in seconds.\n\n## 1. Get your API Key\n\n1. Log in to your [Dashboard](https://genqr.it/dashboard).\n2. Navigate to the **API Keys** section.\n3. Click **Create New Key** to generate your unique secret key.\n\n## 2. Make your first request\n\nHere is the simplest way to generate a QR code for a website URL:\n\n```bash\ncurl -X POST https://genqr.it/api/qr/link \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: image/png\" \\\n -d '{\n \"payload\": {\n \"url\": \"https://krystalcode.com\"\n }\n }' \\\n --output qr.png\n```\n\n> **Note:** Replace `YOUR_API_KEY` with the key you generated in the dashboard.\n\n> **Tip:** The default response is `image/png`. To receive JSON instead, set `Accept: application/json`.\n\n## 3. Customize the design\n\nYou can easily customize colors, styles, and shapes. Here is an example with a blue rounded style:\n\n```bash\ncurl -X POST https://genqr.it/api/qr/link \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: image/png\" \\\n -d '{\n \"payload\": { \"url\": \"https://krystalcode.com\" },\n \"design\": {\n \"dots\": { \"style\": \"rounded\", \"color\": { \"mode\": \"single\", \"color\": \"#2563eb\" } },\n \"background\": { \"mode\": \"single\", \"color\": \"#ffffff\" }\n }\n }' \\\n --output custom-qr.png\n```\n\n## 4. Generate a WiFi QR Code\n\nGenerate a QR code that connects to a WiFi network when scanned:\n\n```bash\ncurl -X POST https://genqr.it/api/qr/wifi \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: image/png\" \\\n -d '{\n \"payload\": {\n \"ssid\": \"Krystalcode-WiFi\",\n \"encryption\": \"WPA\",\n \"password\": \"KrystalCode123\"\n }\n }' \\\n --output wifi-qr.png\n```\n\n## 5. Verify Readability\n\nYou can optionally ask the API to verify if the generated QR code is readable. This is useful for complex designs or small sizes.\n\n```bash\ncurl -X POST https://genqr.it/api/qr/link \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: image/png\" \\\n -d '{\n \"payload\": { \"url\": \"https://krystalcode.com\" },\n \"checkReadability\": true\n }' \\\n --output readable-qr.png\n```\n\n## 6. Pro Tip: Generate Payload from UI\n\nYou can design your QR code visually in [GenQR.it Homepage](https://genqr.it) and copy the exact JSON payload to use in your API requests.\n\n1. Create your QR code using the visual editor.\n2. Click the **Copy Payload** button (available when logged in).\n3. Paste the JSON directly into your API request body.\n\nExplore the endpoints below for the full API reference and all available options.", "contact": { "name": "API Support", "email": "support@krystalcode.com" } }, "tags": [ { "name": "QR Generation", "description": "Endpoints for generating various types of QR codes" }, { "name": "Assets", "description": "Endpoints for retrieving assets like logos" } ], "servers": [ { "url": "https://genqr.it", "description": "Production server" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "parameters": { "AcceptHeader": { "name": "Accept", "in": "header", "schema": { "type": "string", "enum": ["image/png", "image/jpeg", "image/svg+xml", "application/json"], "default": "image/png" } } }, "responses": { "QrGenerated": { "description": "Generated QR Code", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object" } } } }, "QrInvalidInput": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "QrValidationFailed": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "QrRateLimitExceeded": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "QrRateLimitOrQuotaExceeded": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBodies": { "QrLinkRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrLinkPayload" } }, "required": ["payload"] } ] }, "examples": { "logoUrl": { "summary": "Logo from an HTTPS URL", "value": { "payload": { "url": "https://krystalcode.com" }, "design": { "logo": { "source": "url", "url": "https://krystalcode.com/logo.png" }, "dots": { "style": "rounded", "color": { "mode": "single", "color": "#111827" } }, "cornersSquare": { "style": "extra-rounded", "color": { "mode": "single", "color": "#111827" } }, "cornersDot": { "style": "dot", "color": { "mode": "single", "color": "#111827" } }, "background": { "mode": "single", "color": "#ffffff" }, "advanced": { "image": { "hideBackgroundDots": true, "imageSize": 0.35, "margin": 0 }, "qr": { "errorCorrectionLevel": "H" } } } } }, "logoFile": { "summary": "Inline logo as a data URL", "value": { "payload": { "url": "https://krystalcode.com" }, "design": { "logo": { "source": "file", "file": { "name": "logo.png", "type": "image/png", "size": 105, "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAG0lEQVR4nGNg+E8hZBg1gGE0DP6PhgHDcAgDADG1/hDIxpN7AAAAAElFTkSuQmCC" } }, "dots": { "style": "rounded", "color": { "mode": "single", "color": "#111827" } }, "cornersSquare": { "style": "extra-rounded", "color": { "mode": "single", "color": "#111827" } }, "cornersDot": { "style": "dot", "color": { "mode": "single", "color": "#111827" } }, "background": { "mode": "single", "color": "#ffffff" }, "advanced": { "image": { "hideBackgroundDots": true, "imageSize": 0.35, "margin": 0 }, "qr": { "errorCorrectionLevel": "H" } } } } }, "gradientDesign": { "summary": "Dots with a linear gradient", "value": { "payload": { "url": "https://krystalcode.com" }, "design": { "dots": { "style": "extra-rounded", "color": { "mode": "gradient", "gradient": { "type": "linear", "startColor": "#0f172a", "endColor": "#1d4ed8", "rotation": 0 } } }, "cornersSquare": { "style": "extra-rounded", "color": { "mode": "single", "color": "#0f172a" } }, "cornersDot": { "style": "dot", "color": { "mode": "single", "color": "#1d4ed8" } }, "background": { "mode": "single", "color": "#ffffff" } } } } } } } }, "QrTextRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrTextPayload" } }, "required": ["payload"] } ] } } } }, "QrEmailRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrEmailPayload" } }, "required": ["payload"] } ] } } } }, "QrSmsRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrSmsPayload" } }, "required": ["payload"] } ] } } } }, "QrCallRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrCallPayload" } }, "required": ["payload"] } ] } } } }, "QrWhatsappRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrWhatsappPayload" } }, "required": ["payload"] } ] } } } }, "QrWifiRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrWifiPayload" } }, "required": ["payload"] } ] } } } }, "QrVcardRequest": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/QrRequestBase" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/QrVcardPayload" } }, "required": ["payload"] } ] } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object" } } }, "required": ["error"] }, "QrRequestBase": { "type": "object", "properties": { "design": { "$ref": "#/components/schemas/QrDesign" }, "checkReadability": { "type": "boolean", "default": false, "description": "If true, performs a readability check on the generated QR code. Defaults to false for performance." } } }, "QrDesign": { "type": "object", "properties": { "logo": { "allOf": [ { "$ref": "#/components/schemas/QrLogo" } ], "default": { "source": "file", "url": "", "file": null } }, "width": { "type": "integer", "minimum": 128, "maximum": 2048, "default": 640 }, "height": { "type": "integer", "minimum": 128, "maximum": 2048, "default": 640 }, "dots": { "type": "object", "properties": { "style": { "type": "string", "enum": ["square", "dots", "rounded", "classy", "classy-rounded", "extra-rounded"], "default": "square" }, "color": { "allOf": [ { "$ref": "#/components/schemas/QrColor" } ], "default": { "mode": "single", "color": "#0f172a" } } }, "required": ["style", "color"] }, "cornersSquare": { "type": "object", "properties": { "style": { "type": "string", "enum": ["square", "dots", "rounded", "classy", "classy-rounded", "extra-rounded", "dot"], "default": "square" }, "color": { "allOf": [ { "$ref": "#/components/schemas/QrColor" } ], "default": { "mode": "single", "color": "#0f172a" } } }, "required": ["style", "color"] }, "cornersDot": { "type": "object", "properties": { "style": { "type": "string", "enum": ["square", "dots", "rounded", "classy", "classy-rounded", "extra-rounded", "dot"], "default": "square" }, "color": { "allOf": [ { "$ref": "#/components/schemas/QrColor" } ], "default": { "mode": "single", "color": "#0f172a" } } }, "required": ["style", "color"] }, "background": { "allOf": [ { "$ref": "#/components/schemas/QrBackgroundColor" } ], "default": { "mode": "single", "color": "#ffffff" } }, "advanced": { "type": "object", "properties": { "image": { "type": "object", "properties": { "hideBackgroundDots": { "type": "boolean", "default": true }, "imageSize": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.6 }, "margin": { "type": "number", "minimum": 0, "maximum": 0.5, "default": 0 } } }, "qr": { "type": "object", "properties": { "typeNumber": { "type": ["integer", "null"], "minimum": 1, "maximum": 40, "default": null }, "mode": { "type": "string", "enum": ["Byte", "Numeric", "Alphanumeric", "Kanji"], "default": "Byte" }, "errorCorrectionLevel": { "type": "string", "enum": ["L", "M", "Q", "H"], "default": "M" } } } } } } }, "QrLogo": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "url", "enum": ["url"], "default": "url" }, "url": { "type": "string", "format": "uri", "default": "https://krystalcode.com/logo.png", "description": "HTTPS logo URL. Required when source is url." }, "file": { "type": "null", "default": null, "description": "Must be null when source is url." } }, "required": ["source", "url"] }, { "type": "object", "properties": { "source": { "type": "string", "const": "file", "enum": ["file"], "default": "file" }, "url": { "type": "string", "default": "", "description": "Optional and ignored when source is file." }, "file": { "type": ["object", "null"], "description": "Inline logo payload as a base64 data URL. Not a file path.", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml"], "default": "image/png", "example": "image/png", "description": "MIME type of the inline logo file. Must match the dataUrl header and the file signature." }, "size": { "type": "integer" }, "dataUrl": { "type": "string", "pattern": "^data:[\\w/+.-]+;base64,[A-Za-z0-9+/=]+$", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAG0lEQVR4nGNg+E8hZBg1gGE0DP6PhgHDcAgDADG1/hDIxpN7AAAAAElFTkSuQmCC" } }, "required": ["name", "type", "size", "dataUrl"] } }, "required": ["source"] } ] }, "QrColor": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "single", "default": "single" }, "color": { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "default": "#0f172a" } }, "required": ["mode", "color"] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gradient", "default": "gradient" }, "gradient": { "type": "object", "properties": { "type": { "type": "string", "enum": ["linear", "radial"], "default": "linear" }, "startColor": { "type": "string", "default": "#0f172a" }, "endColor": { "type": "string", "default": "#2563eb" }, "rotation": { "type": "integer", "minimum": 0, "maximum": 359, "default": 0 } }, "required": ["type", "startColor", "endColor", "rotation"] } }, "required": ["mode", "gradient"] } ] }, "QrBackgroundColor": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "single", "default": "single" }, "color": { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "default": "#ffffff" } }, "required": ["mode", "color"] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gradient", "default": "gradient" }, "gradient": { "type": "object", "properties": { "type": { "type": "string", "enum": ["linear", "radial"], "default": "linear" }, "startColor": { "type": "string", "default": "#0f172a" }, "endColor": { "type": "string", "default": "#2563eb" }, "rotation": { "type": "integer", "minimum": 0, "maximum": 359, "default": 0 } }, "required": ["type", "startColor", "endColor", "rotation"] } }, "required": ["mode", "gradient"] } ] }, "QrLinkPayload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL that the QR code should open", "default": "https://krystalcode.com" } }, "required": ["url"] }, "QrTextPayload": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4096, "default": "Hello from KrystalCode" } }, "required": ["text"] }, "QrEmailPayload": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "default": "hello@krystalcode.com" }, "subject": { "type": "string", "maxLength": 512, "default": "Hello from KrystalCode" }, "message": { "type": "string", "maxLength": 2048, "default": "Let's talk about your next QR project." } }, "required": ["email"] }, "QrSmsPayload": { "type": "object", "properties": { "countryCode": { "type": "string", "maxLength": 5, "default": "39" }, "phoneNumber": { "type": "string", "maxLength": 32, "default": "3331234567" }, "message": { "type": "string", "maxLength": 2048, "default": "Hello from KrystalCode" } }, "required": ["phoneNumber"] }, "QrCallPayload": { "type": "object", "properties": { "countryCode": { "type": "string", "maxLength": 5, "default": "39" }, "phoneNumber": { "type": "string", "maxLength": 32, "default": "3331234567" } }, "required": ["phoneNumber"] }, "QrWhatsappPayload": { "type": "object", "properties": { "countryCode": { "type": "string", "maxLength": 5, "default": "39" }, "phoneNumber": { "type": "string", "maxLength": 32, "default": "3331234567" }, "message": { "type": "string", "maxLength": 2048, "default": "Hello from KrystalCode" } }, "required": ["phoneNumber"] }, "QrWifiPayload": { "type": "object", "properties": { "ssid": { "type": "string", "maxLength": 128, "default": "KrystalCode-WiFi" }, "encryption": { "type": "string", "enum": ["WEP", "WPA", ""], "default": "WPA" }, "password": { "type": "string", "maxLength": 128, "default": "KrystalCode123" } }, "required": ["ssid"] }, "QrVcardPayload": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 128, "default": "Salvatore" }, "lastName": { "type": "string", "maxLength": 128, "default": "Criniti" }, "phoneNumber": { "type": "string", "maxLength": 32, "default": "+390212345678" }, "mobile": { "type": "string", "maxLength": 32, "default": "+393331234567" }, "email": { "type": "string", "maxLength": 4096, "default": "hello@krystalcode.com" }, "website": { "type": "string", "maxLength": 2048, "default": "https://krystalcode.com" }, "company": { "type": "string", "maxLength": 128, "default": "KrystalCode" }, "jobTitle": { "type": "string", "maxLength": 128, "default": "Founder" }, "fax": { "type": "string", "maxLength": 32, "default": "+390212345679" }, "address": { "type": "string", "maxLength": 256, "default": "Via Roma 1" }, "city": { "type": "string", "maxLength": 128, "default": "Milan" }, "postCode": { "type": "string", "maxLength": 128, "default": "20100" }, "country": { "type": "string", "maxLength": 128, "default": "Italy" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/qr-logo": { "get": { "summary": "Resolve Logo URL", "operationId": "resolveLogo", "tags": ["Assets"], "description": "Resolves a logo URL to a proxied, safe version for embedding in QR codes.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "example": "https://krystalcode.com/logo.png" } ], "responses": { "200": { "description": "Logo image", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/qr/link": { "post": { "summary": "Generate Link QR Code", "description": "Generate a QR code that opens a URL when scanned.", "operationId": "generateLinkQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrLinkRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "400": { "$ref": "#/components/responses/QrInvalidInput" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitOrQuotaExceeded" } } } }, "/api/qr/text": { "post": { "summary": "Generate Text QR Code", "description": "Generate a QR code that displays plain text when scanned.", "operationId": "generateTextQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrTextRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/email": { "post": { "summary": "Generate Email QR Code", "description": "Generate a QR code that drafts an email when scanned.", "operationId": "generateEmailQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrEmailRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/sms": { "post": { "summary": "Generate SMS QR Code", "description": "Generate a QR code that drafts an SMS message when scanned.", "operationId": "generateSmsQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrSmsRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/call": { "post": { "summary": "Generate Call QR Code", "description": "Generate a QR code that initiates a phone call when scanned.", "operationId": "generateCallQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrCallRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/whatsapp": { "post": { "summary": "Generate WhatsApp QR Code", "description": "Generate a QR code that opens a WhatsApp chat when scanned.", "operationId": "generateWhatsappQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrWhatsappRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/wifi": { "post": { "summary": "Generate WiFi QR Code", "description": "Generate a QR code that connects to a WiFi network when scanned.", "operationId": "generateWifiQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrWifiRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } }, "/api/qr/vcard": { "post": { "summary": "Generate VCard QR Code", "description": "Generate a QR code that saves a contact (vCard) when scanned.", "operationId": "generateVcardQr", "tags": ["QR Generation"], "parameters": [{ "$ref": "#/components/parameters/AcceptHeader" }], "requestBody": { "$ref": "#/components/requestBodies/QrVcardRequest" }, "responses": { "200": { "$ref": "#/components/responses/QrGenerated" }, "422": { "$ref": "#/components/responses/QrValidationFailed" }, "429": { "$ref": "#/components/responses/QrRateLimitExceeded" } } } } } }