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. You can find and regenerate your API key on the admin page under Settings.

X-API-Key: YOUR_API_KEY

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).

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.