Migrate from Labelary

If you're rendering ZPL to PNG or PDF through api.labelary.com today, zpl.tools is a close drop-in replacement for the calls you're already making. For most integrations the change is two things: the base URL, and an X-API-Key header.

This guide is the practical version of that swap — the exact header and base-URL change, side-by-side request examples, and an honest list of where behavior differs so you don't get surprised in production.

Is this guide for you?

It's a good fit if your integration:

• Calls POST or GET /v1/printers/{dpmm}/labels/{width}x{height}/... for PNG or PDF output.
• Sends ZPL as application/x-www-form-urlencoded body or multipart/form-data.
• Uses X-Rotation or X-Quality to control rendering.

It needs a closer look first if your integration relies on any of:

• Labelary's application/json label-data extraction, or the IPL/EPL/DPL/SBPL/PCL output formats — not supported yet, see Behavioral differences.
• The X-Page-* headers (page size/orientation/layout/alignment) or X-Label-Border to actually compose a multi-label PDF page — these are accepted and validated the same way Labelary validates them, but not yet applied to the rendered PDF. See Behavioral differences.
• No API key at all (Labelary's free tier) — we require X-API-Key on every request.

None of these are disqualifying — they just mean the "change two things" swap isn't the whole story for your integration. Read Behavioral differences before you flip the switch in production.

The five-minute version

1. Get an API key. Create one from your zpl.tools account — it's required on every request (Labelary's is optional).

2. Change the base URL.

   - https://api.labelary.com
   + https://api.zpl.tools/compatibility/labelary/

3. Add the API key header to every request:

     curl -X POST "https://api.zpl.tools/compatibility/labelary/v1/printers/8dpmm/labels/4x6/0" \
   +   -H "X-API-Key: your_api_key_here" \
       --data "^XA^FO50,50^FDHello World^FS^XZ"

That's it for the common case — same path shape, same headers for Accept/X-Rotation/X-Quality, same response format. The rest of this guide covers the details worth knowing before you cut over.

What's next

• Side-by-side examples — curl, Python, and Node for the three most common calls.
• Behavioral differences — auth model, error codes, rate limits, and the handful of gaps.
• Migration checklist — a runnable checklist for cutting over.
• Full API reference — every endpoint, header, and status code.

Need a hand? Contact us — for higher-volume migrations we also run a founder-led concierge migration; ask when you reach out.