# REST API and WebSocket Reference

All REST endpoints are nested under the `/api/v1` prefix.

---

## Authentication

The API supports two authentication mechanisms:
1. **Session Cookie**: `nx9_session=<SESSION_UUID>` (HttpOnly, SameSite=Strict).
2. **Bearer Token**: `Authorization: Bearer nx9_<TOKEN_BASE64>` (Hashed with SHA-256 on the server).

---

## Endpoints

### 1. Public Endpoints
- `POST /api/v1/auth/login`: Authenticates administrator with username and password. Sets session cookie.
- `GET /api/v1/system/health`: Service and database health check.
- `GET /api/v1/system/version`: Version and build metadata.
- `GET /api/v1/ws`: WebSocket real-time event stream.

### 2. Administrator & Session Management
- `POST /api/v1/auth/logout`: Invalidates the current session.
- `GET /api/v1/auth/session`: Returns information about the active session.
- `POST /api/v1/auth/password`: Changes password and terminates all other sessions.
- `GET /api/v1/auth/tokens`: Lists all provisioned API tokens.
- `POST /api/v1/auth/tokens`: Creates a new API token.
- `DELETE /api/v1/auth/tokens/{id}`: Revokes an API token.

### 3. WireGuard Interfaces
- `GET /api/v1/interfaces`: Lists all interfaces.
- `POST /api/v1/interfaces`: Creates an interface.
- `GET /api/v1/interfaces/{id}`: Interface details.
- `PUT /api/v1/interfaces/{id}`: Updates interface settings.
- `DELETE /api/v1/interfaces/{id}`: Deletes interface.
- `POST /api/v1/interfaces/{id}/enable`: Enables interface.
- `POST /api/v1/interfaces/{id}/disable`: Disables interface.
- `GET /api/v1/interfaces/{id}/status`: Live statistics, listen port, and connected peer metrics.

### 4. WireGuard Peers
- `GET /api/v1/interfaces/{id}/peers`: Lists peers for a specific interface.
- `POST /api/v1/interfaces/{id}/peers`: Enrolls a new peer.
- `GET /api/v1/peers/{id}`: Peer details.
- `PUT /api/v1/peers/{id}`: Updates peer configuration.
- `DELETE /api/v1/peers/{id}`: Deletes peer.
- `POST /api/v1/peers/{id}/enable`: Activates peer.
- `POST /api/v1/peers/{id}/disable`: Disables peer.
- `POST /api/v1/peers/{id}/revoke`: Revokes peer.
- `GET /api/v1/peers/{id}/config`: Downloads standard client `.conf` file.
- `GET /api/v1/peers/{id}/qr`: Returns SVG, PNG base64, and Data URL QR code representations.

### 5. Networks & Routing
- `GET /api/v1/networks`, `POST /api/v1/networks`, `DELETE /api/v1/networks/{id}`
- `GET /api/v1/routes`, `POST /api/v1/routes`, `DELETE /api/v1/routes/{id}`

### 6. Firewall & nftables
- `GET /api/v1/firewall/rules`, `POST /api/v1/firewall/rules`, `DELETE /api/v1/firewall/rules/{id}`
- `POST /api/v1/firewall/rules/{id}/enable`, `POST /api/v1/firewall/rules/{id}/disable`

### 7. Audit Log
- `GET /api/v1/audit`: Paginated and filtered query of security and system events.

### 8. Backups
- `GET /api/v1/backups`: Lists existing backup records.
- `POST /api/v1/backups/create`: Creates a new snapshot and manifest.
- `GET /api/v1/backups/{id}/download`: Downloads backup archive.
- `POST /api/v1/backups/{id}/restore`: Safely restores database.
- `DELETE /api/v1/backups/{id}`: Deletes backup archive and metadata.

### 9. Reconciliation
- `GET /api/v1/reconcile/plan`: Returns detected drift without making changes.
- `POST /api/v1/reconcile/apply`: Applies reconciliation plan to live kernel.

---

## WebSocket Telemetry (`/api/v1/ws`)

Upon connection, clients receive a stream of JSON `SystemEvent` frames:
- `InterfaceChanged { id, action }`
- `PeerChanged { id, action }`
- `NetworkChanged { id, action }`
- `RouteChanged { id, action }`
- `FirewallChanged { id, action }`
- `AuditEvent { event_type, message, resource_type, resource_id }`