{ "openapi": "3.1.1", "info": { "title": "Label Sheet Maker with CSV Mail Merge API", "version": "1.0.0", "summary": "Address labels, name badges and product labels from a CSV, for any sheet layout.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://printshoplabelsheet.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Address labels, name badges and product labels from a CSV, for any sheet layout.", "description": "Fill a sheet of labels from CSV rows with a {Column} template: address labels, name badges, jar and product labels. Use a generic sheet layout or enter your own geometry, skip labels already used, add a QR code or barcode per label and print a true-size PDF.\n\nMethodology:\n- CSV is read after RFC 4180 (quoted fields, doubled quotes, line breaks inside quotes); comma, semicolon or tab is detected from the header line. Each row fills the {Column} placeholders of the template.\n- Label n sits at left + column × horizontal pitch, top + row × vertical pitch, filled row by row; “start at” skips used positions on the first sheet. Presets are generic dimension sets (no brand or product numbers).\n- Text is wrapped to the label width and reduced in 10 % steps until it fits; labels whose text still does not fit are counted as overflow. A QR code takes up to 45 % of the width; barcodes sit at the bottom.\n\nPrinters shift paper by up to a millimetre or two. Print one test page on plain paper, hold it against a label sheet and adjust the margins before printing on labels.", "tags": [ "apps" ], "x-mcp-tool": "printshop_label_sheet", "x-owner-app": "printshop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintshopLabelSheetInput" }, "examples": { "example1": { "summary": "Address labels on a 3 × 8 sheet", "value": {} }, "example2": { "summary": "Jar labels with a QR code, starting at label 4", "value": { "sheet": "a4-3x7-63x38", "template": "{Product}\nBest before {Date}", "csv": "Product,Date,Code\nPlum jam,2028-06,https://example.com/jam/plum\nApricot jam,2028-07,https://example.com/jam/apricot", "code": "qr", "codeTemplate": "{Code}", "fontSize": 4.5, "align": "start", "startAt": 4, "outlines": true } }, "example3": { "summary": "Custom 2 × 3 badges", "value": { "sheet": "custom", "cols": 2, "rows": 3, "labelW": 90, "labelH": 80, "top": 18.5, "left": 12, "pitchX": 96, "pitchY": 88, "template": "{Name}\n{Team}", "csv": "Name,Team\nAlex,Design\nSam,Support\nKim,Finance", "align": "middle", "fontSize": 8, "outlines": true } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintshopLabelSheetResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "PrintshopLabelSheetInput": { "type": "object", "additionalProperties": false, "properties": { "sheet": { "title": "Sheet layout", "type": "string", "enum": [ "a4-3x8-70x37", "a4-3x7-63x38", "a4-2x7-99x38", "a4-2x4-99x68", "a4-4x10-48x25", "a4-5x13-38x21", "a4-2x5-90x54", "a4-4x6-round40", "letter-3x10", "letter-2x10", "letter-2x5", "letter-4x20", "letter-3x4-round2", "custom" ], "default": "a4-3x8-70x37" }, "paper": { "title": "Paper size (custom layout)", "type": "string", "enum": [ "a3", "a4", "a5", "a6", "b5", "letter", "legal", "tabloid", "halfletter" ], "default": "a4" }, "cols": { "title": "Columns (custom)", "type": "integer", "minimum": 1, "maximum": 30, "default": 3 }, "rows": { "title": "Rows (custom)", "type": "integer", "minimum": 1, "maximum": 30, "default": 8 }, "labelW": { "title": "Label width (mm, custom)", "type": "number", "minimum": 5, "maximum": 1200, "default": 70 }, "labelH": { "title": "Label height (mm, custom)", "type": "number", "minimum": 5, "maximum": 1200, "default": 37 }, "top": { "title": "Top margin (mm, custom)", "type": "number", "minimum": 0, "maximum": 600, "default": 0.5 }, "left": { "title": "Left margin (mm, custom)", "type": "number", "minimum": 0, "maximum": 600, "default": 0 }, "pitchX": { "title": "Horizontal pitch (mm, custom)", "description": "Distance from the left edge of one label to the left edge of the next.", "type": "number", "minimum": 5, "maximum": 1200, "default": 70 }, "pitchY": { "title": "Vertical pitch (mm, custom)", "type": "number", "minimum": 5, "maximum": 1200, "default": 37 }, "template": { "title": "Label text", "description": "Use {Column} for values from the CSV header.", "type": "string", "maxLength": 2000, "default": "{Name}\n{Street}\n{Postcode} {City}" }, "csv": { "title": "CSV data (first row = column names)", "type": "string", "maxLength": 200000, "default": "Name,Street,Postcode,City\nAda Example,1 Sample Road,12345,Exampletown\nBo Sample,22 Test Lane,54321,Demoville" }, "code": { "title": "Code on each label", "type": "string", "enum": [ "none", "qr", "code128", "ean13" ], "default": "none" }, "codeTemplate": { "title": "Code content", "description": "Template for the code, for example {SKU} or https://example.com/{Id}.", "type": "string", "maxLength": 500, "default": "" }, "fontSize": { "title": "Font size (mm)", "description": "The text shrinks automatically when it does not fit.", "type": "number", "minimum": 1.5, "maximum": 20, "default": 3.6 }, "align": { "title": "Alignment", "type": "string", "enum": [ "start", "middle", "end" ], "default": "start" }, "startAt": { "title": "Start at label number", "description": "Skip labels already used on a partly used sheet (counted row by row).", "type": "integer", "minimum": 1, "maximum": 900, "default": 1 }, "copies": { "title": "Copies of each label", "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "outlines": { "title": "Draw label outlines", "description": "Useful for a test print on plain paper; usually off for real label sheets.", "type": "boolean", "default": false } }, "required": [] }, "PrintshopLabelSheetResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "labels", "records", "perSheet", "overflow", "missingFields", "codeErrors", "sheetLabel", "pages", "pageWidthMm", "pageHeightMm", "warnings", "files", "openInApp" ], "properties": { "labels": { "type": "integer" }, "records": { "type": "integer" }, "perSheet": { "type": "integer" }, "overflow": { "type": "integer" }, "missingFields": { "type": "array", "items": { "type": "string" } }, "codeErrors": { "type": "integer" }, "sheetLabel": { "type": "string" }, "pages": { "type": "integer" }, "pageWidthMm": { "type": "number" }, "pageHeightMm": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "string" } }, "files": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "pdf", "svg", "png" ], "properties": { "pdf": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "svg": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "png": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } } } }, "openInApp": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }