Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

docs: correct API reference auth labels and add missing routes

rcourtman9031dd949c97
diff --git a/docs/API.md b/docs/API.md
index 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 Metadata
User 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 of
resource-tag strings) and `tagFilterMode` (`"all"` or `"any"`). An omitted
field is preserved on update; an empty `tagFilter` clears routing and restores
delivery 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 are
retained 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 have
different 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 fresh
retry 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.md
index 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.md
index 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 Metadata
User 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 of
resource-tag strings) and `tagFilterMode` (`"all"` or `"any"`). An omitted
field is preserved on update; an empty `tagFilter` clears routing and restores
delivery 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 are
retained 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 have
different 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 fresh
retry 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.md
index 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.py
new file mode 100644
index 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()