Render every label to a single PDF

POST /compatibility/labelary/v1/printers/{dpmm}/labels/{dimensions} Render all labels in the ZPL document into one multi-page PDF. This path takes no label index, so request Accept: application/pdf. To render one label as PNG, use the endpoint with an {index} path segment. Requires an API key in the X-API-Key header.

Parameters

Path parameters

Name	Type	Required	Description
`dpmm`	`6dpmm` \| `8dpmm` \| `12dpmm` \| `24dpmm`	Yes	Printer resolution in dots-per-millimeter. `8dpmm` = 203 DPI, `12dpmm` = 300 DPI, `24dpmm` = 600 DPI, `6dpmm` = 152 DPI.
`dimensions`	string	Yes	Label size in inches as `{width}x{height}`. Each dimension must be between 0.1 and 15 inches.

Headers

Name	Type	Required	Description
`Accept`	`application/pdf`	No	Output format. This endpoint renders every label, so `application/pdf` is the meaningful value. A PNG request must carry an index.
`X-Rotation`	`0` \| `90` \| `180` \| `270`	No	Clockwise rotation of the rendered output. Any other value returns `400`. The renderer applies it to PNG output only; PDF rotation is not implemented yet.
`X-Quality`	`Bitonal`	No	Set to `Bitonal` (case-insensitive) to post-process PNG output to 1-bit black and white. Any other value keeps the default grayscale/color rendering. PNG only.
`X-Linter`	`On`	No	Set to `On` (case-insensitive) to request renderer diagnostics. The response then carries an `X-Warnings` header with up to 20 warnings. See the Diagnostics Reference.
`X-Page-Size`	`letter` \| `a4` \| `legal` \| `a3`	No	Optional target page size for PDF output. The API validates the value, but applies the page layout only in part. Omit for label-sized pages.
`X-Page-Orientation`	`portrait` \| `landscape`	No	Optional page orientation for `X-Page-Size`.
`X-Page-Layout`	string	No	Optional grid layout as `{cols}x{rows}`. With `X-Page-Size`, the API validates that the labels fit vertically on the page.
`X-Page-Align`	`left` \| `right` \| `center` \| `justify`	No	Horizontal alignment of labels on the page, for `X-Page-Size`. Any other value returns `400`. The renderer does not apply page composition yet.
`X-Page-Vertical-Align`	`top` \| `bottom` \| `center` \| `justify`	No	Vertical alignment of labels on the page, for `X-Page-Size`. The API only validates it.
`X-Label-Border`	`dashed` \| `solid` \| `none`	No	Border around each label on a composed page. The API only validates it.

Request body

Raw ZPL. Send it as the entire request body with Content-Type: application/x-www-form-urlencoded, or upload it as a file field with multipart/form-data.

`application/x-www-form-urlencoded`

Type: string. The raw ZPL document as the whole request body.

Example

^XA^FO50,50^A0N,50,50^FDHello World^FS^XZ

`multipart/form-data`

Field	Type	Required	Description
`file`	binary	Yes	A file whose contents are the ZPL document.

Responses

`200`

Rendered PDF containing every label.

Headers:

X-Total-Count — Total number of labels the ZPL document renders.
X-Warnings — Present only when the request carries X-Linter: On and the render reports diagnostics. Pipe-delimited entries of {byteIndex}\|{byteSize}\|{commandName}\|{paramNumber}\|{message}, limited to 20 warnings.
Content-Disposition — Suggested filename for the rendered output, e.g. inline; filename="label.png".

Content-Type: application/pdf

`400`

Invalid request parameters or ZPL. Body is plain text prefixed with ERROR: .

Content-Type: text/plain

ERROR: Unknown print density 10; valid values: 6, 8, 12, 24

`401`

Missing, invalid, or expired API key.

Content-Type: application/json

Field	Type	Required	Description
`error`	string	Yes

{
  "error": "Missing or invalid Authorization header"
}

`404`

Label index out of range, missing ZPL, or an unrecognized path. Body is plain text prefixed with ERROR: .

Content-Type: text/plain

ERROR: Requested 2nd label but ZPL only generated 1 label

`500`

ZPL failed to parse/render on the server.

Content-Type: text/plain

ZPL parse error: unexpected end of input

`503`

The API-key store is not ready. Retry shortly.

Content-Type: application/json

Field	Type	Required	Description
`error`	string	Yes

{
  "error": "API key store initialization failed"
}

Example request

curl -X POST "https://api.zpl.tools/compatibility/labelary/v1/printers/8dpmm/labels/4x6" \
  -H "X-API-Key: your_api_key_here" \
  -H "Accept: application/pdf" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "^XA^FO50,50^A0N,50,50^FDHello World^FS^XZ"

Render every label to a single PDF

On this page