Compatibility LayersLabelary Compatibility
Labelary Compatibility API (Closed Beta)
HTTP API for rendering ZPL labels to PDF and PNG formats
This is a compatibility layer for the Labelary API, designed as a drop-in replacement for existing clients. To use this API instead of Labelary, simply change your base URL to our endpoint while keeping all other request parameters the same.
Already running on Labelary? The migration guide has the exact swap, side-by-side code samples, and a cutover checklist.
Notable Differences
| Aspect | Labelary | ZPL Tools |
|---|---|---|
| Base URL | https://api.labelary.com | https://api.zpl.tools/compatibility/labelary/ |
| Authentication | Optional via X-API-Key header | Required via X-API-Key header |
| Header Settings | Extensive support | X-Rotation, X-Quality, X-Linter fully applied; PDF page-layout headers (X-Page-*, X-Label-Border) validated but not yet composed — see Behavioral notes |
| Format Support | PNG, PDF, IPL, EPL, DPL, SBPL, PCL 5, PCL 6, JSON | PNG, PDF (other formats return 406, not a silent fallback) |
| Page Count Limit | 50 | Unlimited |
| Request Body Size | 1 MB | Unlimited |
| Image File Size | 200 KB | Unlimited |
Behavioral notes
A few divergences are subtle enough to call out explicitly rather than leave to the API reference table:
X-Rotationis PNG-only today. The header is validated (0/90/180/270, else400) and the rotation is applied to PNG output. PDF output does not yet rotate — tracked as a follow-up.- PDF page-layout headers are validated, not composed.
X-Page-Size(Letter/Legal/A4/A5/A6),X-Page-Orientation,X-Page-Layout({cols}x{rows}),X-Page-Align,X-Page-Vertical-Align, andX-Label-Borderare checked for valid values and for whether the label physically fits the page (Labelary's "not enough room" behavior), and are silently ignored for PNG output (Labelary's PDF-only headers behave the same way there). What they don't yet do is actually arrange multiple labels in a grid, resize the PDF page, or draw alignment/border — the PDF is still sized to the label. If your integration depends on the rendered page layout (not just that the request succeeds), hold off until this lands. - Unsupported
Acceptvalues return406, including formats Labelary itself supports but we don't (application/jsonlabel-data extraction,epl/ipl/dpl/sbpl/pcl5/pcl6). This is an honest rejection rather than a mismatched200. dpmmaccepts both8dpmmand bare8. Any unrecognized value (with or without the suffix) gets a400 Unknown print density, not a404.- Label dimensions accept
0.001–15inches, with a distinct error message depending on which bound was hit.
Quick Links
- Migrate from Labelary - Moving an existing integration over
- Quickstart - First request in 5 minutes
- Authentication - API key setup
- API Reference - Complete endpoint documentation
- Error Reference - Troubleshooting
Support
For issues, contact us at https://zpl.tools/contact