{ "openapi": "3.1.0", "info": { "title": "QRFLOW.codes API", "version": "1.0.0", "summary": "Create QR codes, change where dynamic codes point, pull scan analytics, bulk-generate, manage webhooks.", "description": "Everything the QRFLOW.codes dashboard does, from your own code. Authenticate with a Business API key (`Authorization: Bearer qrf_live_…`, made on the Account page) or an OAuth token from https://qrflow.codes/oauth/authorize. Dynamic codes (url, phone, email, sms, location on paid plans) can be re-pointed after printing; their printed link uses the account's own domain when one is connected. Also available as an MCP server at https://qrflow.codes/mcp for Claude, ChatGPT, Cursor and Claude Code.", "termsOfService": "https://qrflow.codes/terms", "contact": { "name": "QRFLOW.codes", "url": "https://qrflow.codes/developers", "email": "hello@qrflow.codes" } }, "servers": [ { "url": "https://qrflow.codes/api/v1" } ], "externalDocs": { "url": "https://qrflow.codes/developers", "description": "Human-readable reference with curl examples" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "account" }, { "name": "catalog" }, { "name": "codes" }, { "name": "analytics" }, { "name": "domains" }, { "name": "webhooks" } ], "paths": { "/me": { "get": { "tags": [ "account" ], "summary": "Who the key belongs to, plan, feature flags and limits", "operationId": "getMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalog": { "get": { "tags": [ "catalog" ], "summary": "Every kind of code and the fields it needs", "operationId": "getCatalog", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEntry" } } } } } } } } } }, "/frames": { "get": { "tags": [ "catalog" ], "summary": "Frame ids and what each needs", "operationId": "getFrames", "security": [], "responses": { "200": { "description": "OK" } } } }, "/codes": { "get": { "tags": [ "codes" ], "summary": "List codes, newest first", "operationId": "listCodes", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "q", "in": "query", "description": "Search labels", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } } } } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks codes:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "codes" ], "summary": "Create a code", "operationId": "createCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCode" }, "examples": { "url": { "value": { "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents", "frame_style": "caption-below", "frame_caption": "Scan for menu" } }, "wifi": { "value": { "type": "wifi", "destination_data": { "ssid": "CafeGuest", "password": "latte-2026", "encryption": "WPA" }, "label": "Counter card" } }, "googleReview": { "value": { "type": "url", "destination_data": { "subtype": "googlereview", "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "label": "Receipt footer" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Code" } } } } } }, "400": { "description": "Invalid fields or destination, or the saved-codes ceiling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The plan does not include this kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/codes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "codes" ], "summary": "One code", "operationId": "getCode", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Code" } } } } } }, "404": { "description": "No such code in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "codes" ], "summary": "Change a code (send only what changes)", "operationId": "updateCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCode" }, "example": { "destination_data": { "url": "https://example.com/menu-fall" }, "slug": "menu" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Code" } } } } } }, "400": { "description": "Not dynamic, invalid name, no domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Link name already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "codes" ], "summary": "Delete a code and its scans", "operationId": "deleteCode", "responses": { "204": { "description": "Deleted" }, "404": { "description": "No such code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/codes/{id}/dynamic": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "codes" ], "summary": "Make a static code dynamic (re-render the image afterwards)", "operationId": "makeDynamic", "responses": { "200": { "description": "OK" }, "400": { "description": "This kind cannot be dynamic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Needs a paid plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/codes/{id}/image.png": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 256, "maximum": 2048, "default": 1024 } }, { "name": "exp", "in": "query", "description": "From png_download_url: signed access without a bearer", "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "schema": { "type": "string" } } ], "get": { "tags": [ "codes" ], "summary": "Plain PNG of the code (no frame or logo)", "operationId": "getImagePng", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "PNG", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "No bearer and no valid signed link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/codes/{id}/image.svg": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 256, "maximum": 4096, "default": 1024 } }, { "name": "exp", "in": "query", "description": "From svg_download_url: signed access without a bearer", "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "schema": { "type": "string" } } ], "get": { "tags": [ "codes" ], "summary": "Print-ready SVG with frame and colors", "operationId": "getImage", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "SVG", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/codes/{id}/scans": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "group", "in": "query", "schema": { "type": "string", "enum": [ "day", "device", "country", "city", "browser", "os", "referrer" ], "default": "day" } } ], "get": { "tags": [ "analytics" ], "summary": "Scan analytics (up to 92 days per request)", "operationId": "getScans", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scans" } } } } } } }, "/codes/bulk": { "post": { "tags": [ "codes" ], "summary": "Create many dynamic URL codes (up to 2,000 rows)", "operationId": "bulkCreate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rows" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "required": [ "destination" ], "properties": { "destination": { "type": "string", "format": "uri" }, "label": { "type": "string", "maxLength": 120 } } } }, "fg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" }, "bg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string" }, "reason": { "type": "string" } } } }, "remaining_this_month": { "type": "integer" } } } } } }, "400": { "description": "Over the monthly or per-request allowance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/domains": { "get": { "tags": [ "domains" ], "summary": "Connected link domains and the default", "operationId": "listDomains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_base": { "type": "string" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } } } } }, "/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "List webhooks", "operationId": "listWebhooks", "responses": { "200": { "description": "OK" } } }, "post": { "tags": [ "webhooks" ], "summary": "Create a webhook (secret returned once)", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "scan", "code.created", "code.updated", "code.deleted" ] } }, "description": { "type": "string", "maxLength": 120 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } } } } }, "402": { "description": "Needs Business", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "webhooks" ], "summary": "Send a signed test ping", "operationId": "testWebhook", "responses": { "200": { "description": "OK" } } }, "delete": { "tags": [ "webhooks" ], "summary": "Remove a webhook", "operationId": "deleteWebhook", "responses": { "204": { "description": "Deleted" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Business API key (qrf_live_…) or an OAuth access token." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://qrflow.codes/oauth/authorize", "tokenUrl": "https://qrflow.codes/api/oauth/token", "refreshUrl": "https://qrflow.codes/api/oauth/token", "scopes": { "profile": "Plan and email", "codes:read": "Read codes", "codes:write": "Create, edit, delete codes", "analytics:read": "Scan analytics", "domains:read": "Link domains", "webhooks:manage": "Webhooks" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "invalid_request", "invalid_token", "upgrade_required", "insufficient_scope", "not_found", "conflict", "rate_limited" ] }, "message": { "type": "string" } } }, "Me": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "premium", "business" ] }, "paid": { "type": "boolean" }, "features": { "type": "object", "additionalProperties": { "type": "boolean" } }, "limits": { "type": "object", "additionalProperties": { "type": [ "integer", "null" ] } }, "auth": { "type": "string", "enum": [ "oauth", "api_key" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "CatalogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" }, "requiresPlan": { "type": "string" }, "type": { "type": "string" }, "subtype": { "type": [ "string", "null" ] }, "dynamic": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "optional": { "type": "boolean" }, "type": { "type": "string" } } } } } }, "CreateCode": { "type": "object", "required": [ "type", "destination_data" ], "properties": { "type": { "type": "string", "enum": [ "url", "text", "wifi", "vcard", "email", "phone", "sms", "location" ] }, "destination_data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The fields for the type; add `subtype` (from /catalog) for a specific kind such as instagram or googlereview" }, "label": { "type": "string", "maxLength": 120 }, "fg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" }, "bg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" }, "frame_style": { "type": "string" }, "frame_caption": { "type": "string", "maxLength": 60 }, "frame_caption2": { "type": "string", "maxLength": 60 }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "UpdateCode": { "type": "object", "properties": { "destination_data": { "type": "object", "additionalProperties": { "type": "string" } }, "label": { "type": [ "string", "null" ] }, "paused": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "slug": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "fg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" }, "bg_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0F172A" }, "frame_style": { "type": "string" }, "frame_caption": { "type": [ "string", "null" ] }, "frame_caption2": { "type": [ "string", "null" ] } } }, "Code": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "kind_label": { "type": "string" }, "type": { "type": "string" }, "destination_data": { "type": "object" }, "destination": { "type": "string" }, "dynamic": { "type": "boolean" }, "dynamic_capable": { "type": "boolean" }, "short_code": { "type": "string" }, "short_url": { "type": "string", "description": "What to print for a dynamic code" }, "domain_id": { "type": [ "string", "null" ] }, "fg_color": { "type": "string" }, "bg_color": { "type": "string" }, "has_logo": { "type": "boolean" }, "frame_style": { "type": [ "string", "null" ] }, "frame_caption": { "type": [ "string", "null" ] }, "scans": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "manage_url": { "type": "string" }, "image_url": { "type": "string", "description": "Print-ready SVG; needs the Authorization header" }, "svg_download_url": { "type": "string", "description": "Same SVG through a signed link that works for 24 hours with no header" }, "png_download_url": { "type": "string", "description": "Plain PNG (no frame or logo) through a signed 24-hour link" }, "download_expires_at": { "type": "string", "format": "date-time" } } }, "Scans": { "type": "object", "properties": { "code_id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "group": { "type": "string" }, "total": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scans": { "type": "integer" } } } } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": "string" }, "status": { "type": "string" }, "active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "verified_at": { "type": [ "string", "null" ] }, "grace_until": { "type": [ "string", "null" ] } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "last_status": { "type": [ "integer", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "secret": { "type": "string", "description": "Only on create" } } } } }, "x-mcp": { "url": "https://qrflow.codes/mcp", "transport": "streamable-http", "auth": "oauth2 (dynamic client registration, PKCE S256) or a Business API key as bearer" }, "x-rate-limits": { "api_keys": "600 requests per minute per key", "bulk": "10,000 codes per month on Business, 2,000 per request" } }