{ "openapi": "3.1.0", "info": { "title": "LinkToQR API", "version": "1.0.0", "description": "Create trackable and basic QR codes, change where they point, download their images, and read scan data. Included with the Business plan. Rate limited to 120 requests per 60 seconds per key. Server-to-server only: no CORS headers are sent, so a browser cannot call this API.\n\nParameters are validated strictly. A numeric parameter that is not a whole number, or is negative, answers 400 and names the field; a whole number outside the documented range is clamped to it. Enum parameters are rejected rather than defaulted.", "contact": { "url": "https://www.linktoqr.co/contact-us/" } }, "servers": [ { "url": "https://www.linktoqr.co/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from the dashboard." } }, "schemas": { "QrCode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "dynamic", "static" ] }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "content_type": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "short_url": { "type": [ "string", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "folder_id": { "type": [ "string", "null" ], "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } }, "design": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "classic", "rounded", "dots", "classy", "indigo", "emerald", "midnight", "sunset" ] }, "fg": { "type": "string" }, "bg": { "type": "string" }, "frame": { "type": "string", "enum": [ "none", "border", "scan-bottom", "scan-top" ] }, "frame_text": { "type": "string" } } }, "image": { "type": "object", "properties": { "png": { "type": "string", "format": "uri" }, "svg": { "type": "string", "format": "uri" } } }, "scan_count": { "type": "integer" }, "last_scanned_at": { "type": [ "string", "null" ], "format": "date-time" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "password_protected": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "svg": { "type": "string", "description": "Only present when ?include=svg was passed." } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string", "format": "uuid" } } } } } } }, "paths": { "/me/": { "get": { "summary": "Account, plan usage and key scopes", "operationId": "getMe", "responses": { "200": { "description": "Account summary." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/": { "get": { "summary": "List QR codes", "operationId": "listQrCodes", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "dynamic", "static" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "archived" ] } }, { "name": "folder_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Matches the code name." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "oldest", "scans" ], "default": "newest" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of codes." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a QR code or short link", "operationId": "createQrCode", "parameters": [ { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "svg" ] }, "description": "Return the rendered SVG in the response body." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dynamic", "static" ], "default": "dynamic" }, "content_type": { "type": "string", "enum": [ "link", "vcard", "event", "email", "sms", "call", "text", "wifi" ], "default": "link", "description": "Basic codes only, apart from 'link'." }, "name": { "type": "string", "maxLength": 160 }, "destination_url": { "type": "string" }, "alias": { "type": "string", "description": "Trackable codes only. Generated when omitted." }, "folder_id": { "type": [ "string", "null" ], "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } }, "design": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "classic", "rounded", "dots", "classy", "indigo", "emerald", "midnight", "sunset" ] }, "fg": { "type": "string" }, "bg": { "type": "string" }, "frame": { "type": "string", "enum": [ "none", "border", "scan-bottom", "scan-top" ] }, "frameText": { "type": "string" } } }, "short_link": { "type": "boolean", "description": "Create a short link instead of a QR code." }, "vcard_first": { "type": "string" }, "vcard_last": { "type": "string" }, "vcard_org": { "type": "string" }, "vcard_title": { "type": "string" }, "vcard_phone": { "type": "string" }, "vcard_email": { "type": "string" }, "vcard_url": { "type": "string" }, "event_title": { "type": "string" }, "event_location": { "type": "string" }, "event_description": { "type": "string" }, "event_start_date": { "type": "string" }, "event_start_time": { "type": "string" }, "event_end_date": { "type": "string" }, "event_end_time": { "type": "string" }, "email": { "type": "string" }, "email_subject": { "type": "string" }, "email_body": { "type": "string" }, "phone": { "type": "string" }, "sms_message": { "type": "string" }, "text": { "type": "string" }, "wifi_ssid": { "type": "string" }, "wifi_password": { "type": "string" }, "wifi_security": { "type": "string" } } } } } }, "responses": { "201": { "description": "The created code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QrCode" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That alias is already taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/bulk/": { "post": { "summary": "Create many trackable codes at once", "operationId": "bulkCreateQrCodes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codes" ], "properties": { "codes": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "destination_url" ], "properties": { "destination_url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "alias": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "short_links": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created and failed row counts." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{id}/": { "get": { "summary": "Retrieve a QR code", "operationId": "getQrCode", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "svg" ] } } ], "responses": { "200": { "description": "The code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QrCode" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a QR code", "operationId": "updateQrCode", "description": "Only the fields you send are changed. Aliases cannot be changed: the alias is what is already printed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "destination_url": { "type": "string", "format": "uri", "description": "Trackable codes only." }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "folder_id": { "type": [ "string", "null" ], "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } }, "design": { "type": "object" } } } } } }, "responses": { "200": { "description": "The updated code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QrCode" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The change is not allowed in the code's current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a QR code", "operationId": "deleteQrCode", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{id}/image/": { "get": { "summary": "Download the code image", "operationId": "getQrCodeImage", "description": "A plain, contrast-corrected rendering. Frames and logos are applied in the dashboard, not here.\n\nThe bytes are deterministic for a given set of parameters, so every response carries a strong `ETag`. Send it back as `If-None-Match` and an unchanged image answers `304` with no body. `Cache-Control` is `private, max-age=0, must-revalidate`: a design edit, or removing a custom domain, changes what a code should look like, so a stale cached image is never served.\n\nUnknown query parameters are rejected rather than ignored. A non-numeric `size` or `margin` is a 400; a numeric value outside the range is clamped to it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "An ETag from a previous response. Matching answers 304." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "png", "svg" ], "default": "png" } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 64, "maximum": 2048, "default": 512 }, "description": "Pixel width. Out-of-range values are clamped." }, { "name": "margin", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10, "default": 2 }, "description": "Quiet zone in modules. The QR specification calls for 4, and 4 is recommended for anything printed — below it some scanners fail, especially on busy backgrounds. The default is 2 for backward compatibility and is planned to become 4 in the next API version." }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "L", "M", "Q", "H" ], "default": "M" }, "description": "Higher levels survive more damage but hold less data." }, { "name": "fg", "in": "query", "schema": { "type": "string" }, "description": "Hex colour override (#rrggbb) for this render only. Contrast is still corrected." }, { "name": "bg", "in": "query", "schema": { "type": "string" }, "description": "Hex colour override (#rrggbb) for this render only. Contrast is still corrected." } ], "responses": { "200": { "description": "The image.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Strong validator over the content and every parameter." }, "Content-Disposition": { "schema": { "type": "string" }, "description": "inline, so the URL can be used in an tag." }, "X-QR-Contrast-Adjusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true when the colours had to be changed to keep the code scannable." } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "304": { "description": "The If-None-Match ETag matched. No body." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use GET, HEAD or OPTIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The code's content is larger than a QR code can hold at the requested error correction level. The message names the size and the limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Rendering failed or exceeded its time limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "summary": "Image headers without the body", "operationId": "headQrCodeImage", "description": "Identical to GET, including Content-Length and ETag, with no body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Headers only." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "options": { "summary": "Allowed methods", "operationId": "optionsQrCodeImage", "description": "Returns 204 with an Allow header. No CORS headers are sent — this API is server-to-server.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Allow: GET, HEAD, OPTIONS." } } } }, "/qr-codes/{id}/scans/": { "get": { "summary": "Scan totals and breakdowns for one code", "operationId": "getQrCodeScans", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "description": "Clamped to the plan's analytics history." } ], "responses": { "200": { "description": "Aggregated scan data." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/qr-codes/{id}/activity/": { "get": { "summary": "Individual scan events for one code", "operationId": "getQrCodeActivity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "description": "Clamped to the plan's analytics history." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Scan events, newest first." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/": { "get": { "summary": "Account-wide scan reporting", "operationId": "getAccountAnalytics", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "description": "Clamped to the plan's analytics history." } ], "responses": { "200": { "description": "Account totals, breakdowns and top codes." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/folders/": { "get": { "summary": "List folders", "operationId": "listFolders", "responses": { "200": { "description": "Folders on this account." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/templates/": { "get": { "summary": "Design templates, frames, content types and image options", "operationId": "listTemplates", "responses": { "200": { "description": "The vocabulary this API accepts." }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, plan, or account standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }