Admin API

prox includes an optional HTTP management API for external integration. When configured, it exposes REST endpoints for health checks, configuration reload, certificate monitoring, and runtime inspection.

Zero Overhead

The admin API is disabled by default. No goroutines, listeners, or allocations are created unless the admin block is present in your configuration.

Configuration

Add the admin block to your root config:

TCPUnix Socket

{
  admin: {
    listen: "127.0.0.1:9090",
    token: "your-secret-token",
  },
  // ... services, actions, etc.
}

{
  admin: {
    listen: "unix:///var/run/prox.sock",
  },
  // ... services, actions, etc.
}

Field	Type	Required	Description
listen	string	Yes	TCP address ("127.0.0.1:9090") or Unix socket ("unix:///var/run/prox.sock")
token	string	No	Bearer token for authentication. If set, all requests must include Authorization: Bearer <token>

Security

The admin API has no default listen address; listen is required. For production use, bind to localhost or a Unix socket, configure a token, and apply network-level access control before exposing the API.

Authentication

When token is configured, all requests must include the Authorization header:

curl -H "Authorization: Bearer $PROX_TOKEN" http://127.0.0.1:9090/api/health

Requests without a valid token receive a 401 Unauthorized response.

Endpoints

GET /api/health

Returns server health and status information.

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": "2h15m0s",
  "routes": 12,
  "services": 3,
  "config_valid": true
}

POST /api/reload

Triggers a synchronous configuration reload. The response indicates success or failure with details.

// Success
{ "ok": true, "routes": 14, "services": 2 }

// Error
{ "ok": false, "error": "service \"web\" route #3: action \"api\" not found in actions" }

Tip

Unlike SIGHUP or file-watcher reloads, the admin API reload is synchronous — you get the result in the response. A mutex prevents concurrent reloads from any source.

GET /api/certs

Returns the status of all ACME-managed certificates.

[
  {
    "domain": "api.example.com",
    "status": "active",
    "expires": "2026-08-29T12:00:00Z",
    "issuer": "Let's Encrypt"
  },
  {
    "domain": "staging.example.com",
    "status": "pending"
  }
]

Status	Meaning
active	Certificate is issued and cached
pending	Certificate is being obtained or not yet available

GET /api/routes

Returns all configured routes with match patterns, actions, and plugins.

[
  {
    "service": "web",
    "index": 0,
    "match": { "domain": "*.example.com", "path": "/api/*" },
    "action": "proxy_backend",
    "balancer": "roundrobin",
    "plugins": ["auth"]
  },
  {
    "service": "web",
    "index": 1,
    "action": "frontend"
  }
]

GET /api/services

Returns metadata about each configured service.

[
  { "name": "web", "listen": ":443", "tls": true, "acme": true, "routes": 5 },
  { "name": "internal", "listen": ":8080", "tls": false, "acme": false, "routes": 3 }
]

GET /api/plugins

Returns all configured plugins.

[
  { "name": "auth", "path": "./plugins/auth" },
  { "name": "resolver", "path": "./plugins/resolver" }
]

GET /api/balancers

Returns the current state of all route balancers, including their live target pools.

[
  {
    "service": "web",
    "route_index": 0,
    "type": "roundrobin",
    "action": "proxy_backend",
    "targets": ["10.0.0.1:8080", "10.0.0.2:8080", "10.0.0.3:8080"]
  }
]

Service Discovery

This endpoint is particularly useful for verifying that plugin-managed targets are correctly registered and active.

GET /api/config

Returns the current configuration with sensitive fields redacted.

{
  "services": { "..." },
  "actions": { "..." },
  "admin": {
    "listen": "127.0.0.1:9090",
    "token": "[REDACTED]"
  }
}

Fields named token are automatically replaced with "[REDACTED]" in the response.

Integration Examples

Health Check (monitoring)

# Simple liveness probe
curl -sf http://127.0.0.1:9090/api/health | jq .status

# Kubernetes-style health check
curl -sf -o /dev/null -w "%{http_code}" http://127.0.0.1:9090/api/health

CI/CD Reload

# Deploy new config, then reload
cp new-config.json5 /etc/prox/config.json5
curl -X POST -H "Authorization: Bearer $PROX_TOKEN" \
  http://127.0.0.1:9090/api/reload | jq .

Certificate Monitoring

# Check for expiring certificates
curl -s -H "Authorization: Bearer $PROX_TOKEN" \
  http://127.0.0.1:9090/api/certs | \
  jq '.[] | select(.status == "active") | {domain, expires}'