zpl.tools
Compatibility LayersLabelary Compatibility

Endpoints

Complete list of all API endpoints

This page documents the zpl.tools compatibility layer, not the official Labelary API.

Available Endpoints

  • GET /compatibility/labelary/v1/printers/{dpmm}/labels/{width}x{height}/{index}/{zpl}
    • The URL-length limit is 16 KB. Use POST for large ZPL.
  • POST /compatibility/labelary/v1/printers/{dpmm}/labels/{width}x{height}/{index}
    • Extract single label by index.
  • POST /compatibility/labelary/v1/printers/{dpmm}/labels/{width}x{height}/
    • Render all labels (PDF only).

Path Parameters

ParameterTypeDescription
dpmmstringPrinter resolution: 6dpmm (152 DPI), 8dpmm (203 DPI), 12dpmm (304 DPI), or 24dpmm (609 DPI). The resolution is floor(dpmm × 25.4), as on Labelary, so a 4×6 label is 812×1218 px at 8dpmm and 1216×1824 px at 12dpmm. The dpmm suffix is optional, and the API also accepts a bare number (8). Any value other than the four densities returns 400 Unknown print density, not 404.
widthnumberLabel width in inches (0.001–15)
heightnumberLabel height in inches (0.001–15)
indexnumberLabel index in the document (0-based). Required for PNG output. A PNG request on the all-labels endpoint returns 404.
zplstringZPL code (sent in POST body as raw data)

Headers

Required Headers

HeaderDescription
X-API-KeyYour API key for authentication

Optional Headers

HeaderValuesPurposeSupported
Acceptapplication/pdf, image/pngSpecify output format (default: image/png)✅ Yes. Any other value returns 406, including Labelary formats like application/json and application/epl
X-Rotation0, 90, 180, 270Rotate output clockwise⚠️ PNG only. The API does not rotate PDF output yet. Any other value returns 400.
X-QualityGrayscale (default), BitonalPNG color depth✅ Yes. PNG only
X-LinterOn, Off (default)Opt-in ZPL linting✅ Yes. See the Linting reference
X-Page-SizeLetter, Legal, A4, A5, A6PDF page size⚠️ Validated only. The API accepts and rejects values exactly like Labelary, and checks that the label fits. It does not yet size or compose the PDF page. PDF only.
X-Page-OrientationPortrait, LandscapePDF page orientation⚠️ Validated only (see above)
X-Page-Layout{cols}x{rows}, e.g. 2x3Labels per PDF page, in a grid⚠️ Validated only (see above). The row count must fit the page height. The API does not yet arrange a grid.
X-Page-AlignLeft, Right, Center, Justify (default)Horizontal placement on the PDF page⚠️ Validated only (see above)
X-Page-Vertical-AlignTop, Bottom, Center, Justify (default)Vertical placement on the PDF page⚠️ Validated only (see above)
X-Label-BorderDashed (default), Solid, NoneBorder around each label⚠️ Validated only (see above)

See Behavioral notes for the meaning of "validated only".

Response Headers

HeaderDescription
Content-TypeMIME type of response
X-Total-CountTotal number of labels in document

Status Codes

CodeMeaning
200Success
400Bad request (invalid parameters)
404Not found
406Not Acceptable (unsupported format)
500Server error

Next Steps

Skip Policy

The ZPL commands the renderer ignores, why that is safe, and what the diagnostics show

Performance

How zpl.tools compares with other ZPL engines, measured 2026-08-17

On this page

Available EndpointsPath ParametersHeadersRequired HeadersOptional HeadersResponse HeadersStatus CodesNext Steps