API Reference

POST/v1/convert

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

Body parameters

Field	Type	Default	Description
zpl	string	required	Raw ZPL (one or more ^XA…^XZ labels, up to 50 per request). Must start with ^XA (or a ~ device command) and end with ^XZ. 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. PNG supports one label per request; use PDF for multi-label ZPL.
output	data \| url	data	Delivery mode. "data" returns the raw file bytes and stores nothing (all plans). "url" hosts the file and returns a public link (paid plans only), kept for your account's retention window — set in the dashboard, up to your plan max (Starter 3, Pro 30, Scale 90 days).

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

The official SDKs wrap this endpoint with typed params, typed errors, and retries.

Response

With "output": "data" (default), response body is 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://files.zpljet.com/…/file.pdf",
  "pages": 1,
  "retentionDays": 7,
  "expiresAt": "2026-07-08T20:09:22.333Z"
}

url is a public link that works until expiresAt, when the file is deleted.

Status codes

Errors are JSON with structured error object — branch on the stable error.code. See Errors & Limits for every code and context fields.

Status	error.code	Description
200	—	Success. The raw PDF/PNG bytes (output:"data", default), or JSON with a public URL (output:"url").
400	invalid_request	Invalid request body — error.param names the offending field.
401	missing_api_key · invalid_api_key	Missing or invalid API key.
402	quota_exceeded	Monthly quota exceeded — error.resetsAt says when it resets (UTC).
403	hosting_not_allowed · no_retention_enforced	Hosting not permitted — plan is data-only, or no-retention mode is enforced.
413	payload_too_large	Request body exceeded the 1 MiB transport limit.
429	rate_limit_exceeded	Rate limit exceeded — error.retryAfter (seconds) and error.retryAt (UTC timestamp) say when to retry; the Retry-After header carries the seconds.
502	conversion_failed	The rendering engine failed to process the ZPL — error.conversionId identifies the attempt for support.
503	service_unavailable	Render engine temporarily unavailable; the request was not charged against quota. Retry after the retry-after interval.

Full machine-readable spec: OpenAPI 3.1.