Skip to main content
The control plane exposes a REST API on the configured port (default 8080). User-facing endpoints for apps, machines, deployments, volumes, secrets, and databases are documented alongside their CLI commands in the Guides and CLI Reference. This page covers the internal and administrative endpoints used by host agents and operators.

​
Public (no auth)

MethodPathDescription
GET/Service info ({"service":"zwrmd","version":"..."})
GET/metricsPrometheus metrics
GET/v1/healthHealth check ({"status":"healthy"})

​
Internal (host agent auth)

These endpoints are used by zwrm-agent for registration and image distribution. Authenticated via SHA-256 hash of the license key.
MethodPathDescription
POST/v1/internal/hosts/registerRegister a host agent
POST/v1/internal/hosts/{host_id}/heartbeatHost heartbeat
POST/v1/internal/hosts/{host_id}/deregisterDeregister a host agent
GET/v1/internal/images/{digest}Download image by content-addressed digest
HEAD/v1/internal/images/{digest}Check image existence
GET/v1/internal/imagesList images (optional ?app_id=)

​
Host management

MethodPathDescription
GET/v1/hostsList all hosts
GET/v1/hosts/{host_id}Get host with capacity
POST/v1/hosts/{host_id}/drainInitiate host drain
GET/v1/hosts/{host_id}/drain-statusGet drain progress
POST/v1/hosts/{host_id}/undrainCancel drain
POST/v1/hosts/{host_id}/activateReturn host from maintenance

​
System

MethodPathDescription
GET/v1/auth/whoamiCurrent user info
GET/v1/statusSystem status (scoped to user’s org)

​
Authentication

Protected endpoints require one of:
  • Session token: Authorization: Bearer <session_token>
  • API key: Authorization: Bearer <api_key>
  • Localhost bypass: Requests from 127.0.0.1 or ::1 bypass auth with host-admin access
Internal endpoints (under /v1/internal/) use the license key hash for authentication instead of session tokens.

​
Middleware

All requests pass through the middleware stack in order:
MiddlewareDescription
LoggerLogs METHOD PATH STATUS DURATION BYTES
RecoveryCatches panics, returns 500 JSON
CORSValidates Origin against cors.allowed_origins
MetricsRecords Prometheus metrics
AuthValidates Bearer token (protected routes only)