{ "openapi": "3.1.0", "info": { "title": "Gookit Print Labels API", "version": "1.0.0", "description": "# Print Labels API\n\nOpen, platform-agnostic API for rendering print-ready **PDF** labels. Save a\ndata-driven template once, then print it over many rows of data (mail-merge)\nand poll for the finished PDF.\n\n## Get an API key\n\nEvery request is authenticated with a developer key.\n\n1. Open the developers portal → **Settings → API Keys**.\n2. **Create key** and copy the `gkdev_…` value — it is shown **once**.\n3. Send it on every request:\n\n```http\nAuthorization: Bearer gkdev_your_key\n```\n\n`GET /template-presets` and this spec are the only public endpoints meant\nfor API consumers; every other documented call returns `401` without a\nvalid key. (One undocumented public path exists — the Label Editor's\ninternal launch-code exchange — and is not part of this contract.)\n\n## Core concepts\n\n- **Template** — a label definition: `unit` (`mm`/`inch`), `width`/`height`,\n `type` (`ROLL` for one label, `SHEET`/`ROLL2Up` for a grid), and `elements`.\n- **Element content** — each element carries either a static `value` (baked\n into every copy) or a `field` (looked up per row). Set exactly one.\n- **Print job** — a stored template plus `items`. Each item has its own `data`\n (fills the template's `field`s) and a `quantity` (copies). This is the\n mail-merge.\n- **Asynchronous** — `POST /print` returns a `jobId` immediately; the PDF\n renders in the background. Poll `GET /print/{jobId}` until it is ready.\n\n## Start from a paper preset\n\nPrinting on branded stock (Avery, Dymo, Zebra, …)? Don't hand-type\ndimensions from a vendor PDF. The public catalog\n`GET /template-presets` returns verified geometry — label size, page,\nmargins, grid, gaps — for thousands of models, ready to drop into a\ntemplate. Or skip the JSON entirely: the **Label Editor** on the\ndevelopers portal creates a template from a preset plus one of 12 designed\nlayouts (price tag, QR, barcode-only, address, …), seeded as data-bound\nelements that preview with sample values. Deep-link it as\n`/editor?preset=&layout=`. Product layout ids:\n`classic-top-bottom`, `price-tag`, `image-left-text-right`,\n`qr-code-right`, `barcode-only`, `detailed-product`. Address layout ids:\n`classic-top-bottom-address`, `order-tag-address`,\n`image-left-text-right-address`, `qr-code-right-address`,\n`barcode-only-address`, `detailed-address`.\n\nSaved templates are **snapshots**: later catalog or layout updates never\nchange a template you've already stored.\n\n## Print your first labels\n\n### 1. Create a template\n\n`POST /templates` stores a reusable template and returns its `id`.\n\n```bash\ncurl -X POST https://YOUR_HOST/api/v1/templates \\\n -H \"Authorization: Bearer gkdev_your_key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My First Label\",\n \"template\": {\n \"unit\": \"mm\",\n \"type\": \"ROLL\",\n \"width\": 50,\n \"height\": 30,\n \"elements\": [\n { \"type\": \"text\", \"x\": 5, \"y\": 8, \"width\": 40, \"height\": 12, \"field\": \"name\", \"fontSize\": 10 }\n ]\n }\n }'\n```\n\nThe response includes an `id` — use it as the `templateId` below.\n\n### 2. Submit a print job\n\n`POST /print` renders the template once per item (times its `quantity`) and\nreturns a `jobId`.\n\n```bash\ncurl -X POST https://YOUR_HOST/api/v1/print \\\n -H \"Authorization: Bearer gkdev_your_key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"templateId\": \"PASTE_TEMPLATE_ID\",\n \"items\": [\n { \"quantity\": 2, \"data\": { \"name\": \"SKU-001\" } },\n { \"quantity\": 1, \"data\": { \"name\": \"SKU-002\" } }\n ]\n }'\n```\n\nThe response is `{ \"jobId\": \"…\" }` (HTTP `202`). This example prints three\nlabels into one PDF.\n\n### 3. Poll for the PDF\n\n`GET /print/{jobId}` reports the job's status. Repeat until `status` is\n`completed`; the PDF is then in `url`.\n\n```bash\ncurl https://YOUR_HOST/api/v1/print/PASTE_JOB_ID \\\n -H \"Authorization: Bearer gkdev_your_key\"\n```\n\n```json\n{ \"jobId\": \"…\", \"status\": \"completed\", \"url\": \"https://…/labels.pdf\" }\n```\n\n`status` moves `pending → processing → completed` (usually a second or two);\non failure it is `failed` with an `error`. The PDF `url` is **temporary\n(~24h)** — download it if you need to keep it.\n\n> Just want a quick single-label preview without polling? `POST /render` an\n> inline template to get a PNG back synchronously.\n\n## One-time Trial and Developer Pro\n\nNew eligible developer accounts receive **2,000 production labels once**.\nThe balance is shared by every `gkdev_` key on the account and never resets\nor renews. PDF and PNG production consume the same owner balance. After the\nbalance is exhausted, Developer Pro is **$29/month** for unlimited production\noutput while subscribed. Operational rate and job-size limits still apply.\nPro output does not consume Trial labels; unused Trial labels resume if Pro ends.\n\nEvery `POST /print` or `POST /render` call is a new production job. The server\ncreates its accounting identity automatically, so callers do not need a request\nid header. Insufficient Trial balance returns `402 developer_payment_required`\nbefore any partial output is rendered.\n\n## Rate limits\n\nLimits are enforced **per API key** — different keys never affect each other,\nso you can isolate workloads by minting a key each.\n\n- **1000 labels per minute** — the primary limit. Cost tracks the number of\n labels rendered, so `POST /print` charges its total copies (items ×\n `quantity`) and `POST /render` charges one. A single job can also hold at\n most 1000 labels.\n- **120 requests per minute** — a coarse flood guard across all endpoints\n (template CRUD, polling, MCP calls included).\n\nLabel-producing responses carry your remaining budget:\n\n```http\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 940\nX-RateLimit-Reset: 1710000000\n```\n\nOver either limit returns **`429`** with `{ \"error\": \"rate_limit_exceeded\", …}`\nand a `Retry-After` header (seconds until the window resets) — wait that long\nand retry. `GET /template-presets` and this spec are public and unmetered." }, "servers": [ { "url": "https://prod-bcm-api.barcodeman.app/api/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A developer API key (`gkdev_…`), minted from the developers portal's API Keys page. Send it as `Authorization: Bearer gkdev_…`." } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Print", "description": "Render stored templates into PDF labels." }, { "name": "Templates", "description": "Create and manage reusable templates." }, { "name": "Presets", "description": "Built-in paper/label-stock geometry (Avery, Dymo, …)." } ], "paths": { "/print": { "post": { "tags": [ "Print" ], "operationId": "createPrintJob", "summary": "Create a print job", "description": "Renders the supplied items against a stored template (referenced by `templateId`) and returns a job id. Rendering is asynchronous — poll GET /print/{jobId} for the PDF URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templateId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of a stored template (from POST /templates)." }, "items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "quantity": { "default": 1, "description": "Number of copies of this label.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "data": { "description": "Values for the template's `field` bindings.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "quantity" ], "additionalProperties": false, "description": "OpenPrintItem" } } }, "required": [ "templateId", "items" ], "additionalProperties": false, "description": "OpenPrintRequest" } } } }, "responses": { "202": { "description": "Job accepted and queued for rendering.", "headers": { "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobId": { "type": "string", "description": "Opaque job id; poll for status." } }, "required": [ "jobId" ], "additionalProperties": false, "description": "OpenPrintAccepted" } } } }, "400": { "description": "Invalid request (validation failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "402": { "description": "Payment required. Developer keys: the one-time Trial cannot cover the request and Developer Pro is inactive (body carries a machine `error` code + `upgradeUrl`). Shopify keys: the shop's API subscription is inactive (body is `{ ok, error: \"user_error\", message }`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "developer_payment_required" ] }, "message": { "type": "string" }, "available": { "type": "integer", "minimum": 0 }, "requested": { "type": "integer", "minimum": 1 }, "upgradeUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "error", "message", "available", "requested", "upgradeUrl" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } ] } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "413": { "description": "Request body too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } } }, "/print/{jobId}": { "get": { "tags": [ "Print" ], "operationId": "getPrintJob", "summary": "Get print job status", "description": "Returns the current status of a render job. When `status` is `completed`, `url` holds the PDF download link (valid ~24h).", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current job status.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Lifecycle state of the render job." }, "url": { "description": "PDF URL, present once status is `completed`.", "type": "string" }, "error": { "description": "Failure reason, present once status is `failed`.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "completedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "jobId", "status" ], "additionalProperties": false, "description": "OpenJobStatus" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Job not found or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } } }, "/render": { "post": { "tags": [ "Print" ], "operationId": "renderLabel", "summary": "Render a single label (synchronous)", "description": "Renders one label from an inline `template` (plus an optional `data` map for its field bindings) and returns a PNG (inline base64 data URI) plus the realized `layout` — no stored template, no job to poll, no PDF. The layout reports what the renderer actually drew (inked regions, post-shrink font size, truncation, barcode/QR fill ratio), which is what an editor preview or AI feedback loop needs. Produces exactly one label.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" }, "data": { "description": "Values for the template's `field` bindings, for this one label.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "template" ], "additionalProperties": false, "description": "OpenRenderRequest" } } } }, "responses": { "200": { "description": "The rendered single-label PNG + realized layout.", "headers": { "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "const": "png" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "PNG pixel width." }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "PNG pixel height." }, "dataUri": { "type": "string", "description": "`data:image/png;base64,...` — the PNG bytes inline." } }, "required": [ "format", "width", "height", "dataUri" ], "additionalProperties": false }, "layout": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "mm", "inch" ] }, "label": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "elements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "TEXT", "BARCODE", "QRCODE", "IMAGE" ] }, "box": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false, "description": "Requested element box, in `unit`." }, "ink": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false, "description": "Actually-inked region, in `unit`." }, "rotation": { "type": "number", "description": "Clockwise degrees (ink is reported pre-rotation)." }, "text": { "type": "object", "properties": { "fontSize": { "type": "number", "description": "Font size actually used (post auto-shrink), in pt." }, "lines": { "type": "array", "items": { "type": "string" }, "description": "Lines as wrapped and drawn." }, "truncated": { "type": "boolean", "description": "True when the box dropped content." } }, "required": [ "fontSize", "lines", "truncated" ], "additionalProperties": false }, "fillRatio": { "description": "BARCODE/QRCODE inked extent ÷ box (a QR quiet zone makes this < 1).", "type": "number" } }, "required": [ "id", "type", "box", "ink", "rotation" ], "additionalProperties": false, "description": "OpenRenderLayoutElement" } } }, "required": [ "unit", "label", "elements" ], "additionalProperties": false, "description": "OpenRenderLayout" } }, "required": [ "image", "layout" ], "additionalProperties": false, "description": "OpenRenderResponse" } } } }, "400": { "description": "Invalid request (validation failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "402": { "description": "Payment required. Developer keys: the one-time Trial cannot cover the request and Developer Pro is inactive (body carries a machine `error` code + `upgradeUrl`). Shopify keys: the shop's API subscription is inactive (body is `{ ok, error: \"user_error\", message }`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "developer_payment_required" ] }, "message": { "type": "string" }, "available": { "type": "integer", "minimum": 0 }, "requested": { "type": "integer", "minimum": 1 }, "upgradeUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "error", "message", "available", "requested", "upgradeUrl" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } ] } } } }, "413": { "description": "Request body too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } }, "502": { "description": "Rendering failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "504": { "description": "Rendering timed out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } } } } }, "/templates": { "post": { "tags": [ "Templates" ], "operationId": "createTemplate", "summary": "Save a template", "description": "Stores a reusable template. Print it later by referencing its id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" } }, "required": [ "name", "template" ], "additionalProperties": false, "description": "CreateOpenTemplate" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Server-assigned template id." }, "name": { "type": "string" }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "template", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "OpenStoredTemplate" } } } }, "400": { "description": "Invalid request (validation failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } }, "get": { "tags": [ "Templates" ], "operationId": "listTemplates", "summary": "List templates", "description": "Returns all stored templates for the caller.", "responses": { "200": { "description": "Stored templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Server-assigned template id." }, "name": { "type": "string" }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "template", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "OpenStoredTemplate" } } }, "required": [ "templates" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "operationId": "getTemplate", "summary": "Get a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "The stored template.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Server-assigned template id." }, "name": { "type": "string" }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "template", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "OpenStoredTemplate" } } } }, "400": { "description": "Invalid template id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } }, "patch": { "tags": [ "Templates" ], "operationId": "updateTemplate", "summary": "Update a template", "description": "Partial update — supply `name` and/or `template`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" } }, "additionalProperties": false, "description": "UpdateOpenTemplate" } } } }, "responses": { "200": { "description": "The updated template.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Server-assigned template id." }, "name": { "type": "string" }, "template": { "type": "object", "properties": { "unit": { "default": "mm", "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Label width, in `unit`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Label height, in `unit`." }, "type": { "default": "ROLL", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "elements": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "fontSize": { "type": "number", "exclusiveMinimum": 0 }, "fontFamily": { "type": "string" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "color": { "description": "Text fill, e.g. `#000000`.", "type": "string" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "barcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "barcodeType": { "description": "bwip-js symbology. Defaults to code128.", "type": "string", "enum": [ "upca", "ean13", "code128", "upca", "upce", "code39", "isbn", "ean8", "gs1-128" ] }, "showBarcodeText": { "type": "boolean" } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "qrcode" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "x": { "type": "number", "description": "Left offset, in the template unit." }, "y": { "type": "number", "description": "Top offset, in the template unit." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Width, in the template unit." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Height, in the template unit." }, "rotation": { "default": 0, "description": "Clockwise degrees.", "type": "number" }, "value": { "description": "Static content baked into every copy. For `image`, a URL.", "type": "string" }, "field": { "description": "Key looked up in each item's `data`. For `image`, a URL.", "type": "string" }, "stroke": { "description": "Border color, e.g. `#000000`. Requires `strokeWidth`.", "type": "string" }, "strokeWidth": { "description": "Border width, in the template unit. Requires `stroke`.", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "type", "x", "y", "width", "height", "rotation" ], "additionalProperties": false } ], "description": "OpenElement" } }, "page": { "description": "Paper size for sheet layouts.", "type": "object", "properties": { "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "margins": { "default": [ 0, 0, 0, 0 ], "description": "[left, top, right, bottom], in `unit`.", "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "description": "Labels per sheet. Defaults to 1×1.", "type": "object", "properties": { "col": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "row": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "description": "Spacing between labels on multi-up layouts.", "type": "object", "properties": { "column": { "type": "number", "minimum": 0 }, "line": { "type": "number", "minimum": 0 } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "unit", "width", "height", "type", "elements" ], "additionalProperties": false, "description": "OpenTemplate" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "template", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "OpenStoredTemplate" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "413": { "description": "Request body too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } }, "delete": { "tags": [ "Templates" ], "operationId": "deleteTemplate", "summary": "Delete a template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "204": { "description": "Template deleted." }, "400": { "description": "Invalid template id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "invalid_token" ] }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } }, "429": { "description": "Rate limit exceeded — too many requests (120/min per key) or too many labels (1000 labels/min per key). Body is `{ error, error_description }` (not `{ ok, message }`). Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Label budget for the current 60s window (labels/min, per key).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Labels remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) at which the current window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] } } } } } } }, "/template-presets": { "get": { "tags": [ "Presets" ], "operationId": "listTemplatePresets", "summary": "List paper/label-stock presets", "description": "Returns the built-in catalog of paper/label stocks (Avery, Dymo, …) as ready-to-use `OpenTemplate` geometry — label size, page size, margins, grid, and gaps, with a lowercase `unit`. Presets carry no elements: pick one for the layout, then add your own text/barcode/qrcode/image elements. Pass `?type=SHEET` (or `ROLL` / `ROLL2Up`) to narrow to one label kind — a paper-stock picker wants `SHEET`. Public — no API key required. To browse the catalog visually (and seed a designed layout on top), use the developers portal's Label Editor: `/editor?preset=&layout=`.", "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "description": "Filter to one label kind." } ], "responses": { "200": { "description": "The matching presets.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable preset id (e.g. `AVERY_66.675x25.4`)." }, "brand": { "type": "string", "description": "Manufacturer, e.g. `AVERY`." }, "model": { "type": "string", "description": "Display name, e.g. `AVERY 5160`." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Human labels, e.g. `[\"1\\\" x 2-5/8\\\"\", \"30 per Sheet\"]`." }, "type": { "type": "string", "enum": [ "ROLL", "SHEET", "ROLL2Up" ] }, "unit": { "type": "string", "enum": [ "mm", "inch" ] }, "width": { "type": "number", "description": "Label width, in `unit`." }, "height": { "type": "number", "description": "Label height, in `unit`." }, "page": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" }, "margins": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ], "description": "[left, top, right, bottom], in `unit`." } }, "required": [ "width", "height", "margins" ], "additionalProperties": false }, "grid": { "type": "object", "properties": { "col": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "row": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "col", "row" ], "additionalProperties": false }, "gap": { "type": "object", "properties": { "column": { "type": "number" }, "line": { "type": "number" } }, "required": [ "column", "line" ], "additionalProperties": false } }, "required": [ "id", "brand", "model", "tags", "type", "unit", "width", "height", "page", "grid", "gap" ], "additionalProperties": false, "description": "OpenTemplatePreset" } } }, "required": [ "presets" ], "additionalProperties": false, "description": "OpenTemplatePresets" } } } }, "400": { "description": "Invalid type filter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "enum": [ "user_error" ] }, "message": { "type": "string" } }, "required": [ "ok", "error", "message" ] } } } } } } } } }