Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
docs: correct API reference auth labels and add missing routes
rcourtman9031dd949c97
diff --git a/docs/API.md b/docs/API.mdindex 0761aa6c7c..21edce3d25 100644--- a/docs/API.md+++ b/docs/API.md@@ -171,7 +171,7 @@ Public endpoints include:- `GET /api/health`- `GET /api/version`- `GET /api/agent/version` (agent update checks)-- `GET /api/setup-script` (requires a setup token)+- `GET /api/setup-script` (public; the generated script prompts for its setup token at runtime and skips auto-registration if none is supplied)## π Scopes and Admin Access@@ -589,25 +589,27 @@ Response:### Resource MetadataUser notes, tags, and custom URLs for resources.-- `GET /api/agents/metadata` (admin or `monitoring:read`)-- `GET /api/agents/metadata/{agentId}` (admin or `monitoring:read`)-- `PUT /api/agents/metadata/{agentId}` (admin or `monitoring:write`)-- `DELETE /api/agents/metadata/{agentId}` (admin or `monitoring:write`)+These routes do not require admin access. Any authenticated browser session can call them, and API tokens need the scope shown.-- `GET /api/guests/metadata` (admin or `monitoring:read`)-- `GET /api/guests/metadata/{guestId}` (admin or `monitoring:read`)-- `PUT /api/guests/metadata/{guestId}` (admin or `monitoring:write`)-- `DELETE /api/guests/metadata/{guestId}` (admin or `monitoring:write`)+- `GET /api/agents/metadata` (`monitoring:read`)+- `GET /api/agents/metadata/{agentId}` (`monitoring:read`)+- `PUT /api/agents/metadata/{agentId}` (`monitoring:write`)+- `DELETE /api/agents/metadata/{agentId}` (`monitoring:write`)-- `GET /api/docker/metadata` (admin or `monitoring:read`)-- `GET /api/docker/metadata/{containerId}` (admin or `monitoring:read`)-- `PUT /api/docker/metadata/{containerId}` (admin or `monitoring:write`)-- `DELETE /api/docker/metadata/{containerId}` (admin or `monitoring:write`)+- `GET /api/guests/metadata` (`monitoring:read`)+- `GET /api/guests/metadata/{guestId}` (`monitoring:read`)+- `PUT /api/guests/metadata/{guestId}` (`monitoring:write`)+- `DELETE /api/guests/metadata/{guestId}` (`monitoring:write`)-- `GET /api/docker/runtimes/metadata` (admin or `monitoring:read`)-- `GET /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:read`)-- `PUT /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:write`)-- `DELETE /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:write`)+- `GET /api/docker/metadata` (`monitoring:read`)+- `GET /api/docker/metadata/{containerId}` (`monitoring:read`)+- `PUT /api/docker/metadata/{containerId}` (`monitoring:write`)+- `DELETE /api/docker/metadata/{containerId}` (`monitoring:write`)++- `GET /api/docker/runtimes/metadata` (`monitoring:read`)+- `GET /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:read`)+- `PUT /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:write`)+- `DELETE /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:write`)### Version Info`GET /api/version`@@ -891,8 +893,8 @@ Returns time-series data for CPU, Memory, and Storage.Returns storage chart data.### Storage Stats-`GET /api/storage/`-Detailed storage usage per node and pool.+`GET /api/storage/{storageId}` (`monitoring:read`)+Returns one storage resource by its `id`, wrapped as `{"data": {...}, "timestamp": 1700000000}`. The `data` object includes `id`, `name`, `node`, `instance`, `type`, `status`, `total`, `used`, `free`, `usage`, `content`, `shared`, `enabled` and `active`. Returns HTTP 404 with code `storage_not_found` for an unknown ID, and HTTP 405 for methods other than GET. A request without an ID (`GET /api/storage/`) returns HTTP 400 with code `missing_storage_id`.### Recovery (formerly Backups / Snapshots)Pulse v6 uses the recovery API to provide a platform-agnostic view of backup and snapshot artifacts.@@ -924,29 +926,29 @@ points, rollups, posture, and filter semantics.## π Notifications### Send Test Notification-`POST /api/notifications/test` (admin)-Triggers a test alert to all configured channels.+`POST /api/notifications/test` (admin, `settings:write`)+Sends one test notification through a single channel per request, not all configured channels. The JSON body `method` (or `type`) selects `email`, `webhook`, or `apprise` and uses the saved configuration. `webhookId` targets one specific saved webhook. `config` tests unsaved email or Apprise settings. If alert delivery is paused, the response includes `deliveryPaused: true`.### Email, Apprise, and Webhooks-- `GET /api/notifications/email` (admin)-- `PUT /api/notifications/email` (admin)-- `GET /api/notifications/apprise` (admin)-- `PUT /api/notifications/apprise` (admin)-- `GET /api/notifications/webhooks` (admin)-- `POST /api/notifications/webhooks` (admin)-- `PUT /api/notifications/webhooks/<id>` (admin)-- `DELETE /api/notifications/webhooks/<id>` (admin)-- `POST /api/notifications/webhooks/test` (admin)-- `GET /api/notifications/webhook-templates` (admin)-- `GET /api/notifications/webhook-history` (admin)-- `GET /api/notifications/email-providers` (admin)+- `GET /api/notifications/email` (admin, `settings:read`; `settings:write` also accepted)+- `PUT /api/notifications/email` (admin, `settings:write`)+- `GET /api/notifications/apprise` (admin, `settings:read`; `settings:write` also accepted)+- `PUT /api/notifications/apprise` (admin, `settings:write`)+- `GET /api/notifications/webhooks` (admin, `settings:read`; `settings:write` also accepted)+- `POST /api/notifications/webhooks` (admin, `settings:write`)+- `PUT /api/notifications/webhooks/<id>` (admin, `settings:write`)+- `DELETE /api/notifications/webhooks/<id>` (admin, `settings:write`)+- `POST /api/notifications/webhooks/test` (admin, `settings:write`)+- `GET /api/notifications/webhook-templates` (admin, `settings:read`; `settings:write` also accepted)+- `GET /api/notifications/webhook-history` (admin, `settings:read`; `settings:write` also accepted)+- `GET /api/notifications/email-providers` (admin, `settings:read`; `settings:write` also accepted)Email and webhook configurations accept optional `tagFilter` (an array ofresource-tag strings) and `tagFilterMode` (`"all"` or `"any"`). An omittedfield is preserved on update; an empty `tagFilter` clears routing and restoresdelivery for all resources.-- `GET /api/notifications/health` (admin)+- `GET /api/notifications/health` (admin, `settings:read`; `settings:write` also accepted)- Queue health is `degraded` whenever any retained `failed` or `dlq`delivery exists, and `unavailable` when queue state cannot be read.Recoverable failed attempts that returned to `pending` for retry do not@@ -1003,12 +1005,19 @@ Common reporting error codes:text. Completed attempts are retained for 7 days; dead-letter attempts areretained for 30 days, so the response reports both windows explicitly.- `limit` defaults to 50 and is capped at 200.-- `GET /api/notifications/queue/stats` (admin)+- `GET /api/notifications/queue/stats` (admin, `settings:read` and `monitoring:read`)- Returns counts for all rows still retained by the queue. Status counts havedifferent retention windows and are not a delivery rate or lifetime total.- `GET /api/notifications/dlq` (admin)- `POST /api/notifications/dlq/retry` (admin)-- `POST /api/notifications/dlq/delete` (admin)+- `POST /api/notifications/dlq/delete` (admin, `settings:write`; `DELETE` also accepted)+ - Body: `{ "id": "<notification id>" }`. Marks that queue row `cancelled`+ with the note "Manually deleted from DLQ"; the row is not removed and is+ retained for 7 days like other cancelled rows. The endpoint does not check+ that the row is in the dead-letter queue.+ - Returns `{ "success": true, "message": "Notification deleted from DLQ",+ "id": "<notification id>" }`. An empty or missing `id`, or an invalid JSON+ body, returns `400`. An unknown `id` returns `500`.- `POST /api/notifications/terminal-failures/retry` (admin, `settings:write`)- Returns every retained `failed` or `dlq` delivery to `pending` with a freshretry budget. Existing per-attempt delivery history is preserved.@@ -1079,20 +1088,31 @@ In Docker installs, the response includes a restart notice.{ "name": "ansible-script", "scopes": ["monitoring:read"] }```-### Edit API Token Scopes+### Edit API Token`PATCH /api/security/tokens/<id>````json{ "scopes": ["monitoring:read", "settings:read"] }```-The `scopes` field is required and must contain at least one known scope.-Wildcard access (`"*"`) cannot be combined with other scopes. The update takes-effect on the token's next request without changing its ID, secret, expiry, or-organization bindings.+Send `scopes`, `name`, or both; a body with neither returns 400. A rename-only+body such as `{ "name": "new-name" }` leaves the scopes unchanged, and a blank+`name` returns 400. When `scopes` is sent it must contain at least one known+scope, and wildcard access (`"*"`) cannot be combined with other scopes.+API-token callers that change scopes must already hold every existing scope on+the target token and every scope they request. The update takes effect on the+token's next request without changing its ID, secret, expiry, or organization+bindings.### Revoke Token`DELETE /api/security/tokens/<id>`+### Validate API Token (admin session or `settings:write` token)+`POST /api/security/validate-token`+```json+{ "token": "raw-token" }+```+Returns `{ "valid": true, "message": "Token is valid" }` for a known, unexpired token. An unknown or expired token returns HTTP 200 with `"valid": false` and `"message": "Token is invalid"`. An empty `token` returns HTTP 400 with `"valid": false` and `"message": "Token is required"`. When no API tokens are configured, the response is HTTP 200 with `"valid": false` and `"message": "API token authentication is not configured"`. API-token callers need the `settings:write` scope; a token without it gets HTTP 403. Non-admin proxy-auth callers get HTTP 403. Requests over the rate limit get HTTP 429. A successful validation updates the token's last-used time. This endpoint is not gated by the Pro audit licence.+### Recovery (Localhost or Recovery Token)`POST /api/security/recovery`Supports actions:@@ -1102,12 +1122,12 @@ Supports actions:`GET /api/security/recovery` returns recovery mode status.-### Reset Account Lockout (Admin)-`POST /api/security/reset-lockout`+### Reset Account Lockout (Admin or settings:write token)+`POST /api/security/reset-lockout` (admin, `settings:write`)```json{ "identifier": "admin" }```-Identifier can be a username or IP address.+Callers need an admin session, or an API token with the `settings:write` scope; a token without that scope gets `403` with `error: "missing_scope"`. Identifier can be a username or IP address. An empty identifier returns `400 missing_identifier`. Success returns `{ "success": true, "message": "Lockout reset for admin" }`.### Regenerate API Token (Admin)`POST /api/security/regenerate-token`@@ -1165,16 +1185,6 @@ Response:}```-### Validate API Token (Admin)-`POST /api/security/validate-token`-```json-{ "token": "raw-token" }-```-Returns:-```json-{ "valid": true, "message": "Token is valid" }-```-### Bootstrap Token Validation (Public)`POST /api/security/validate-bootstrap-token`@@ -1287,11 +1297,11 @@ Returns minimal server info for installer scripts.OIDC and SAML configuration is managed via SSO providers.### SSO Provider Management (Community)-- `GET /api/security/sso/providers` (admin)-- `POST /api/security/sso/providers` (admin)-- `GET /api/security/sso/providers/{id}` (admin)-- `PUT /api/security/sso/providers/{id}` (admin)-- `DELETE /api/security/sso/providers/{id}` (admin)+- `GET /api/security/sso/providers` (admin, `settings:read`)+- `POST /api/security/sso/providers` (admin, `settings:write`)+- `GET /api/security/sso/providers/{id}` (admin, `settings:read`)+- `PUT /api/security/sso/providers/{id}` (admin, `settings:write`)+- `DELETE /api/security/sso/providers/{id}` (admin, `settings:write`)Provider mutation request contract:- Max request body: 1MB.@@ -1300,8 +1310,8 @@ Provider mutation request contract:- OIDC and SAML providers are included with the Community SSO entitlement.### SSO Test and Metadata Preview (Community)-- `POST /api/security/sso/providers/test` (admin)-- `POST /api/security/sso/providers/metadata/preview` (admin)+- `POST /api/security/sso/providers/test` (admin, `settings:write`)+- `POST /api/security/sso/providers/metadata/preview` (admin, `settings:read`)Test/preview request contract:- Max request body: 32KB.@@ -1318,13 +1328,13 @@ Test/preview request contract:### License Features (Authenticated)`GET /api/license/features`-### Activate License (Admin)+### Activate License (Admin, `settings:write`)`POST /api/license/activate````json{ "license_key": "PASTE_KEY_HERE" }```-### Clear License (Admin)+### Clear License (Admin, `settings:write`)`POST /api/license/clear`---@@ -1597,6 +1607,12 @@ Runs a focused investigation for an alert payload (used by the UI).`409 patrol_objective_revision_conflict`.- `GET /api/ai/patrol/history`- `GET /api/ai/patrol/runs`+- `GET /api/ai/patrol/runs/{id}` (`ai:execute`)+ - Returns one retained Patrol run by the `id` from `GET /api/ai/patrol/runs`.+ Percent-encode the ID in the path. Tool-call arrays are omitted unless+ `?include=tool_calls`. Returns `400` when the ID is empty, `404`+ (`not_found`) when no retained run has that ID, and `503`+ (`service_unavailable`) when the Patrol service is unavailable.- `GET /api/ai/patrol/stream` (Pro)- `POST /api/ai/patrol/run` (admin, Pro)- `POST /api/ai/patrol/acknowledge` (Pro)@@ -1628,14 +1644,9 @@ Runs a focused investigation for an alert payload (used by the UI).### Remediation Plans (Pro)- `GET /api/ai/remediation/plans`- `GET /api/ai/remediation/plan?plan_id=<id>`-- `POST /api/ai/remediation/approve`-- `POST /api/ai/remediation/execute`-- `POST /api/ai/remediation/rollback`--Request bodies:-- `approve`: `{ "plan_id": "...", "approved_by": "api" }`-- `execute`: `{ "execution_id": "..." }`-- `rollback`: `{ "execution_id": "..." }`+- `POST /api/ai/remediation/approve` (`ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response; approve typed actions through `POST /api/actions/{id}/decision` (`actions:approve`) instead)+- `POST /api/ai/remediation/execute` (admin, `ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response)+- `POST /api/ai/remediation/rollback` (admin, `ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response; no rollback runs through this endpoint)### Intelligence & Forecasting- `GET /api/ai/intelligence`@@ -1753,6 +1764,9 @@ Unlinks an agent from a node.`DELETE /api/agents/agent/{agent_id}` (admin, `settings:write`)Removes an agent from state.+`POST /api/agents/agent/{agent_id}/allow-reenroll` (admin, `settings:write`)+Clears the removal block left by `DELETE /api/agents/agent/{agent_id}` so the agent can report again. Returns `{"success": true, "agentId": "<agent_id>"}`. Other methods return `405`.+### Agent Linking (Admin)- `POST /api/agents/agent/link` (admin, `settings:write`)- `POST /api/agents/agent/unlink` (admin, `settings:write`)@@ -1812,22 +1826,24 @@ These routes manage Docker / Podman telemetry and container actions reported by- `PUT /api/agents/kubernetes/clusters/{clusterId}/display-name` (`kubernetes:manage`)### Agent Profiles (Pro)-`GET /api/admin/profiles` (admin, Pro)-`POST /api/admin/profiles` (admin, Pro)-`GET /api/admin/profiles/{id}` (admin, Pro)-`PUT /api/admin/profiles/{id}` (admin, Pro)-`DELETE /api/admin/profiles/{id}` (admin, Pro)-`GET /api/admin/profiles/schema` (admin, Pro)-`POST /api/admin/profiles/validate` (admin, Pro)-`POST /api/admin/profiles/suggestions` (admin, Pro)-`GET /api/admin/profiles/changelog` (admin, Pro)-`GET /api/admin/profiles/deployments` (admin, Pro)-`POST /api/admin/profiles/deployments` (admin, Pro)-`GET /api/admin/profiles/{id}/versions` (admin, Pro)-`POST /api/admin/profiles/{id}/rollback/{version}` (admin, Pro)-`GET /api/admin/profiles/assignments` (admin, Pro)-`POST /api/admin/profiles/assignments` (admin, Pro)-`DELETE /api/admin/profiles/assignments/{agent_id}` (admin, Pro)+`GET /api/admin/profiles/` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`PUT /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`DELETE /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/schema` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/validate` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/suggestions` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/changelog` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/deployments` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/deployments` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/{id}/versions` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/{id}/rollback/{version}` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/assignments` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/assignments` (admin, `settings:write`, Pro)+`DELETE /api/admin/profiles/assignments/{agent_id}` (admin, `settings:write`, Pro)++Every profile route requires admin access and the `agent_profiles` licence feature (HTTP 402 when unlicensed). Token callers also need `settings:write` on every profile route, including GET requests; session requests are not subject to the token scope check. Use the trailing slash on the collection path; the path without it is redirected, not served.---@@ -1840,12 +1856,12 @@ the API for automation.### Target Management-- `GET /api/availability-targets` (`settings:read`) - List configured targets and latest probe status.-- `POST /api/availability-targets` (`settings:write`) - Add a target.-- `PUT /api/availability-targets/{id}` (`settings:write`) - Update a target.-- `DELETE /api/availability-targets/{id}` (`settings:write`) - Remove a target.-- `POST /api/availability-targets/test` (`settings:write`) - Test an unsaved target.-- `POST /api/availability-targets/{id}/test` (`settings:write`) - Test a saved target.+- `GET /api/availability-targets` (admin, `settings:read`) - List configured targets and latest probe status.+- `POST /api/availability-targets` (admin, `settings:write`) - Add a target.+- `PUT /api/availability-targets/{id}` (admin, `settings:write`) - Update a target.+- `DELETE /api/availability-targets/{id}` (admin, `settings:write`) - Remove a target.+- `POST /api/availability-targets/test` (admin, `settings:write`) - Test an unsaved target. If the body includes the `id` of a saved target, that target's stored HTTP credentials are reused, but only while the HTTP scheme, host and port are unchanged.+- `POST /api/availability-targets/{id}/test` (admin, `settings:write`) - Test a saved target.Target payload fields:@@ -1896,6 +1912,14 @@ Example ping-only target:The create response and subsequent reads return `"protocol": "icmp"`.+### History++- `POST /api/availability-history` (`monitoring:read`) - Recent state and latency history for up to 200 availability targets in one request. Body: `{"targetIds": ["<target-id>"], "range": "24h"}`. `targetIds` is required; blank and duplicate IDs are dropped, and at most 200 unique IDs are accepted. `range` is optional (default `24h`). Allowed ranges are `1h`, `6h`, `12h`, `24h`, `7d`, `14d`, `30d`, `90d`, and `365d`. A range longer than the licence's metrics history retention returns `402` (free tier: 7 days). Non-POST methods return `405`.++Response (`200`): `start` and `end` (UTC, end truncated to the minute) and `targets`. Each target has `targetId` and either `summary` (`reachableSeconds`, `unreachableSeconds`, `indeterminateSeconds`, `unknownSeconds`, `coveragePercent`, optional `availabilityPercent`, optional `reachableLatencyMillis`) with `buckets` (at most 120) and, only when present, `revisionBoundaries`; or an `error` with code `not_found` when the ID is not a configured target. An unknown ID does not fail the batch.++Errors: `400` with `invalid_request` (malformed JSON, unknown fields, or body over 32 KiB), `missing_target_ids`, `too_many_target_ids`, or `invalid_range`. Server-side failures return `500` or `503` with a typed error code.+---## π TrueNAS@@ -1906,7 +1930,9 @@ TrueNAS connection management endpoints for adding, testing, and removing TrueNA- `GET /api/truenas/connections` (admin, `settings:read`) β List configured TrueNAS connections.- `POST /api/truenas/connections` (admin, `settings:write`) β Add a new TrueNAS connection.- `POST /api/truenas/connections/test` (admin, `settings:write`) β Test a TrueNAS connection before saving.+- `POST /api/truenas/connections/{id}/test` (admin, `settings:write`) β Live-test a saved connection with its stored credentials. An optional JSON body overrides fields for this test only and is not saved. Returns `404` (`truenas_not_found`) for an unknown ID and `400` (`truenas_invalid_config` or `truenas_connection_failed`) on failure. The probe does not clear poll errors or advance poll freshness, so check the `poll` field from `GET /api/truenas/connections` to see whether ordinary polling has recovered.- `DELETE /api/truenas/connections/{id}` (admin, `settings:write`) β Remove a TrueNAS connection.+- `PUT /api/truenas/connections/{id}` (admin, `settings:write`) β Update a saved TrueNAS connection. Send only the fields to change in a private JSON file; omitted fields keep their stored values. A masked `apiKey` or `password` returned by a GET response is kept from the stored record, so never send a masked value as a new secret. Saving does not test the connection. Setting `monitorDatasets`, `monitorPools` and `monitorReplication` all to `false` is saved as all enabled. Returns 200 with the redacted connection, 400 `validation_error`, 404 `truenas_not_found`, or 403 `mock_mode_enabled` in mock mode.TrueNAS resources (pools, datasets, disks, ZFS snapshots, replication tasks, alerts) are surfaced through the unified `/api/resources` endpoint with `source=truenas`.@@ -1918,10 +1944,10 @@ End-to-end encrypted relay protocol for mobile connectivity.> Relay pairing endpoints generate the QR code and deep link used by supported Pulse Mobile clients.-### Relay Configuration (Admin, Relay and Above)-- `GET /api/settings/relay` (admin, `settings:read`, Relay+) β Get current relay configuration.-- `PUT /api/settings/relay` (admin, `settings:write`, Relay+) β Update relay configuration.-- `GET /api/settings/relay/status` (admin, `settings:read`, Relay+) β Get relay connection status.+### Relay Configuration (Relay and Above; admin session or scoped token)+- `GET /api/settings/relay` (`settings:read` token scope, or admin session, Relay+) β Get current relay configuration.+- `PUT /api/settings/relay` (`settings:write` token scope, or admin session, Relay+) β Update relay configuration.+- `GET /api/settings/relay/status` (`settings:read` token scope, or admin session, Relay+) β Get relay connection status.### Mobile Onboarding- `GET /api/onboarding/qr` (`settings:read`) β Generate QR code for Pulse Mobile pairing.diff --git a/docs/TRUENAS.md b/docs/TRUENAS.mdindex 8bd672a1e0..0412b62e55 100644--- a/docs/TRUENAS.md+++ b/docs/TRUENAS.md@@ -133,6 +133,7 @@ All endpoints require admin authentication.| `GET` | `/api/truenas/connections` | List all configured TrueNAS connections || `POST` | `/api/truenas/connections` | Add a new TrueNAS connection || `DELETE` | `/api/truenas/connections/{id}` | Remove a TrueNAS connection |+| `PUT` | `/api/truenas/connections/{id}` | Update a saved connection; send only the fields to change, and never a masked secret || `POST` | `/api/truenas/connections/test` | Test a connection before saving |### Testing and adding a connection (API)diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.mdindex 0761aa6c7c..21edce3d25 100644--- a/frontend-modern/public/docs/API.md+++ b/frontend-modern/public/docs/API.md@@ -171,7 +171,7 @@ Public endpoints include:- `GET /api/health`- `GET /api/version`- `GET /api/agent/version` (agent update checks)-- `GET /api/setup-script` (requires a setup token)+- `GET /api/setup-script` (public; the generated script prompts for its setup token at runtime and skips auto-registration if none is supplied)## π Scopes and Admin Access@@ -589,25 +589,27 @@ Response:### Resource MetadataUser notes, tags, and custom URLs for resources.-- `GET /api/agents/metadata` (admin or `monitoring:read`)-- `GET /api/agents/metadata/{agentId}` (admin or `monitoring:read`)-- `PUT /api/agents/metadata/{agentId}` (admin or `monitoring:write`)-- `DELETE /api/agents/metadata/{agentId}` (admin or `monitoring:write`)+These routes do not require admin access. Any authenticated browser session can call them, and API tokens need the scope shown.-- `GET /api/guests/metadata` (admin or `monitoring:read`)-- `GET /api/guests/metadata/{guestId}` (admin or `monitoring:read`)-- `PUT /api/guests/metadata/{guestId}` (admin or `monitoring:write`)-- `DELETE /api/guests/metadata/{guestId}` (admin or `monitoring:write`)+- `GET /api/agents/metadata` (`monitoring:read`)+- `GET /api/agents/metadata/{agentId}` (`monitoring:read`)+- `PUT /api/agents/metadata/{agentId}` (`monitoring:write`)+- `DELETE /api/agents/metadata/{agentId}` (`monitoring:write`)-- `GET /api/docker/metadata` (admin or `monitoring:read`)-- `GET /api/docker/metadata/{containerId}` (admin or `monitoring:read`)-- `PUT /api/docker/metadata/{containerId}` (admin or `monitoring:write`)-- `DELETE /api/docker/metadata/{containerId}` (admin or `monitoring:write`)+- `GET /api/guests/metadata` (`monitoring:read`)+- `GET /api/guests/metadata/{guestId}` (`monitoring:read`)+- `PUT /api/guests/metadata/{guestId}` (`monitoring:write`)+- `DELETE /api/guests/metadata/{guestId}` (`monitoring:write`)-- `GET /api/docker/runtimes/metadata` (admin or `monitoring:read`)-- `GET /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:read`)-- `PUT /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:write`)-- `DELETE /api/docker/runtimes/metadata/{runtimeId}` (admin or `monitoring:write`)+- `GET /api/docker/metadata` (`monitoring:read`)+- `GET /api/docker/metadata/{containerId}` (`monitoring:read`)+- `PUT /api/docker/metadata/{containerId}` (`monitoring:write`)+- `DELETE /api/docker/metadata/{containerId}` (`monitoring:write`)++- `GET /api/docker/runtimes/metadata` (`monitoring:read`)+- `GET /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:read`)+- `PUT /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:write`)+- `DELETE /api/docker/runtimes/metadata/{runtimeId}` (`monitoring:write`)### Version Info`GET /api/version`@@ -891,8 +893,8 @@ Returns time-series data for CPU, Memory, and Storage.Returns storage chart data.### Storage Stats-`GET /api/storage/`-Detailed storage usage per node and pool.+`GET /api/storage/{storageId}` (`monitoring:read`)+Returns one storage resource by its `id`, wrapped as `{"data": {...}, "timestamp": 1700000000}`. The `data` object includes `id`, `name`, `node`, `instance`, `type`, `status`, `total`, `used`, `free`, `usage`, `content`, `shared`, `enabled` and `active`. Returns HTTP 404 with code `storage_not_found` for an unknown ID, and HTTP 405 for methods other than GET. A request without an ID (`GET /api/storage/`) returns HTTP 400 with code `missing_storage_id`.### Recovery (formerly Backups / Snapshots)Pulse v6 uses the recovery API to provide a platform-agnostic view of backup and snapshot artifacts.@@ -924,29 +926,29 @@ points, rollups, posture, and filter semantics.## π Notifications### Send Test Notification-`POST /api/notifications/test` (admin)-Triggers a test alert to all configured channels.+`POST /api/notifications/test` (admin, `settings:write`)+Sends one test notification through a single channel per request, not all configured channels. The JSON body `method` (or `type`) selects `email`, `webhook`, or `apprise` and uses the saved configuration. `webhookId` targets one specific saved webhook. `config` tests unsaved email or Apprise settings. If alert delivery is paused, the response includes `deliveryPaused: true`.### Email, Apprise, and Webhooks-- `GET /api/notifications/email` (admin)-- `PUT /api/notifications/email` (admin)-- `GET /api/notifications/apprise` (admin)-- `PUT /api/notifications/apprise` (admin)-- `GET /api/notifications/webhooks` (admin)-- `POST /api/notifications/webhooks` (admin)-- `PUT /api/notifications/webhooks/<id>` (admin)-- `DELETE /api/notifications/webhooks/<id>` (admin)-- `POST /api/notifications/webhooks/test` (admin)-- `GET /api/notifications/webhook-templates` (admin)-- `GET /api/notifications/webhook-history` (admin)-- `GET /api/notifications/email-providers` (admin)+- `GET /api/notifications/email` (admin, `settings:read`; `settings:write` also accepted)+- `PUT /api/notifications/email` (admin, `settings:write`)+- `GET /api/notifications/apprise` (admin, `settings:read`; `settings:write` also accepted)+- `PUT /api/notifications/apprise` (admin, `settings:write`)+- `GET /api/notifications/webhooks` (admin, `settings:read`; `settings:write` also accepted)+- `POST /api/notifications/webhooks` (admin, `settings:write`)+- `PUT /api/notifications/webhooks/<id>` (admin, `settings:write`)+- `DELETE /api/notifications/webhooks/<id>` (admin, `settings:write`)+- `POST /api/notifications/webhooks/test` (admin, `settings:write`)+- `GET /api/notifications/webhook-templates` (admin, `settings:read`; `settings:write` also accepted)+- `GET /api/notifications/webhook-history` (admin, `settings:read`; `settings:write` also accepted)+- `GET /api/notifications/email-providers` (admin, `settings:read`; `settings:write` also accepted)Email and webhook configurations accept optional `tagFilter` (an array ofresource-tag strings) and `tagFilterMode` (`"all"` or `"any"`). An omittedfield is preserved on update; an empty `tagFilter` clears routing and restoresdelivery for all resources.-- `GET /api/notifications/health` (admin)+- `GET /api/notifications/health` (admin, `settings:read`; `settings:write` also accepted)- Queue health is `degraded` whenever any retained `failed` or `dlq`delivery exists, and `unavailable` when queue state cannot be read.Recoverable failed attempts that returned to `pending` for retry do not@@ -1003,12 +1005,19 @@ Common reporting error codes:text. Completed attempts are retained for 7 days; dead-letter attempts areretained for 30 days, so the response reports both windows explicitly.- `limit` defaults to 50 and is capped at 200.-- `GET /api/notifications/queue/stats` (admin)+- `GET /api/notifications/queue/stats` (admin, `settings:read` and `monitoring:read`)- Returns counts for all rows still retained by the queue. Status counts havedifferent retention windows and are not a delivery rate or lifetime total.- `GET /api/notifications/dlq` (admin)- `POST /api/notifications/dlq/retry` (admin)-- `POST /api/notifications/dlq/delete` (admin)+- `POST /api/notifications/dlq/delete` (admin, `settings:write`; `DELETE` also accepted)+ - Body: `{ "id": "<notification id>" }`. Marks that queue row `cancelled`+ with the note "Manually deleted from DLQ"; the row is not removed and is+ retained for 7 days like other cancelled rows. The endpoint does not check+ that the row is in the dead-letter queue.+ - Returns `{ "success": true, "message": "Notification deleted from DLQ",+ "id": "<notification id>" }`. An empty or missing `id`, or an invalid JSON+ body, returns `400`. An unknown `id` returns `500`.- `POST /api/notifications/terminal-failures/retry` (admin, `settings:write`)- Returns every retained `failed` or `dlq` delivery to `pending` with a freshretry budget. Existing per-attempt delivery history is preserved.@@ -1079,20 +1088,31 @@ In Docker installs, the response includes a restart notice.{ "name": "ansible-script", "scopes": ["monitoring:read"] }```-### Edit API Token Scopes+### Edit API Token`PATCH /api/security/tokens/<id>````json{ "scopes": ["monitoring:read", "settings:read"] }```-The `scopes` field is required and must contain at least one known scope.-Wildcard access (`"*"`) cannot be combined with other scopes. The update takes-effect on the token's next request without changing its ID, secret, expiry, or-organization bindings.+Send `scopes`, `name`, or both; a body with neither returns 400. A rename-only+body such as `{ "name": "new-name" }` leaves the scopes unchanged, and a blank+`name` returns 400. When `scopes` is sent it must contain at least one known+scope, and wildcard access (`"*"`) cannot be combined with other scopes.+API-token callers that change scopes must already hold every existing scope on+the target token and every scope they request. The update takes effect on the+token's next request without changing its ID, secret, expiry, or organization+bindings.### Revoke Token`DELETE /api/security/tokens/<id>`+### Validate API Token (admin session or `settings:write` token)+`POST /api/security/validate-token`+```json+{ "token": "raw-token" }+```+Returns `{ "valid": true, "message": "Token is valid" }` for a known, unexpired token. An unknown or expired token returns HTTP 200 with `"valid": false` and `"message": "Token is invalid"`. An empty `token` returns HTTP 400 with `"valid": false` and `"message": "Token is required"`. When no API tokens are configured, the response is HTTP 200 with `"valid": false` and `"message": "API token authentication is not configured"`. API-token callers need the `settings:write` scope; a token without it gets HTTP 403. Non-admin proxy-auth callers get HTTP 403. Requests over the rate limit get HTTP 429. A successful validation updates the token's last-used time. This endpoint is not gated by the Pro audit licence.+### Recovery (Localhost or Recovery Token)`POST /api/security/recovery`Supports actions:@@ -1102,12 +1122,12 @@ Supports actions:`GET /api/security/recovery` returns recovery mode status.-### Reset Account Lockout (Admin)-`POST /api/security/reset-lockout`+### Reset Account Lockout (Admin or settings:write token)+`POST /api/security/reset-lockout` (admin, `settings:write`)```json{ "identifier": "admin" }```-Identifier can be a username or IP address.+Callers need an admin session, or an API token with the `settings:write` scope; a token without that scope gets `403` with `error: "missing_scope"`. Identifier can be a username or IP address. An empty identifier returns `400 missing_identifier`. Success returns `{ "success": true, "message": "Lockout reset for admin" }`.### Regenerate API Token (Admin)`POST /api/security/regenerate-token`@@ -1165,16 +1185,6 @@ Response:}```-### Validate API Token (Admin)-`POST /api/security/validate-token`-```json-{ "token": "raw-token" }-```-Returns:-```json-{ "valid": true, "message": "Token is valid" }-```-### Bootstrap Token Validation (Public)`POST /api/security/validate-bootstrap-token`@@ -1287,11 +1297,11 @@ Returns minimal server info for installer scripts.OIDC and SAML configuration is managed via SSO providers.### SSO Provider Management (Community)-- `GET /api/security/sso/providers` (admin)-- `POST /api/security/sso/providers` (admin)-- `GET /api/security/sso/providers/{id}` (admin)-- `PUT /api/security/sso/providers/{id}` (admin)-- `DELETE /api/security/sso/providers/{id}` (admin)+- `GET /api/security/sso/providers` (admin, `settings:read`)+- `POST /api/security/sso/providers` (admin, `settings:write`)+- `GET /api/security/sso/providers/{id}` (admin, `settings:read`)+- `PUT /api/security/sso/providers/{id}` (admin, `settings:write`)+- `DELETE /api/security/sso/providers/{id}` (admin, `settings:write`)Provider mutation request contract:- Max request body: 1MB.@@ -1300,8 +1310,8 @@ Provider mutation request contract:- OIDC and SAML providers are included with the Community SSO entitlement.### SSO Test and Metadata Preview (Community)-- `POST /api/security/sso/providers/test` (admin)-- `POST /api/security/sso/providers/metadata/preview` (admin)+- `POST /api/security/sso/providers/test` (admin, `settings:write`)+- `POST /api/security/sso/providers/metadata/preview` (admin, `settings:read`)Test/preview request contract:- Max request body: 32KB.@@ -1318,13 +1328,13 @@ Test/preview request contract:### License Features (Authenticated)`GET /api/license/features`-### Activate License (Admin)+### Activate License (Admin, `settings:write`)`POST /api/license/activate````json{ "license_key": "PASTE_KEY_HERE" }```-### Clear License (Admin)+### Clear License (Admin, `settings:write`)`POST /api/license/clear`---@@ -1597,6 +1607,12 @@ Runs a focused investigation for an alert payload (used by the UI).`409 patrol_objective_revision_conflict`.- `GET /api/ai/patrol/history`- `GET /api/ai/patrol/runs`+- `GET /api/ai/patrol/runs/{id}` (`ai:execute`)+ - Returns one retained Patrol run by the `id` from `GET /api/ai/patrol/runs`.+ Percent-encode the ID in the path. Tool-call arrays are omitted unless+ `?include=tool_calls`. Returns `400` when the ID is empty, `404`+ (`not_found`) when no retained run has that ID, and `503`+ (`service_unavailable`) when the Patrol service is unavailable.- `GET /api/ai/patrol/stream` (Pro)- `POST /api/ai/patrol/run` (admin, Pro)- `POST /api/ai/patrol/acknowledge` (Pro)@@ -1628,14 +1644,9 @@ Runs a focused investigation for an alert payload (used by the UI).### Remediation Plans (Pro)- `GET /api/ai/remediation/plans`- `GET /api/ai/remediation/plan?plan_id=<id>`-- `POST /api/ai/remediation/approve`-- `POST /api/ai/remediation/execute`-- `POST /api/ai/remediation/rollback`--Request bodies:-- `approve`: `{ "plan_id": "...", "approved_by": "api" }`-- `execute`: `{ "execution_id": "..." }`-- `rollback`: `{ "execution_id": "..." }`+- `POST /api/ai/remediation/approve` (`ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response; approve typed actions through `POST /api/actions/{id}/decision` (`actions:approve`) instead)+- `POST /api/ai/remediation/execute` (admin, `ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response)+- `POST /api/ai/remediation/rollback` (admin, `ai:execute`; retired: on Pro builds it always returns `410 Gone` with error code `command_remediation_retired` after the licence, method and scope checks, and community builds return a licence-required response; no rollback runs through this endpoint)### Intelligence & Forecasting- `GET /api/ai/intelligence`@@ -1753,6 +1764,9 @@ Unlinks an agent from a node.`DELETE /api/agents/agent/{agent_id}` (admin, `settings:write`)Removes an agent from state.+`POST /api/agents/agent/{agent_id}/allow-reenroll` (admin, `settings:write`)+Clears the removal block left by `DELETE /api/agents/agent/{agent_id}` so the agent can report again. Returns `{"success": true, "agentId": "<agent_id>"}`. Other methods return `405`.+### Agent Linking (Admin)- `POST /api/agents/agent/link` (admin, `settings:write`)- `POST /api/agents/agent/unlink` (admin, `settings:write`)@@ -1812,22 +1826,24 @@ These routes manage Docker / Podman telemetry and container actions reported by- `PUT /api/agents/kubernetes/clusters/{clusterId}/display-name` (`kubernetes:manage`)### Agent Profiles (Pro)-`GET /api/admin/profiles` (admin, Pro)-`POST /api/admin/profiles` (admin, Pro)-`GET /api/admin/profiles/{id}` (admin, Pro)-`PUT /api/admin/profiles/{id}` (admin, Pro)-`DELETE /api/admin/profiles/{id}` (admin, Pro)-`GET /api/admin/profiles/schema` (admin, Pro)-`POST /api/admin/profiles/validate` (admin, Pro)-`POST /api/admin/profiles/suggestions` (admin, Pro)-`GET /api/admin/profiles/changelog` (admin, Pro)-`GET /api/admin/profiles/deployments` (admin, Pro)-`POST /api/admin/profiles/deployments` (admin, Pro)-`GET /api/admin/profiles/{id}/versions` (admin, Pro)-`POST /api/admin/profiles/{id}/rollback/{version}` (admin, Pro)-`GET /api/admin/profiles/assignments` (admin, Pro)-`POST /api/admin/profiles/assignments` (admin, Pro)-`DELETE /api/admin/profiles/assignments/{agent_id}` (admin, Pro)+`GET /api/admin/profiles/` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`PUT /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`DELETE /api/admin/profiles/{id}` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/schema` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/validate` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/suggestions` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/changelog` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/deployments` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/deployments` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/{id}/versions` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/{id}/rollback/{version}` (admin, `settings:write`, Pro)+`GET /api/admin/profiles/assignments` (admin, `settings:write`, Pro)+`POST /api/admin/profiles/assignments` (admin, `settings:write`, Pro)+`DELETE /api/admin/profiles/assignments/{agent_id}` (admin, `settings:write`, Pro)++Every profile route requires admin access and the `agent_profiles` licence feature (HTTP 402 when unlicensed). Token callers also need `settings:write` on every profile route, including GET requests; session requests are not subject to the token scope check. Use the trailing slash on the collection path; the path without it is redirected, not served.---@@ -1840,12 +1856,12 @@ the API for automation.### Target Management-- `GET /api/availability-targets` (`settings:read`) - List configured targets and latest probe status.-- `POST /api/availability-targets` (`settings:write`) - Add a target.-- `PUT /api/availability-targets/{id}` (`settings:write`) - Update a target.-- `DELETE /api/availability-targets/{id}` (`settings:write`) - Remove a target.-- `POST /api/availability-targets/test` (`settings:write`) - Test an unsaved target.-- `POST /api/availability-targets/{id}/test` (`settings:write`) - Test a saved target.+- `GET /api/availability-targets` (admin, `settings:read`) - List configured targets and latest probe status.+- `POST /api/availability-targets` (admin, `settings:write`) - Add a target.+- `PUT /api/availability-targets/{id}` (admin, `settings:write`) - Update a target.+- `DELETE /api/availability-targets/{id}` (admin, `settings:write`) - Remove a target.+- `POST /api/availability-targets/test` (admin, `settings:write`) - Test an unsaved target. If the body includes the `id` of a saved target, that target's stored HTTP credentials are reused, but only while the HTTP scheme, host and port are unchanged.+- `POST /api/availability-targets/{id}/test` (admin, `settings:write`) - Test a saved target.Target payload fields:@@ -1896,6 +1912,14 @@ Example ping-only target:The create response and subsequent reads return `"protocol": "icmp"`.+### History++- `POST /api/availability-history` (`monitoring:read`) - Recent state and latency history for up to 200 availability targets in one request. Body: `{"targetIds": ["<target-id>"], "range": "24h"}`. `targetIds` is required; blank and duplicate IDs are dropped, and at most 200 unique IDs are accepted. `range` is optional (default `24h`). Allowed ranges are `1h`, `6h`, `12h`, `24h`, `7d`, `14d`, `30d`, `90d`, and `365d`. A range longer than the licence's metrics history retention returns `402` (free tier: 7 days). Non-POST methods return `405`.++Response (`200`): `start` and `end` (UTC, end truncated to the minute) and `targets`. Each target has `targetId` and either `summary` (`reachableSeconds`, `unreachableSeconds`, `indeterminateSeconds`, `unknownSeconds`, `coveragePercent`, optional `availabilityPercent`, optional `reachableLatencyMillis`) with `buckets` (at most 120) and, only when present, `revisionBoundaries`; or an `error` with code `not_found` when the ID is not a configured target. An unknown ID does not fail the batch.++Errors: `400` with `invalid_request` (malformed JSON, unknown fields, or body over 32 KiB), `missing_target_ids`, `too_many_target_ids`, or `invalid_range`. Server-side failures return `500` or `503` with a typed error code.+---## π TrueNAS@@ -1906,7 +1930,9 @@ TrueNAS connection management endpoints for adding, testing, and removing TrueNA- `GET /api/truenas/connections` (admin, `settings:read`) β List configured TrueNAS connections.- `POST /api/truenas/connections` (admin, `settings:write`) β Add a new TrueNAS connection.- `POST /api/truenas/connections/test` (admin, `settings:write`) β Test a TrueNAS connection before saving.+- `POST /api/truenas/connections/{id}/test` (admin, `settings:write`) β Live-test a saved connection with its stored credentials. An optional JSON body overrides fields for this test only and is not saved. Returns `404` (`truenas_not_found`) for an unknown ID and `400` (`truenas_invalid_config` or `truenas_connection_failed`) on failure. The probe does not clear poll errors or advance poll freshness, so check the `poll` field from `GET /api/truenas/connections` to see whether ordinary polling has recovered.- `DELETE /api/truenas/connections/{id}` (admin, `settings:write`) β Remove a TrueNAS connection.+- `PUT /api/truenas/connections/{id}` (admin, `settings:write`) β Update a saved TrueNAS connection. Send only the fields to change in a private JSON file; omitted fields keep their stored values. A masked `apiKey` or `password` returned by a GET response is kept from the stored record, so never send a masked value as a new secret. Saving does not test the connection. Setting `monitorDatasets`, `monitorPools` and `monitorReplication` all to `false` is saved as all enabled. Returns 200 with the redacted connection, 400 `validation_error`, 404 `truenas_not_found`, or 403 `mock_mode_enabled` in mock mode.TrueNAS resources (pools, datasets, disks, ZFS snapshots, replication tasks, alerts) are surfaced through the unified `/api/resources` endpoint with `source=truenas`.@@ -1918,10 +1944,10 @@ End-to-end encrypted relay protocol for mobile connectivity.> Relay pairing endpoints generate the QR code and deep link used by supported Pulse Mobile clients.-### Relay Configuration (Admin, Relay and Above)-- `GET /api/settings/relay` (admin, `settings:read`, Relay+) β Get current relay configuration.-- `PUT /api/settings/relay` (admin, `settings:write`, Relay+) β Update relay configuration.-- `GET /api/settings/relay/status` (admin, `settings:read`, Relay+) β Get relay connection status.+### Relay Configuration (Relay and Above; admin session or scoped token)+- `GET /api/settings/relay` (`settings:read` token scope, or admin session, Relay+) β Get current relay configuration.+- `PUT /api/settings/relay` (`settings:write` token scope, or admin session, Relay+) β Update relay configuration.+- `GET /api/settings/relay/status` (`settings:read` token scope, or admin session, Relay+) β Get relay connection status.### Mobile Onboarding- `GET /api/onboarding/qr` (`settings:read`) β Generate QR code for Pulse Mobile pairing.diff --git a/frontend-modern/public/docs/TRUENAS.md b/frontend-modern/public/docs/TRUENAS.mdindex 8bd672a1e0..0412b62e55 100644--- a/frontend-modern/public/docs/TRUENAS.md+++ b/frontend-modern/public/docs/TRUENAS.md@@ -133,6 +133,7 @@ All endpoints require admin authentication.| `GET` | `/api/truenas/connections` | List all configured TrueNAS connections || `POST` | `/api/truenas/connections` | Add a new TrueNAS connection || `DELETE` | `/api/truenas/connections/{id}` | Remove a TrueNAS connection |+| `PUT` | `/api/truenas/connections/{id}` | Update a saved connection; send only the fields to change, and never a masked secret || `POST` | `/api/truenas/connections/test` | Test a connection before saving |### Testing and adding a connection (API)diff --git a/scripts/tests/test_api_reference_routes.py b/scripts/tests/test_api_reference_routes.pynew file mode 100644index 0000000000..690ae182f7--- /dev/null+++ b/scripts/tests/test_api_reference_routes.py@@ -0,0 +1,133 @@+#!/usr/bin/env python3+"""Keep docs/API.md aligned with the routes and scopes the server registers.++Static checks only: no server, credentials or network. Each check reads the+reference and a router or handler source file, so drift in either direction+fails here instead of surfacing as a support question.+"""++from __future__ import annotations++from pathlib import Path+import re+import unittest+++ROOT = Path(__file__).resolve().parents[2]+DOC = ROOT / "docs/API.md"+SCOPES = ROOT / "pkg/auth/scopes.go"++SCOPE_TOKEN = re.compile(r"`([a-z]+(?::[a-z]+)+)`")+ROUTE_LINE = re.compile(r"`(?:GET|POST|PUT|PATCH|DELETE)(?:/(?:GET|POST|PUT|PATCH|DELETE))* /api/")+++def read(path: str | Path) -> str:+ return (ROOT / path).read_text(encoding="utf-8") if isinstance(path, str) else path.read_text(encoding="utf-8")+++def known_scopes(text: str) -> set[str]:+ return set(re.findall(r'Scope\w+\s*=\s*"([^"]+)"', text))+++def unknown_scopes_in_reference(doc: str, scopes: set[str]) -> list[str]:+ """Scope-looking tokens on route lines that no code constant defines.++ Only tokens whose first segment is a real scope family are judged, so a+ request value such as `provider:model` is not mistaken for a scope.+ """+ families = {scope.split(":")[0] for scope in scopes}+ unknown: list[str] = []+ for line in doc.splitlines():+ if not ROUTE_LINE.search(line):+ continue+ for token in SCOPE_TOKEN.findall(line):+ if token.split(":")[0] in families and token not in scopes:+ unknown.append(f"{token} in: {line.strip()[:100]}")+ return unknown+++def missing_anchors(pairs: list[tuple[str, str, str]], doc: str, sources: dict[str, str]) -> list[str]:+ """Each pair is (text the reference must contain, source file, text the code must contain)."""+ failures: list[str] = []+ for doc_text, source, code_text in pairs:+ if doc_text not in doc:+ failures.append(f"reference lacks: {doc_text}")+ if code_text not in sources[source]:+ failures.append(f"{source} lacks: {code_text}")+ return failures+++# (reference text, source file, code text). Routes this guide documents on the+# strength of the registration or handler named here.+ROUTE_ANCHORS = [+ ("`GET /api/ai/patrol/runs/{id}` (`ai:execute`)",+ "internal/api/router_routes_ai_relay.go",+ 'r.mux.HandleFunc("/api/ai/patrol/runs/", RequireAuth(r.config, RequireScope(config.ScopeAIExecute,'),+ ("`POST /api/availability-history` (`monitoring:read`)",+ "internal/api/router_routes_monitoring.go",+ 'r.mux.HandleFunc("/api/availability-history", RequireAuth(r.config, RequireScope(config.ScopeMonitoringRead,'),+ ("`POST /api/agents/agent/{agent_id}/allow-reenroll` (admin, `settings:write`)",+ "internal/api/router_routes_registration.go",+ 'strings.HasSuffix(req.URL.Path, "/allow-reenroll")'),+ ("`PUT /api/truenas/connections/{id}` (admin, `settings:write`)",+ "internal/api/router_routes_registration.go",+ "update: r.trueNASHandlers.HandleUpdate,"),+ ("`POST /api/truenas/connections/{id}/test` (admin, `settings:write`)",+ "internal/api/router_routes_registration.go",+ "test: r.trueNASHandlers.HandleTestSavedConnection,"),+ # Every profile route is wrapped once, for all methods, including GET.+ ("Token callers also need `settings:write` on every profile route, including GET requests",+ "internal/api/router_routes_registration.go",+ 'r.mux.Handle("/api/admin/profiles/", RequireAdmin(r.config, RequireScope(config.ScopeSettingsWrite,'),+ ("`PUT /api/notifications/email` (admin, `settings:write`)",+ "internal/api/alerting/notifications.go",+ 'case path == "/email" && r.Method == http.MethodPut:\n\t\tif !requireAnyScope(config.ScopeSettingsWrite'),+]+++class APIReferenceRoutesTest(unittest.TestCase):+ @classmethod+ def setUpClass(cls) -> None:+ cls.doc = read(DOC)+ cls.scopes = known_scopes(read(SCOPES))+ cls.sources = {source: read(source) for _, source, _ in ROUTE_ANCHORS}++ def test_scope_catalogue_was_parsed(self) -> None:+ for scope in ("monitoring:read", "settings:write", "ai:execute", "audit:read"):+ self.assertIn(scope, self.scopes)++ def test_every_scope_named_on_a_route_line_exists_in_code(self) -> None:+ self.assertEqual(unknown_scopes_in_reference(self.doc, self.scopes), [])++ def test_documented_routes_match_their_registration(self) -> None:+ self.assertEqual(missing_anchors(ROUTE_ANCHORS, self.doc, self.sources), [])++ def test_retired_remediation_routes_say_so(self) -> None:+ for route in ("approve", "execute", "rollback"):+ line = next(l for l in self.doc.splitlines() if l.startswith(f"- `POST /api/ai/remediation/{route}`"))+ self.assertIn("410 Gone", line, route)+ self.assertIn("command_remediation_retired", line, route)++ def test_validate_token_is_not_filed_under_the_licensed_audit_log(self) -> None:+ audit = self.doc.split("## π§Ύ Audit Log (Pro)", 1)[1].split("\n## ", 1)[0]+ self.assertNotIn("/api/security/validate-token", audit)+ self.assertIn("/api/security/validate-token", self.doc)++ def test_negative_controls_fail_when_reference_or_code_drift(self) -> None:+ # An invented scope on a route line is reported.+ drifted = self.doc.replace("`POST /api/availability-history` (`monitoring:read`)",+ "`POST /api/availability-history` (`monitoring:peek`)")+ self.assertNotEqual(drifted, self.doc)+ self.assertTrue(unknown_scopes_in_reference(drifted, self.scopes))+ # A route dropped from the reference is reported.+ without_route = self.doc.replace("`GET /api/ai/patrol/runs/{id}` (`ai:execute`)", "")+ self.assertTrue(missing_anchors(ROUTE_ANCHORS, without_route, self.sources))+ # A route whose wrapper loses its scope in code is reported.+ weakened = dict(self.sources)+ key = "internal/api/router_routes_monitoring.go"+ weakened[key] = weakened[key].replace("RequireScope(config.ScopeMonitoringRead,", "RequireScope(config.ScopeSettingsRead,")+ self.assertTrue(missing_anchors(ROUTE_ANCHORS, self.doc, weakened))+++if __name__ == "__main__":+ unittest.main()