HTTP endpoints
A non-exhaustive map of the surfaces the control plane exposes.
All /api/* routes return JSON; all other paths render HTML
(server-rendered with HTMX in the loop).
The canonical wiring lives at
internal/server/http/server.go;
when in doubt, read the routes block there.
Public (no auth)
| Method |
Path |
Purpose |
| GET |
/healthz |
Liveness probe. Returns 204. |
| POST |
/api/auth/login |
Local-user login. JSON body: {username, password}. |
| POST |
/api/auth/logout |
Invalidate the session cookie. |
| POST |
/api/bootstrap |
First-run admin creation. Accepts the token printed at first start. |
| POST |
/api/agents/enroll |
Token-based agent enrolment. |
| POST |
/api/agents/announce |
Announce-and-approve agent enrolment. |
| GET |
/agent/binary?os=&arch= |
Serves the agent binary for the install scripts. |
| GET |
/install/* |
Serves the Linux + Windows install scripts and the systemd unit. |
| GET |
/api/version |
Build version + commit JSON. |
| GET |
/metrics |
Prometheus exposition (only when opted-in via RM_METRICS_TOKEN / RM_METRICS_TRUSTED_CIDR). |
| GET |
/login, /setup, /bootstrap |
UI pages. |
Authenticated (any role)
| Method |
Path |
Purpose |
| GET |
/ |
Dashboard. |
| GET |
/hosts/{id} |
Host detail. |
| GET |
/hosts/{id}/repo |
Repo tab. |
| GET |
/hosts/{id}/jobs |
Jobs tab. |
| GET |
/hosts/{id}/sources |
Source groups list. |
| GET |
/hosts/{id}/schedules |
Schedules list. |
| GET |
/jobs/{id} |
Live job log. |
| GET |
/api/hosts, /api/fleet/summary |
JSON list + summary. |
| GET |
/api/jobs/{id}/stream |
WebSocket subscription to a job's live log. |
| GET |
/api/jobs/{id}/log.{txt,ndjson} |
Persisted log download. |
Operator role and above
| Method |
Path |
Purpose |
| POST |
/hosts/{id}/run-backup |
Run-now (HTMX form-post). |
| POST |
/hosts/{id}/sources/{gid}/run-now |
Per-source-group run-now. |
| POST |
/hosts/{id}/repo/{prune,check,unlock,reinit,probe} |
Maintenance actions. |
| POST |
/api/hosts/{id}/snapshots/diff |
Snapshot-diff job. |
| POST |
/hosts/{id}/restore |
Restore wizard submit. |
| POST |
/api/jobs/{id}/cancel |
Cancel a running job. |
| POST |
/hosts/{id}/tags |
Update host tags. |
| POST |
/hosts/{id}/sources and friends |
Source-group CRUD. |
| POST |
/hosts/{id}/schedules and friends |
Schedule CRUD. |
| POST |
/hosts/{id}/repo/credentials, /admin-credentials |
Credential update. |
Admin role only
| Method |
Path |
Purpose |
| POST |
/hosts/new |
Mint enrolment token (Add host). |
| POST |
/hosts/{id}/delete |
Delete + cascade. |
| POST |
/hosts/{id}/update |
Dispatch a single agent update. |
| GET/POST |
/settings/users/... |
User management. |
| POST |
/settings/notifications/... |
Notification channel CRUD + test fire. |
| POST |
/settings/fleet-update/... |
Fleet-update worker. |
WebSocket
| Path |
Who connects |
Auth |
/ws/agent |
Agent |
Bearer token issued at enrolment. |
/ws/agent/pending |
Agent (announce flow) |
Pending-id query param. |
/api/jobs/{id}/stream |
Browser |
Session cookie. |
RBAC enforcement
Routes are grouped into chi route-groups by required role
(viewer < operator < admin); the requireRole middleware in
internal/server/http/middleware.go is the bouncer. Sessions
re-validate disabled_at on every request, so a disabled user's
cookie stops working immediately.
steve
89537d417a