API Reference

Every ProxyBox 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
Local (same network)	https://pbx-<id>.pbxz.io/api/v1
Remote (anywhere)	https://pbx-<id>.pbxz.cloud/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. See Remote Access for details.

Authentication

All requests must include your API key in the X-API-Key header. Each ProxyBox has its own key — find and regenerate yours on the admin page under Settings. The keys shown in examples throughout these docs (like the one below) are placeholders; substitute your device’s key.

X-API-Key: ULA9WHXMFCHF

Note

API key authentication can be toggled on/off via the Require API Key setting on the admin page. When disabled, 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 Require API Key is enabled).
404	Printer or job not found.
503	Printer not ready — the pre-flight check found a problem (ZPL printers only).

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.