{"openapi":"3.1.0","info":{"title":"BarcodeStack API","version":"1.0.0","description":"Generate barcodes and print-ready labels from your own systems.\n\nLabels render to **native ZPL** — real printer commands (`^BC`, `^BQ`, `^A0`), not bitmaps — so output is byte-small and the printer draws every barcode at its own maximum fidelity.\n\n### Authentication\nEvery endpoint takes an API key as a bearer token:\n\n```\nAuthorization: Bearer bcs_live_…\n```\n\nCreate keys in the editor's account menu → **API keys**.\n\n### Printing what you get back\nThe ZPL responses are ready to send straight to a printer:\n\n```bash\ncurl -s -X POST … | nc PRINTER_IP 9100\n```","contact":{"name":"BarcodeStack support","email":"support@barcodestack.com"}},"servers":[{"url":"https://barcodestack.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Labels","description":"Render print-ready labels"},{"name":"Barcodes","description":"Generate a single symbol"},{"name":"Designs","description":"Print designs saved in the editor"},{"name":"Reference","description":"Label size catalog"}],"paths":{"/api/v1/labels/render":{"post":{"tags":["Labels"],"summary":"Render a label to ZPL","description":"Turn a label spec into native ZPL. Supply `rows` to render one label per data row in a single response — the fastest way to print a batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"},"examples":{"shipping":{"summary":"4×6 shipping label with a tracking barcode","value":{"size":{"preset":"thermal-4x6"},"elements":[{"type":"text","x":0.25,"y":0.25,"text":"SHIP TO","fontSize":10},{"type":"text","x":0.25,"y":0.5,"text":"{{name}}","fontSize":18,"width":3.5},{"type":"text","x":0.25,"y":0.85,"text":"{{address}}","fontSize":12,"width":3.5,"maxLines":3},{"type":"line","x":0.25,"y":1.6,"x2":3.75,"y2":1.6,"thickness":0.02},{"type":"barcode","x":0.4,"y":4.2,"symbology":"code128","value":"{{tracking}}","height":1,"moduleWidth":3}],"data":{"name":"Jane Doe","address":"1600 Amphitheatre Pkwy\nMountain View, CA 94043","tracking":"1Z999AA10123456784"}}},"batch":{"summary":"One product label per row","value":{"size":{"widthIn":2,"heightIn":1,"dpi":203},"elements":[{"type":"text","x":0.1,"y":0.08,"text":"{{sku}}","fontSize":11},{"type":"barcode","x":0.1,"y":0.3,"symbology":"code128","value":"{{sku}}","height":0.45}],"rows":[{"sku":"ABC-001"},{"sku":"ABC-002"},{"sku":"ABC-003"}]}}}}}},"responses":{"200":{"description":"ZPL document","headers":{"X-Label-Count":{"schema":{"type":"integer"},"description":"Labels in the response"}},"content":{"text/plain":{"schema":{"type":"string"},"example":"^XA\n^CI28\n^PW812\n^LL1218\n…\n^XZ"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/barcode":{"post":{"tags":["Barcodes"],"summary":"Generate one barcode or QR code","description":"Returns SVG by default (scales cleanly anywhere), or a ZPL label with `format: \"zpl\"`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarcodeRequest"},"examples":{"svg":{"summary":"Code 128 as SVG","value":{"symbology":"code128","value":"ABC-12345"}},"qr":{"summary":"QR code as SVG","value":{"symbology":"qrcode","value":"https://barcodestack.com","ecLevel":"Q"}},"zpl":{"summary":"EAN-13 as a ZPL label","value":{"symbology":"ean13","value":"5901234123457","format":"zpl","dpi":203}}}}}},"responses":{"200":{"description":"The barcode","content":{"image/svg+xml":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"example":"^XA…^XZ"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/designs":{"get":{"tags":["Designs"],"summary":"List saved designs","responses":{"200":{"description":"Designs belonging to the key's account","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"designs":{"type":"array","items":{"$ref":"#/components/schemas/Design"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/designs/{id}/render":{"post":{"tags":["Designs"],"summary":"Print a saved design","description":"Design the label in the browser, then print it from your server. `{{placeholders}}` in the design are filled from `data` (one label) or `rows` (one label per row).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"string"},"description":"Placeholder values for a single label"},"rows":{"type":"array","maxItems":1000,"items":{"type":"object","additionalProperties":{"type":"string"}},"description":"One label per row"},"copies":{"type":"integer","minimum":1,"maximum":10000,"description":"Printer-side copies of each label"}}},"examples":{"single":{"summary":"One label","value":{"data":{"name":"Jane Doe","sku":"ABC-001"}}},"batch":{"summary":"A run","value":{"rows":[{"sku":"ABC-001"},{"sku":"ABC-002"}]}}}}}},"responses":{"200":{"description":"ZPL document","headers":{"X-Conversion-Warnings":{"schema":{"type":"string"},"description":"Set when parts of the design have no native ZPL equivalent (e.g. photos)"}},"content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Nothing in the design can be drawn natively","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Designs"],"summary":"Inspect a design's converted spec","description":"Shows how a saved design maps to label elements, plus any conversion warnings. Useful when debugging output.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The converted spec","content":{"application/json":{"schema":{"type":"object","properties":{"spec":{"$ref":"#/components/schemas/LabelSpec"},"warnings":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/presets":{"get":{"tags":["Reference"],"summary":"List label sizes","description":"The full catalog of 148 label sizes — use an `id` as `size.preset` when rendering.","parameters":[{"name":"brand","in":"query","schema":{"type":"string"},"description":"Filter by printer family, e.g. `dymo`"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Match id, name, or product code"}],"responses":{"200":{"description":"Matching presets","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"presets":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the editor's account menu."}},"responses":{"BadRequest":{"description":"The request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such resource for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"invalid_spec"},"message":{"type":"string","example":"size.widthIn must be 0–24 inches"}}},"LabelSize":{"type":"object","description":"Either a `preset` id, or explicit dimensions.","properties":{"preset":{"type":"string","description":"Preset id from /api/v1/presets","example":"thermal-4x6"},"widthIn":{"type":"number","minimum":0.1,"maximum":24},"heightIn":{"type":"number","minimum":0.1,"maximum":24},"dpi":{"type":"integer","minimum":100,"maximum":1200,"example":203,"description":"Printhead resolution — 203 for most thermal printers, 300 for DYMO/Brother."}}},"TextElement":{"type":"object","required":["type","x","y","text"],"properties":{"type":{"const":"text"},"x":{"type":"number","description":"Inches from the left edge"},"y":{"type":"number","description":"Inches from the top edge"},"text":{"type":"string","description":"Supports {{placeholders}}"},"fontSize":{"type":"number","default":10,"description":"Points"},"width":{"type":"number","description":"Wrap width in inches"},"maxLines":{"type":"integer","default":8},"align":{"type":"string","enum":["left","center","right"]},"rotation":{"type":"string","enum":["N","R","I","B"],"description":"Normal, 90°, 180°, 270°"},"invert":{"type":"boolean","description":"White on black"}}},"BarcodeElement":{"type":"object","required":["type","x","y","symbology","value"],"properties":{"type":{"const":"barcode"},"x":{"type":"number"},"y":{"type":"number"},"symbology":{"type":"string","enum":["code128","code39","code93","ean13","ean8","upca","upce","itf14","interleaved2of5","codabar","msi","gs1-128","datamatrix","pdf417","aztec"]},"value":{"type":"string","description":"Supports {{placeholders}}"},"height":{"type":"number","default":0.5,"description":"Bar height in inches"},"moduleWidth":{"type":"integer","minimum":1,"maximum":10,"default":2,"description":"Narrow bar width in printer dots"},"ratio":{"type":"number","minimum":2,"maximum":3,"default":3},"humanReadable":{"type":"boolean","default":true},"rotation":{"type":"string","enum":["N","R","I","B"]}}},"QrElement":{"type":"object","required":["type","x","y","value"],"properties":{"type":{"const":"qr"},"x":{"type":"number"},"y":{"type":"number"},"value":{"type":"string"},"magnification":{"type":"integer","minimum":1,"maximum":10,"default":5},"ecLevel":{"type":"string","enum":["L","M","Q","H"],"default":"M"},"rotation":{"type":"string","enum":["N","R","I","B"]}}},"BoxElement":{"type":"object","required":["type","x","y","width","height"],"properties":{"type":{"const":"box"},"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"thickness":{"type":"number","default":0.02,"description":"Border thickness in inches"},"filled":{"type":"boolean"}}},"LineElement":{"type":"object","required":["type","x","y","x2","y2"],"properties":{"type":{"const":"line"},"x":{"type":"number"},"y":{"type":"number"},"x2":{"type":"number"},"y2":{"type":"number"},"thickness":{"type":"number","default":0.01}}},"LabelSpec":{"type":"object","required":["size","elements"],"properties":{"size":{"$ref":"#/components/schemas/LabelSize"},"elements":{"type":"array","maxItems":500,"items":{"oneOf":[{"$ref":"#/components/schemas/TextElement"},{"$ref":"#/components/schemas/BarcodeElement"},{"$ref":"#/components/schemas/QrElement"},{"$ref":"#/components/schemas/BoxElement"},{"$ref":"#/components/schemas/LineElement"}]}},"copies":{"type":"integer","minimum":1,"maximum":10000,"description":"Printer-side copies"},"darkness":{"type":"integer","minimum":0,"maximum":30,"description":"Override printer darkness for this job"}}},"RenderRequest":{"allOf":[{"$ref":"#/components/schemas/LabelSpec"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"string"},"description":"Placeholder values"},"rows":{"type":"array","maxItems":1000,"items":{"type":"object","additionalProperties":{"type":"string"}},"description":"One label per row"}}}]},"BarcodeRequest":{"type":"object","required":["value"],"properties":{"symbology":{"type":"string","enum":["code128","code39","code93","ean13","ean8","upca","upce","itf14","interleaved2of5","codabar","msi","gs1-128","datamatrix","pdf417","aztec","qrcode"],"default":"code128"},"value":{"type":"string"},"format":{"type":"string","enum":["svg","zpl","json"],"default":"svg"},"scale":{"type":"integer","minimum":1,"maximum":20,"description":"Module width — px for SVG, printer dots for ZPL"},"heightIn":{"type":"number","default":0.5},"humanReadable":{"type":"boolean","default":true},"ecLevel":{"type":"string","enum":["L","M","Q","H"],"description":"QR only"},"dpi":{"type":"integer","default":203,"description":"ZPL format only"}}},"Design":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"presetId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Preset":{"type":"object","properties":{"id":{"type":"string","example":"thermal-4x6"},"name":{"type":"string"},"brand":{"type":"string"},"widthIn":{"type":"number"},"heightIn":{"type":"number"},"dpi":{"type":"integer"},"widthDots":{"type":"integer"},"heightDots":{"type":"integer"},"kind":{"type":"string","enum":["thermal","sheet","paper"]},"labelsPerSheet":{"type":["integer","null"]},"aliases":{"type":"array","items":{"type":"string"}}}}}}}