API Reference

POST/v1/convert

Renders ZPL to PDF (default) or PNG. By default it returns the raw file bytes and stores nothing; pass "output": "url" (paid plans) to host the file and get a signed link back.

Body parameters

Field	Type	Default	Description
zpl	string	required	Raw ZPL (one or more ^XA…^XZ labels). Max 512 KB.
dpmm	6 \| 8 \| 12 \| 24	8	Print density in dots/mm. 8 = 203 dpi, 12 = 300 dpi, 24 = 600 dpi.
widthMm	number	101.6	Label width in millimeters (default 4 in).
heightMm	number	152.4	Label height in millimeters (default 6 in).
format	pdf \| png	pdf	Output format.
output	data \| url	data	Delivery mode. "data" returns the raw file bytes and stores nothing (all plans). "url" hosts the file and returns a signed link (paid plans only).
retentionDays	number	3	For output:"url" only. Days to retain the hosted file, clamped to your plan max (Starter 3, Pro 30, Scale 90).

Example request

curl -X POST https://api.zpljet.com/v1/convert \
  -H "X-API-Key: zpl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "zpl": "^XA^FO50,50^A0N,50,50^FDHello^FS^XZ",
    "dpmm": 8,
    "widthMm": 101.6,
    "heightMm": 152.4,
    "format": "pdf"
  }' \
  --output label.pdf

Response

With "output": "data" (default), the response body is the raw application/pdf or image/png bytes, with the conversion id in the X-Conversion-Id header.

With "output": "url", the response is JSON:

{
  "id": "7c9fc824-8d30-4bb9-ba36-03d3bcf574bf",
  "url": "https://…/file.pdf?…",
  "pages": 1,
  "retentionDays": 7,
  "expiresAt": "2026-07-08T20:09:22.333Z",
  "urlExpiresAt": "2026-07-08T20:09:22.333Z"
}

expiresAt is when the file is deleted; urlExpiresAt is when the signed link expires (capped at 7 days).

Status codes

200	Success. The raw PDF/PNG bytes (output:"data", default), or JSON with a signed URL (output:"url").
400	Invalid request body.
401	Missing or invalid API key.
402	Monthly conversion quota exceeded for your plan.
403	Hosting not permitted — plan is data-only, or no-retention mode is enforced.
429	Rate limit exceeded — see the Retry-After header (seconds).
502	The rendering engine failed to process the ZPL.

Full machine-readable spec: OpenAPI 3.1.