Render a Label

POST /v1/labels — send raw ZPL, get a signed URL to a rendered PNG. The fastest path to a label when you already have the full ZPL in hand.

cURLPythonJavaScript

curl -X POST https://api.maddoxapi.dev/v1/labels \
  -H "Authorization: Bearer $MADDOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "zpl": "^XA…^XZ", "source_dpi": 203, "target_dpi": 203 }'

Endpoint#

endpoint

POST /v1/labels

Authentication: Bearer API key — Authorization: Bearer <api_key>. See Authentication.

Request Body#

Content-Type: application/json is required (a non-JSON content type returns 415).

Field	Type	Required	Default	Description
`zpl`	string	yes	—	The ZPL to render. Must be a non-empty string.
`source_dpi`	integer	no	`203`	DPI the ZPL was authored for. Integer, 1–1200.
`target_dpi`	integer	no	`203`	DPI to render at — match your printer. See Rendering & DPI.
`threshold`	boolean	no	`false`	`true` renders a hard black/white image; `false` is an anti-aliased preview.
`font_profile`	string	no	engine	Font family for built-in text: `dejavu`, `inter`, `plex`, `roboto`.

NoteThe maximum request body size is 5 MB. Your target_dpi may not exceed your plan's DPI ceiling — see Plans & Quotas.

Idempotency#

Pass an Idempotency-Key header to make retries safe. A replay of the same key and body returns the original response with an Idempotency-Replay: true header; the same key with a different body returns 409 IdempotencyKeyConflict.

Response#

200 OK

200 OK

{
  "status": "ok",
  "url": "https://api.maddoxapi.dev/v1/labels/9b1c4f?…&sig=…",
  "cached": false,
  "warnings": []
}

Field	Type	Description
`status`	string	`"ok"` on success.
`url`	string	A signed URL to the rendered PNG. Fetch it directly — no auth header.
`cached`	boolean	`true` if served from cache (identical ZPL + DPI seen before).
`warnings`	array	Non-fatal advisories, e.g. an extreme DPI ratio. Empty when there's nothing to flag.

Error Codes#

Status	`kind`	Cause
400	`InvalidJson`	Body is not valid JSON.
400	`InvalidDpi`	`source_dpi`/`target_dpi` not an integer in 1–1200.
401	`Unauthorized`	Missing, invalid, or revoked API key.
402	(gate `kind`)	Monthly volume / sandbox cap reached. Body may include `upgrade_url`.
403	`DpiNotPermitted`	Requested DPI exceeds your plan's ceiling.
409	`IdempotencyKeyConflict`	`Idempotency-Key` reused with a different body.
413	`PayloadTooLarge`	Body exceeds the 5 MB limit.
415	`UnsupportedMediaType`	`Content-Type` is not `application/json`.
422	`MissingZpl`	`zpl` missing or empty.
429	`RateLimitExceeded`	Too many requests / in-flight. Honor `Retry-After`.
503	`AgentOverloaded`	Renderer temporarily overloaded. Retriable.

Errors share a common envelope:

error

{ "status": "error", "errors": [{ "kind": "MissingZpl", "message": "'zpl' is required" }] }

Rendering & DPI

How source/target DPI affects output size and sharpness.

Signed URLs

What the url is and how long it lasts.