POST /print/{target}/test

Send a test print to a printer. What gets printed depends on the printer family: a branded ZPL test label (Zebra), an ESC/POS test receipt (Epson TM-series), a label sized to the loaded media (Brother P-touch/QL), or a PDF test page (everything else).

Endpoint:

POST /api/v1/print/{target}/test

Path Parameter

Parameter	Type	Description
target	string	Same as POST /print/{target} — the printer’s path value or a tag alias.

Body Parameter (Brother label printers only)

USB Brother P-touch printers detect the loaded tape. Omit media to generate a label at that width, with its length fitted to the content on every tape width (minimum 36pt). If you supply media, it must equal the detected name.

QL and network P-touch printers require a media name in a JSON body or as a ?media= query parameter. For example, to require 24mm tape on a USB P-touch:

POST /api/v1/print/usb_sn_000F5G234070/test
Content-Type: application/json

{ "media": "tz-24" }

Parameter	Type	Description
media	string	Media size name (e.g. tz-24, 62mm). Optional for USB P-touch; a name different from the loaded tape returns 400 with { message, loadedTape }. Required for QL and network P-touch; a missing or unknown name returns 400 with validMedia (an array of names). Ignored for other printer families.

Response

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "module": "/print/tcp_192-168-86-250_9100/test",
    "message": "Test print sent successfully.",
    "content": null
  }
}

Error Responses

Code	Condition
400	USB P-touch media differs from the detected tape, or QL/network P-touch media is missing or unknown.
409	USB P-touch has no tape, unsupported tape, or a decoded printer error.
503	USB P-touch tape is unreadable, or the queue is busy with no previous reading; also returned for a Zebra pre-flight failure.

For USB P-touch, errors contain { message, loadedTape } as on POST /print/{target}. For example, requesting tz-24 with 12mm tape loaded returns 400 with the message Requested media tz-24 does not match the loaded tape; the printer has 12 mm tape loaded (34 pt).

The tape is read when the queue is idle. Processing, pending jobs, and the 20 seconds after a queue state change reuse the last reading. With no previous reading, loadedTape is null and the request returns 503.

A Zebra test-print 503 has result.message equal to Printer is not ready; its result.content is the printer status (ready, paperOut, paused, headOpen, ribbonOut, errors), rather than a print-job record.