API Reference

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

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.