{ "openapi": "3.1.0", "info": { "title": "ScanMosaic API", "version": "1.0.0", "description": "Create and manage dynamic QR codes, short links and barcodes, read their stats and render QR images. Business plan.", "contact": { "url": "https://scanmosaic.com/developers/" } }, "servers": [ { "url": "https://scanmosaic.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Items" }, { "name": "Images" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "The workspace, plan, limits and usage of this key", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/domains": { "get": { "tags": [ "Account" ], "operationId": "listDomains", "summary": "Custom domains of the workspace", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/items": { "get": { "tags": [ "Items" ], "operationId": "listItems", "summary": "List items, newest first", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "qr", "link", "barcode" ] }, "description": "Only this kind" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this content type" }, { "name": "campaign", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this campaign" }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this custom domain" }, { "name": "paused", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only paused or only live items" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search name, destination and alias" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Page size" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "A page of items", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Items" ], "operationId": "createItem", "summary": "Create a QR code, link or barcode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "qr", "link", "barcode" ], "default": "qr" }, "type": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }, "name": { "type": "string", "maxLength": 80 }, "dest": { "type": "string", "format": "uri" }, "alias": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{1,38}[A-Za-z0-9]$" }, "domain": { "type": [ "string", "null" ] }, "campaign": { "type": [ "string", "null" ], "maxLength": 60 }, "style": { "type": "object" }, "content": { "type": [ "object", "null" ] }, "rules": { "type": [ "object", "null" ] }, "og": { "type": [ "object", "null" ] }, "paused": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Item" } } } } } }, "403": { "description": "Plan limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/items/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Items" ], "operationId": "getItem", "summary": "Get an item", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Item" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Items" ], "operationId": "updateItem", "summary": "Update an item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "qr", "link", "barcode" ], "default": "qr" }, "type": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }, "name": { "type": "string", "maxLength": 80 }, "dest": { "type": "string", "format": "uri" }, "alias": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{1,38}[A-Za-z0-9]$" }, "domain": { "type": [ "string", "null" ] }, "campaign": { "type": [ "string", "null" ], "maxLength": 60 }, "style": { "type": "object" }, "content": { "type": [ "object", "null" ] }, "rules": { "type": [ "object", "null" ] }, "og": { "type": [ "object", "null" ] }, "paused": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Item" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Alias taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Items" ], "operationId": "deleteItem", "summary": "Delete an item and its stats", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "const": true } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/items/{id}/stats": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Items" ], "operationId": "getItemStats", "summary": "Scans or clicks over a period", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "description": "Days to include" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stats" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/qr": { "get": { "tags": [ "Images" ], "operationId": "renderQr", "summary": "Render a QR code image", "parameters": [ { "name": "data", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2953 }, "description": "" }, { "name": "item", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "png", "svg" ], "default": "png" }, "description": "" }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 64, "maximum": 4096 }, "description": "" }, { "name": "color", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "description": "" }, { "name": "background", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "description": "" }, { "name": "corner_color", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "description": "" }, { "name": "gradient_color", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "description": "" }, { "name": "transparent", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "" }, { "name": "error_correction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "description": "" }, { "name": "margin", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 8 }, "description": "" }, { "name": "dot_style", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "square", "dots", "rounded", "extra-rounded", "classy", "classy-rounded" ] }, "description": "" }, { "name": "corner_style", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "square", "extra-rounded", "dot" ] }, "description": "" }, { "name": "corner_dot_style", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "square", "dot" ] }, "description": "" }, { "name": "download", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[\\w.-]{1,80}$" }, "description": "" } ], "responses": { "200": { "description": "The image", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "image/png": { "schema": { "type": "string", "contentMediaType": "image/png" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "Item not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Images" ], "operationId": "renderQrPost", "summary": "Render a QR code image (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "maxLength": 2953 }, "item": { "type": "string" }, "format": { "type": "string", "enum": [ "png", "svg" ], "default": "png" }, "size": { "type": "integer", "minimum": 64, "maximum": 4096 }, "color": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "corner_color": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "gradient_color": { "type": "string", "pattern": "^#?[0-9a-fA-F]{6}$" }, "transparent": { "type": "boolean" }, "error_correction": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "margin": { "type": "integer", "minimum": 0, "maximum": 8 }, "dot_style": { "type": "string", "enum": [ "square", "dots", "rounded", "extra-rounded", "classy", "classy-rounded" ] }, "corner_style": { "type": "string", "enum": [ "square", "extra-rounded", "dot" ] }, "corner_dot_style": { "type": "string", "enum": [ "square", "dot" ] }, "download": { "type": "string", "pattern": "^[\\w.-]{1,80}$" } } } } } }, "responses": { "200": { "description": "The image", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" } }, "content": { "image/png": { "schema": { "type": "string", "contentMediaType": "image/png" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "Item not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "402": { "description": "Business plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from the dashboard (tsk_…)" } }, "headers": { "Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute" }, "Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute" }, "Reset": { "schema": { "type": "integer" }, "description": "Unix time the minute resets" } }, "responses": { "RateLimited": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/Reset" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "status" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" } }, "additionalProperties": true } } }, "Item": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "qr", "link", "barcode" ] }, "type": { "type": "string" }, "name": { "type": "string" }, "dest": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "alias": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "campaign": { "type": [ "string", "null" ] }, "content": { "type": [ "object", "null" ] }, "style": { "type": "object" }, "rules": { "type": [ "object", "null" ] }, "og": { "type": [ "object", "null" ] }, "paused": { "type": "boolean" }, "disabled": { "type": "boolean" }, "hits": { "type": "integer" }, "last_hit": { "type": [ "integer", "null" ] }, "created": { "type": "integer" }, "updated": { "type": "integer" } } }, "ItemList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Breakdown": { "type": "array", "items": { "type": "object", "properties": { "k": { "type": [ "string", "null" ] }, "n": { "type": "integer" } } } }, "Stats": { "type": "object", "properties": { "days": { "type": "integer" }, "total": { "type": "integer" }, "last_hit": { "type": [ "integer", "null" ] }, "inRange": { "type": "integer" }, "series": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string", "format": "date" }, { "type": "integer" } ] } }, "countries": { "$ref": "#/components/schemas/Breakdown" }, "devices": { "$ref": "#/components/schemas/Breakdown" }, "os": { "$ref": "#/components/schemas/Breakdown" }, "browsers": { "$ref": "#/components/schemas/Breakdown" }, "langs": { "$ref": "#/components/schemas/Breakdown" }, "rules": { "$ref": "#/components/schemas/Breakdown" } } }, "Domain": { "type": "object", "properties": { "host": { "type": "string" }, "verified": { "type": "boolean" }, "ready": { "type": "boolean" } } }, "Me": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "plan": { "type": "string" }, "key": { "type": "object", "properties": { "prefix": { "type": "string" }, "name": { "type": "string" } } }, "limits": { "type": "object" }, "usage": { "type": "object" }, "domains": { "type": "array", "items": { "type": "string" } }, "rate_limits": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_day": { "type": "integer" } } } } } } } }