{ "openapi": "3.0.3", "info": { "title": "ZPLCraft saved-label API", "version": "2026-09-16", "description": "Public reference for the existing label-api Edge Function. Access requires active Pro entitlement (including Team membership or an admin grant). Keys only access personal labels owned by their account; Team-space labels are excluded. Maximum five active keys. Full keys have labels:list, labels:read, render and print; historical/render-only keys have render. Keep credentials server-side. Each account and each key has a 60-unit/minute budget. Authenticated attempts cost 1 unit; valid print jobs cost 5 + number of record objects total. Retry-After is in seconds. Request body: 65536 bytes. Rendering bounds: stored/output ZPL 2097152 JavaScript string units, 10000 commands; PNG/PDF 16000000 pixels and 12000 dots per dimension, 33554432 response bytes, 15-second provider timeout. There is no arbitrary-source upload or remote printer dispatch endpoint.", "contact": { "url": "https://label-designer.app/api-docs" } }, "servers": [ { "url": "https://{project}.supabase.co/functions/v1/label-api", "description": "Replace project with your deployment project reference; copy the exact base URL from Dashboard \u2192 API & Integrations.", "variables": { "project": { "default": "YOUR_PROJECT" } } } ], "security": [ { "ApiKey": [] }, { "BearerKey": [] } ], "paths": { "/labels": { "get": { "operationId": "listLabels", "summary": "List personal saved labels", "description": "List personal saved labels", "tags": [ "Saved labels" ], "x-required-scope": "labels:list", "responses": { "200": { "description": "Metadata ordered by updated_at descending, then id descending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelList" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ] } }, "/labels/{label_id}": { "parameters": [ { "name": "label_id", "in": "path", "required": true, "description": "UUID (versions 1\u20135) of a personal label owned by this API-key account.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "get": { "operationId": "getLabel", "summary": "Read a saved label", "description": "Read a saved label", "tags": [ "Saved labels" ], "x-required-scope": "labels:read", "responses": { "200": { "description": "Metadata, dynamic_tokens and untouched stored zpl inside data. The editor canvas document is not exposed; nonempty include is rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } } }, "post": { "operationId": "renderLabelAlias", "summary": "Render a saved label (compatibility alias)", "description": "Render a saved label (compatibility alias)", "tags": [ "Saved labels" ], "x-required-scope": "render", "responses": { "200": { "description": "Substituted ZPL text or PNG/PDF bytes. PNG/PDF uses the external Labelary renderer.", "headers": { "X-ZPLCraft-Output-Format": { "description": "Saved fidelity mode; the response container does not change this mode.", "schema": { "type": "string", "enum": [ "bitmap", "vector" ] } } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "^XA^FO20,20^A0N,30,30^FDA-77^FS^XZ" }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderRequest" } } } } } }, "/labels/{label_id}/zpl": { "parameters": [ { "name": "label_id", "in": "path", "required": true, "description": "UUID (versions 1\u20135) of a personal label owned by this API-key account.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "get": { "operationId": "getStoredZpl", "summary": "Download stored ZPL", "description": "Download stored ZPL", "tags": [ "Saved labels" ], "x-required-scope": "labels:read", "responses": { "200": { "description": "Untouched saved ZPL. No variable substitution.", "headers": { "X-ZPLCraft-Output-Format": { "description": "Saved fidelity mode; the response container does not change this mode.", "schema": { "type": "string", "enum": [ "bitmap", "vector" ] } } }, "content": { "application/vnd.zebra-zpl": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } } } }, "/labels/{label_id}/render": { "parameters": [ { "name": "label_id", "in": "path", "required": true, "description": "UUID (versions 1\u20135) of a personal label owned by this API-key account.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "post": { "operationId": "renderLabel", "summary": "Render variable ZPL, PNG or PDF", "description": "Save designs as Vector ZPL for API-time variables. Dynamic Bitmap ZPL returns 409. PNG/PDF sends substituted ZPL to Labelary. UTC clock tokens DATE, TIME, DATETIME and fixed COUNTER seeds are substituted automatically.", "tags": [ "Saved labels" ], "x-required-scope": "render", "responses": { "200": { "description": "Substituted ZPL text or PNG/PDF bytes. PNG/PDF uses the external Labelary renderer.", "headers": { "X-ZPLCraft-Output-Format": { "description": "Saved fidelity mode; the response container does not change this mode.", "schema": { "type": "string", "enum": [ "bitmap", "vector" ] } } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "^XA^FO20,20^A0N,30,30^FDA-77^FS^XZ" }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderRequest" } } } } } }, "/labels/{label_id}/print": { "parameters": [ { "name": "label_id", "in": "path", "required": true, "description": "UUID (versions 1\u20135) of a personal label owned by this API-key account.", "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" } } ], "post": { "operationId": "createPrintJob", "summary": "Build a bounded print-ready ZPL job", "description": "Build a bounded print-ready ZPL job", "tags": [ "Saved labels" ], "x-required-scope": "print", "responses": { "200": { "description": "Concatenated ZPL, ready for your existing printer transport. This operation does not dispatch to a printer.", "headers": { "X-ZPLCraft-Output-Format": { "description": "Saved fidelity mode; the response container does not change this mode.", "schema": { "type": "string", "enum": [ "bitmap", "vector" ] } }, "Content-Disposition": { "schema": { "type": "string" }, "example": "attachment; filename=\"shelf-label.zpl\"" }, "X-ZPLCraft-Label-Count": { "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "content": { "application/vnd.zebra-zpl": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintRequest" } } } } } }, "/": { "post": { "operationId": "legacyAction", "summary": "Render or build a print-ready job (compatibility form)", "description": "Render or build a print-ready job (compatibility form)", "tags": [ "Saved labels" ], "x-required-scope": "render or print according to action", "responses": { "200": { "description": "Render or print response according to action and format.", "headers": { "X-ZPLCraft-Output-Format": { "description": "Saved fidelity mode; the response container does not change this mode.", "schema": { "type": "string", "enum": [ "bitmap", "vector" ] } }, "Content-Disposition": { "schema": { "type": "string" }, "example": "attachment; filename=\"shelf-label.zpl\"" }, "X-ZPLCraft-Label-Count": { "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "^XA^FO20,20^A0N,30,30^FDA-77^FS^XZ" }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.zebra-zpl": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyRequest" } } } } }, "get": { "operationId": "legacyRead", "summary": "List or read labels (compatibility form)", "description": "List or read labels (compatibility form)", "tags": [ "Saved labels" ], "x-required-scope": "labels:list or labels:read according to label_id", "responses": { "200": { "description": "List when label_id is absent/empty; label detail when provided.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LabelList" }, { "$ref": "#/components/schemas/LabelResponse" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "parameters": [ { "name": "label_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "zplc_ followed by 48 lowercase hexadecimal characters." }, "BearerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ZPLCraft API key", "description": "Alternative Authorization: Bearer zplc_\u2026 header. If both are present, x-api-key takes precedence." } }, "schemas": { "Variables": { "type": "object", "maxProperties": 50, "description": "Recommended values are strings (up to 1000 characters). The server trims names, rejects blank/duplicate/prototype names, and converts other JSON values to strings; null becomes empty text. Names have at most 80 characters. Matching is case-insensitive. Unmatched text placeholders stay unchanged; unmatched barcode placeholders return 422. Saved field transforms run before substitution.", "additionalProperties": { "type": "string", "maxLength": 1000 }, "example": { "sku": "A-77", "price": "9.99" } }, "Label": { "type": "object", "required": [ "id", "name", "width", "height", "dpi", "revision", "created_at", "updated_at", "output_format" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "width": { "type": "number", "description": "Saved width in millimetres." }, "height": { "type": "number", "description": "Saved height in millimetres." }, "dpi": { "type": "number" }, "revision": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "output_format": { "type": "string", "enum": [ "bitmap", "vector" ] } } }, "LabelDetail": { "allOf": [ { "$ref": "#/components/schemas/Label" }, { "type": "object", "required": [ "dynamic_tokens", "zpl" ], "properties": { "dynamic_tokens": { "type": "array", "items": { "type": "string" } }, "zpl": { "type": "string", "nullable": true, "description": "Exact saved command stream, with no substitution. Null when no ZPL was saved." } } } ] }, "LabelResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LabelDetail" } } }, "LabelList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "pagination": { "type": "object", "required": [ "limit", "offset", "total", "next_offset" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "nullable": true }, "next_offset": { "type": "integer", "nullable": true, "description": "Do not request an offset above 10000 even if next_offset exceeds that cap." } } } } }, "RenderRequest": { "type": "object", "properties": { "variables": { "$ref": "#/components/schemas/Variables" }, "format": { "type": "string", "enum": [ "zpl", "png", "pdf" ], "default": "zpl" } }, "example": { "variables": { "sku": "A-77" }, "format": "zpl" } }, "PrintRequest": { "type": "object", "description": "Use variables or records, not both. At most 25 record objects; records.length \u00d7 copies must be \u2264100. No records means one record. Costs 5 + record count rate-limit units in total, including the initial authenticated unit. Copies repeat rendered labels; COUNTER does not increment across records/copies.", "properties": { "variables": { "$ref": "#/components/schemas/Variables" }, "records": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Variables" } }, "copies": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, "not": { "required": [ "variables", "records" ] }, "example": { "records": [ { "sku": "A-77" }, { "sku": "A-78" } ], "copies": 2 } }, "LegacyRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RenderRequest" }, { "type": "object", "required": [ "label_id" ], "properties": { "label_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "render" ], "default": "render" } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/PrintRequest" }, { "type": "object", "required": [ "label_id", "action" ], "properties": { "label_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "print" ] } } } ] } ] }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "output_format": { "type": "string" }, "required_scope": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "symbology", "template", "value", "reason" ], "properties": { "symbology": { "type": "string" }, "template": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" } } } } } } }, "responses": { "Error400": { "description": "Invalid JSON, label UUID, pagination, format, variables or print-job parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Missing, malformed or unknown API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Active Pro entitlement is required, or the key lacks the required scope (required_scope is included).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Route or personal label was not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error405": { "description": "The method is not supported on this route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error408": { "description": "Reading the request body timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "No saved ZPL, invalid saved dimensions, or dynamic Bitmap ZPL. For the last case code is bitmap_dynamic_output_incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "Request body, stored/rendered ZPL, render dimensions or barcode work exceeds the bounded limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "Invalid substituted barcode content (fields), or saved field transforms failed (code: field_transform_invalid).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Account/key work budget or deployment-wide credential guard exceeded. Wait Retry-After seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry.", "schema": { "type": "integer", "minimum": 1 } } } }, "Error500": { "description": "A database lookup, entitlement or account/key limiter check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error502": { "description": "Labelary renderer failed or returned an invalid/oversized artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Durable deployment-wide credential limiter unavailable; fails closed before key lookup. Wait Retry-After seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retry.", "schema": { "type": "integer", "minimum": 1 } } } }, "Error504": { "description": "The Labelary render request or response timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "tags": [ { "name": "Saved labels", "description": "Every operation is scoped to labels.user_id of the key account, with team_id null." } ] }