GET /printers

Returns all configured printers — both auto-discovered and manually added — with real-time status from CUPS.

Endpoint:

GET /api/v1/printers

Response

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "module": "/printers",
    "message": "Successfully obtained printers.",
    "content": [
      {
        "id": "MYS9QT8D",
        "type": "printer",
        "path": "tcp_192-168-86-250_9100",
        "connection": {
          "type": "network",
          "host": "192.168.86.250",
          "port": 9100,
          "protocol": "tcp"
        },
        "model": "Zebra ZD421",
        "content": "zpl",
        "discovered": false,
        "localAddress": "192.168.86.250",
        "status": "online",
        "statusReasons": [],
        "tags": ["LABELS"]
      }
    ]
  }
}

Printer Object Fields

Field	Type	Description
id	string	Unique printer identifier.
path	string	The addressable path — use this as the target parameter when printing.
connection.type	string	network or usb.
connection.host	string	IP or hostname (network printers).
connection.port	number	Port number (network printers).
connection.protocol	string	tcp, ipp, http, or https.
connection.serialNumber	string	Serial number (USB printers only).
model	string	Printer model name.
content	string	Content type: raw, pdf, or zpl.
supportedFormats	string[]	MIME types supported (discovered via IPP).
discovered	boolean	true if auto-discovered, false if manually added.
status	string	Printer status: online, error, or unknown. Derived from CUPS queue state.
statusReasons	string[]	CUPS printer-state-reasons for the queue (e.g. media-empty, toner-low-warning, paused). Empty array when no conditions are raised.
tags	string[]	Names from the device’s tag list whose path matches this printer. Each can be used as a print target as tag_<name>.
loadedTape	object | null	USB P-touch tape reading; see below. Omitted for other printers.
capabilities	object	Capability snapshot captured during discovery (see below).

Status Reasons

statusReasons reflects what the CUPS queue knows about the printer. Driver- and IPP-backed printers report rich conditions (e.g. media-empty, toner-low-warning, paused). Raw socket printers such as Zebra label printers on TCP port 9100 always report an empty array — CUPS learns nothing about printer health from a raw socket. For Zebra printers, health is checked at print time instead: see the pre-flight status check.

Loaded Tape (USB P-touch)

loadedTape is present on supported USB P-touch printers and omitted on other printers. It has three shapes:

Shape	Meaning
{ media, label, widthMm, widthPt, mediaType, readAt }	Successful tape reading. media is the media name, label is its display label, widthPt is the PDF page width in points, and mediaType is the numeric Brother media-type code. widthMm is the reported width; 3.5mm tape reports 4 and uses tz-4 with widthPt: 10.
{ reason, readAt }	Failed reading. reason is no-tape, unsupported-tape, printer-error, or unreadable.
null	The queue is busy and this backend process has never read the tape.

For example, a successful reading is:

{
  "media": "tz-24",
  "label": "24 mm tape",
  "widthMm": 24,
  "widthPt": 68,
  "mediaType": 1,
  "readAt": "2026-03-28T14:30:00.000Z"
}

An idle queue gets a live reading, bounded to 3 seconds. A busy queue returns the last reading with its original readAt timestamp. Busy includes processing, pending jobs, and the 20 seconds after the queue last changed state: CUPS can report a completed job while the label is still printing and cutting, so ProxyBox does not query the printer then. A stopped queue with no pending jobs and no recent state change also permits a read.

For USB P-touch, use loadedTape.widthPt to size a PDF. capabilities.mediaSupported describes the driver default, not the loaded tape.

Capabilities Object

Use capabilities to build valid print requests — it tells you which print options a printer will honor. IPP printers report real values; other printer types get sensible defaults. For USB P-touch media, use loadedTape; capabilities.mediaSupported is the driver default.

Field	Type	Description
makeAndModel	string	Make and model as reported by the printer.
colorSupported	boolean	Whether the printer can print in color (colorMode option).
documentFormatsSupported	string[]	MIME types the printer accepts.
mediaSupported	string[]	Valid values for the paperSize print option (IPP media names, e.g. na_letter_8.5x11in, iso_a4_210x297mm).
sidesSupported	string[]	Duplex support: one-sided, two-sided-long-edge, two-sided-short-edge.
copiesSupported	[number, number]	[min, max] range for the copies option.