Cloud Print API

The Cloud Print API sends labels to printers connected through the LabelZoom Print Agent. A user-installed agent holds a persistent connection to the cloud and prints jobs pushed from these endpoints — from the dashboard, this API, or your own integrations.

Base URL and authentication

All endpoints are hosted on the LabelZoom API gateway:

https://api.labelzoom.com

Authenticate with your LabelZoom access token — the same Authorization bearer token used by the conversion API:

Authorization: Bearer <your-access-token>

Automatic format conversion

When you send a document whose format differs from a printer’s configured native format, LabelZoom converts it before the job reaches the agent. For example, sending a PDF to a printer configured for ZPL converts the PDF to ZPL automatically — you don’t need to convert first. Declare what you’re sending with the request Content-Type (or the sourceFormat query parameter for the text printer languages) — see Send a label to a printer.

Endpoints

List printers

GET /api/v3/printers

Returns the printers configured for your account, each with its live status and the agents that can serve it.

{
  "printers": [
    {
      "id": "b2c3…",
      "name": "Warehouse Zebra",
      "connection_type": "network",
      "address": "192.168.1.50:9100",
      "status": "ready",
      "config": { "nativeFormat": "zpl", "driver": "zebra" }
    }
  ]
}

Send a label to a printer

POST /api/v3/printers/{id}/print

The request body is the raw document you want to print — exactly like the conversion API. Send the bytes directly (ZPL/EPL text, or a PDF/PNG binary); there is no JSON envelope. If the document’s format differs from the printer’s native format, it is converted automatically before printing (e.g. a PDF sent to a ZPL printer is converted to ZPL).

Declaring the format. The gateway determines the document’s format from the request Content-Type (e.g. application/pdf, image/png). Because the thermal-printer languages (ZPL, EPL, TSPL, DPL) all share text/plain, declare those explicitly with a sourceFormat query parameter:

POST /api/v3/printers/{id}/print?sourceFormat=zpl

Transformations. Any conversion parameter — rotation, dpi, label.width, scaling, and so on — can be added as a query parameter and is applied on the way to the printer, even when no format change is needed:

POST /api/v3/printers/{id}/print?sourceFormat=zpl&rotation=90

Idempotency. To make a print safe to retry, send an Idempotency-Key request header — a unique client-generated value (e.g. a UUID). Repeating the same key returns the original job instead of printing again.

Idempotency-Key: 3f1c9a2e-1b7d-4e6a-9c2f-8a5b1d4e7c90

# Send ZPL to a ZPL printer (raw body; declare the format with sourceFormat)
curl -X POST "https://api.labelzoom.com/api/v3/printers/b2c3.../print?sourceFormat=zpl" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: text/plain" \
  -H "Idempotency-Key: 3f1c9a2e-1b7d-4e6a-9c2f-8a5b1d4e7c90" \
  --data-binary '^XA^FO50,50^A0N,50,50^FDHello^FS^XZ'

# Send a PDF to a ZPL printer — converted to ZPL automatically, rotated 90°
curl -X POST "https://api.labelzoom.com/api/v3/printers/b2c3.../print?rotation=90" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/pdf" \
  --data-binary @label.pdf

The response tells you whether the job went straight to an online agent:

{ "jobId": "9f8e…", "status": "dispatched" }

status is dispatched when the job was pushed to an online agent, or queued when every bound agent is offline — a queued job prints as soon as an agent reconnects.

Status	Meaning
`200`	Job accepted (`dispatched` or `queued`).
`400`	Missing or empty document body.
`403`	The printer does not belong to your account.
`404`	No printer with that id.
`502`	The document could not be converted to the printer’s native format.

List a printer’s jobs

GET /api/v3/printers/{id}/jobs?status={status}&limit={limit}

Returns recent print jobs for a printer, most recent first. Optional status filter (queued, dispatched, completed, failed) and limit.

{
  "jobs": [
    { "id": "9f8e…", "status": "completed", "source_format": "zpl", "retry_count": 0, "created_date": "2026-07-29T15:00:00Z", "completed_date": "2026-07-29T15:00:02Z" }
  ]
}

Get a print job

GET /api/v3/jobs/{id}

Returns a single job, including its current status and any error. Poll this to track a job to completion.

Retry a failed print job

POST /api/v3/jobs/{id}/retry

Re-enqueues a failed job, replaying its stored payload. Capped so a permanently broken job cannot loop.

List print agents

GET /api/v3/agents

Returns the print agents enrolled for your account, with each agent’s online status.

Create an agent enrollment code

POST /api/v3/agents/enroll

Issues a short-lived, single-use code to pair a newly installed agent with your account. Expires in 15 minutes.

{ "enrollmentCode": "LZ-7F3K-9QW2" }

Provide it to the agent when you start it — see the Print Agent guide.