API Reference

Every ProxyBox Zero has two base URLs — one for local access and one for remote access. The API works identically on both.

AI agents can use your ProxyBox’s MCP endpoint to list printers and print. See Connect an AI agent (MCP) for setup instructions.

Access	Base URL
Remote (anywhere)	https://pbx-<id>.pbxz.cloud/api/v1
Local (same network)	https://pbx-<id>.pbxz.io/api/v1

Replace <id> with your 4-character device ID (found on the sticker on your device). The .cloud URL routes through an encrypted tunnel — no VPN or port forwarding required. The .io URL is for browsers and on-prem services on the same network as the box. See Remote Access for details.

Authentication

When Settings → Options → API Key is Required, requests must include an enabled API key in the X-API-Key header. Find, reveal, and copy your keys under Settings → API Keys; to create another, enter a name in Key name… and select Create Key. The keys shown in examples throughout these docs (like the one below) are placeholders; substitute your device’s key.

X-API-Key: ULA9WHXMFCHF

Note

Set API Key to Required or Optional under Settings → Options. When Optional, the header is not required.

Response Format

All endpoints return a standard JSON envelope:

Field	Type	Description
status	string	"success" or "error".
statusCode	number	HTTP status code.
result.module	string	The route that handled the request.
result.message	string	Human-readable status message.
result.content	object | null	Response payload (varies by endpoint).

HTTP Status Codes

Code	Meaning
200	Success. For POST /print, the job completed (synchronous mode).
201	Print job accepted, still in progress (wait: false).
400	Bad request — malformed body, or a rejected job (e.g. a Brother label media mismatch).
401	Missing or invalid X-API-Key (when API Key is Required).
404	Printer or job not found.
409	USB P-touch tape problem — no tape, unsupported tape, or a printer error. See Tape Problem.
503	The Zebra pre-flight check found a problem, or the USB P-touch tape could not be read. See Printer Not Ready.

Request bodies are limited to 50 MB (both raw binary and JSON).

Error Responses

All endpoints may return an error in this format:

{
  "status": "error",
  "statusCode": 400,
  "result": {
    "module": "/status",
    "message": "An error occurred.",
    "content": "A specific error occurred."
  }
}

Endpoints

Method	Path	Description
GET	/status	Device status and health
GET	/printers	List all printers with status
GET	/printers/{path}	Get a single printer by path
GET	/discover	Trigger printer discovery
POST	/print/{target}	Send a print job
POST	/print/{target}/test	Send a test print
GET	/jobs/{jobId}	Get print job status

OpenAPI Specification

The full OpenAPI 3.1 specification is available for programmatic consumers at openapi.json.