# 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`](https://gitea.dcglab.co.uk/steve/restic-manager/src/branch/main/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.