POST /print/{target}

Send a print job to a specific printer. Returns a job ID for tracking.

Endpoint:

POST /api/v1/print/{target}

Path Parameter

Parameter	Type	Description
target	string	The printer’s path value from GET /printers, or a tag alias (e.g. tag_LABELS).

Request Body

Three options for sending print data:

Option 1: Raw binary data

Send the raw print data (ZPL, PDF, etc.) directly as the request body. Always synchronous — blocks until the job completes.

POST /api/v1/print/tcp_192-168-86-250_9100
Content-Type: application/octet-stream
X-API-Key: YOUR_API_KEY

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

Option 2: JSON with URL

Send a JSON body with a content field containing a URL to fetch the document from.

POST /api/v1/print/tcp_192-168-86-250_9100
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "content": "https://example.com/label.zpl",
  "contentType": "raw_url"
}

Option 3: JSON with base64

Send a JSON body with base64-encoded content and print options.

POST /api/v1/print/tag_LABELS
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "content": "XlhBXkZPNTAsNTBeQTBOLDUwLDUwXkZESGVsbG8gV29ybGReRlNeWFo=",
  "contentType": "raw_base64",
  "title": "Shipping Label #1234",
  "source": "my-erp",
  "options": {
    "copies": 2
  }
}

JSON Body Fields

Field	Type	Required	Description
content	string	Yes	The document to print — a URL, base64-encoded data, or a local file path.
contentType	string	Recommended	One of: pdf_url, pdf_base64, raw_url, raw_base64, zpl, zpl_base64. When omitted, inferred from the content and printer type. New integrations should always set this.
title	string	No	Job name. Passed to CUPS. Defaults to "Untitled".
source	string	No	Identifier for the submitting application or user (e.g. "my-erp", "jsmith").
wait	boolean	No	true (default): block until job completes. false: return immediately, poll GET /jobs/{jobId} for status.
options	object	No	Print options (see below). Unsupported options for a given printer are silently ignored.
idempotencyKey	string	No	Unique key to prevent duplicate submissions. If a job with this key already exists (within 1-hour TTL), the existing job is returned with HTTP 200.

Print Options

Option	Type	Description
copies	number	Number of copies. Default 1.
duplex	string	"one-sided", "long-edge", or "short-edge".
colorMode	string	"color", "grayscale", or "auto".
paperSize	string	CUPS media name (e.g. "letter", "a4"). Must be in the printer’s mediaSupported.
pageRange	string	Page range (e.g. "1-5", "1,3,7-9"). PDF only.
bin	string	Paper tray / input slot name.
fitToPage	boolean	Scale content to fit the page. PDF only.
orientation	string	"portrait", "landscape", "reverse-landscape", or "reverse-portrait".
quality	string	"draft", "normal", or "high".

Success Response (200 — synchronous)

Returned when wait is true (default) or for raw binary requests.

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "module": "/print/tag_LABELS",
    "message": "Printed successfully.",
    "content": {
      "jobId": "pj_a8f3e1b2",
      "printer": "tcp_192-168-86-250_9100",
      "target": "tag_LABELS",
      "title": "Shipping Label #1234",
      "source": "my-erp",
      "state": "completed",
      "error": null,
      "createdAt": "2026-03-28T14:30:00.000Z",
      "completedAt": "2026-03-28T14:30:08.500Z"
    }
  }
}

Accepted Response (201 — non-waiting)

Returned when wait is false. Poll GET /jobs/{jobId} for the final state.

{
  "status": "success",
  "statusCode": 201,
  "result": {
    "module": "/print/tag_LABELS",
    "message": "Print job accepted.",
    "content": {
      "jobId": "pj_a8f3e1b2",
      "printer": "tcp_192-168-86-250_9100",
      "target": "tag_LABELS",
      "title": "Shipping Label #1234",
      "source": "my-erp",
      "state": "queued",
      "error": null,
      "createdAt": "2026-03-28T14:30:00.000Z",
      "completedAt": null
    }
  }
}

Error: 503 — Printer Not Ready

Returned when the pre-flight status check detects an issue (ZPL printers only). See Pre-flight Status Check for details.

{
  "status": "error",
  "statusCode": 503,
  "result": {
    "module": "/print/tcp_192-168-86-250_9100",
    "message": "Printer is not ready",
    "content": {
      "jobId": "pj_c4d5e6f7",
      "printer": "tcp_192-168-86-250_9100",
      "target": "tcp_192-168-86-250_9100",
      "state": "failed",
      "error": "Printer not ready: paper out, head open",
      "createdAt": "2026-03-28T14:30:00.000Z",
      "completedAt": "2026-03-28T14:30:00.500Z"
    }
  }
}