From 6753727a04c19f5361713a56c8d08940ded401f0 Mon Sep 17 00:00:00 2001 From: rcourtman Date: Sun, 1 Feb 2026 23:26:42 +0000 Subject: [PATCH] docs: update API documentation and config file references Comprehensive documentation updates: API.md: - Add /api/security/change-password endpoint - Add AI provider test endpoints - Add assistant chat & session management endpoints - Add legacy chat sessions endpoints - Add alert investigation and patrol autonomy endpoints - Add findings & investigations endpoints - Add approvals & command execution endpoints - Add remediation plans endpoints - Add intelligence & forecasting endpoints - Add knowledge base endpoints - Add debug endpoint - Add Socket.IO compatibility endpoint Config files: - Document sso.enc, ai_chat_sessions.json - Document profile-versions.json, profile-changelog.json, profile-deployments.json --- .env.example | 3 +- docs/API.md | 116 +++++++++++++++++++++++++++++++++ docs/CENTRALIZED_MANAGEMENT.md | 3 + docs/CONFIGURATION.md | 2 + docs/DEPLOYMENT_MODELS.md | 3 + 5 files changed, 125 insertions(+), 2 deletions(-) diff --git a/.env.example b/.env.example index 0f4c781e7..5c49930b7 100644 --- a/.env.example +++ b/.env.example @@ -26,8 +26,7 @@ # PULSE_PUBLIC_URL=https://pulse.example.com # ALLOWED_ORIGINS=https://pulse.example.com # FRONTEND_PORT=7655 -# BACKEND_HOST=0.0.0.0 -# BACKEND_PORT=7655 +# BIND_ADDRESS=0.0.0.0 # ----------------------------------------------------------------------------- # Monitoring and logging diff --git a/docs/API.md b/docs/API.md index 5fbec7bf7..3a36eccdc 100644 --- a/docs/API.md +++ b/docs/API.md @@ -22,6 +22,15 @@ curl -H "Authorization: Bearer your-token" http://localhost:7655/api/health ### Session Cookie Standard browser session cookie (used by the UI). +Session endpoints: +- `POST /api/login` (sets `pulse_session` + `pulse_csrf`) +- `POST /api/logout` (clears session) + +Login body: +```json +{ "username": "admin", "password": "secret", "rememberMe": true } +``` + Public endpoints include: - `GET /api/health` - `GET /api/version` @@ -59,6 +68,10 @@ Check if Pulse is running. `GET /api/state` Returns the complete state of your infrastructure (Nodes, VMs, Containers, Storage, Alerts). This is the main endpoint used by the dashboard. +### Simple Stats (HTML) +`GET /simple-stats` +Lightweight HTML status page for quick checks. + ### Unified Resources `GET /api/resources` Returns a unified, flattened resource list. Requires `monitoring:read`. @@ -237,6 +250,10 @@ Other backup endpoints: - `GET /api/backups/pve` - `GET /api/backups/pbs` +### Snapshots +`GET /api/snapshots` +Returns guest snapshot history for the current tenant. + --- ## 🔔 Notifications @@ -303,6 +320,13 @@ Alert configuration and history (requires `monitoring:read`/`monitoring:write`). `GET /api/security/status` Returns authentication status, proxy auth state, and security posture flags. +### Change Password +`POST /api/security/change-password` +```json +{ "currentPassword": "old-pass", "newPassword": "new-pass" } +``` +In Docker installs, the response includes a restart notice. + ### List API Tokens `GET /api/security/tokens` @@ -590,6 +614,10 @@ Configure AI providers, API keys, and preferences. Requires admin + `settings:wr `GET /api/ai/models` Lists models available to the configured providers (queried live from provider APIs). +### Provider Tests (Admin) +- `POST /api/ai/test` +- `POST /api/ai/test/{provider}` + ### OAuth (Anthropic) - `POST /api/ai/oauth/start` (admin) - `POST /api/ai/oauth/exchange` (admin, manual code input) @@ -604,6 +632,29 @@ Runs an AI request which may return tool calls, findings, or suggested actions. `POST /api/ai/execute/stream` Streaming variant of execute (used by the UI for incremental responses). +### Assistant Chat & Sessions +- `GET /api/ai/status` +- `POST /api/ai/chat` (streaming) +- `GET /api/ai/sessions` +- `POST /api/ai/sessions` +- `DELETE /api/ai/sessions/{id}` +- `GET /api/ai/sessions/{id}/messages` +- `POST /api/ai/sessions/{id}/abort` +- `POST /api/ai/sessions/{id}/summarize` +- `GET /api/ai/sessions/{id}/diff` +- `POST /api/ai/sessions/{id}/fork` +- `POST /api/ai/sessions/{id}/revert` +- `POST /api/ai/sessions/{id}/unrevert` + +### Legacy Chat Sessions (UI Sync) +- `GET /api/ai/chat/sessions` +- `GET /api/ai/chat/sessions/{id}` +- `PUT /api/ai/chat/sessions/{id}` +- `DELETE /api/ai/chat/sessions/{id}` + +### Question Answers +- `POST /api/ai/question/{id}/answer` + ### Kubernetes AI Analysis (Pro) `POST /api/ai/kubernetes/analyze` ```json @@ -611,7 +662,13 @@ Streaming variant of execute (used by the UI for incremental responses). ``` Requires a Pulse Pro license with the `kubernetes_ai` feature enabled. +### Alert Investigation (Pro) +`POST /api/ai/investigate-alert` +Runs a focused investigation for an alert payload (used by the UI). + ### Patrol +- `GET /api/ai/patrol/autonomy` +- `PUT /api/ai/patrol/autonomy` - `GET /api/ai/patrol/status` - `GET /api/ai/patrol/findings` - `DELETE /api/ai/patrol/findings` (clear all findings) @@ -621,6 +678,7 @@ Requires a Pulse Pro license with the `kubernetes_ai` feature enabled. - `POST /api/ai/patrol/run` (admin, Pro) - `POST /api/ai/patrol/acknowledge` (Pro) - `POST /api/ai/patrol/dismiss` +- `POST /api/ai/patrol/findings/note` - `POST /api/ai/patrol/resolve` - `POST /api/ai/patrol/snooze` (Pro) - `POST /api/ai/patrol/suppress` (Pro) @@ -629,6 +687,63 @@ Requires a Pulse Pro license with the `kubernetes_ai` feature enabled. - `DELETE /api/ai/patrol/suppressions/{id}` (Pro) - `GET /api/ai/patrol/dismissed` (Pro) +### Findings & Investigations +- `GET /api/ai/unified/findings` +- `GET /api/ai/findings/{id}/investigation` +- `GET /api/ai/findings/{id}/investigation/messages` +- `POST /api/ai/findings/{id}/reinvestigate` +- `POST /api/ai/findings/{id}/reapprove` (Pro) + +### Approvals & Command Execution (Pro) +- `GET /api/ai/approvals` +- `GET /api/ai/approvals/{id}` +- `POST /api/ai/approvals/{id}/approve` +- `POST /api/ai/approvals/{id}/deny` +- `POST /api/ai/run-command` (execute an approved command) +- `GET /api/ai/agents` (connected agents via `/api/agent/ws`) + +### Remediation Plans (Pro) +- `GET /api/ai/remediation/plans` +- `GET /api/ai/remediation/plan?plan_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": "...", "plan_id": "..." }` +- `rollback`: `{ "execution_id": "..." }` + +### Intelligence & Forecasting +- `GET /api/ai/intelligence` +- `GET /api/ai/intelligence/patterns` +- `GET /api/ai/intelligence/predictions` +- `GET /api/ai/intelligence/correlations` +- `GET /api/ai/intelligence/changes` +- `GET /api/ai/intelligence/baselines` +- `GET /api/ai/intelligence/remediations` +- `GET /api/ai/intelligence/anomalies` +- `GET /api/ai/intelligence/learning` +- `GET /api/ai/forecast` (params: `resource_id`, `metric`, optional `resource_name`, `horizon_hours`, `threshold`) +- `GET /api/ai/forecasts/overview` (params: `metric`, `horizon_hours`, `threshold`) +- `GET /api/ai/learning/preferences` (optional `resource_id`) +- `GET /api/ai/proxmox/events` +- `GET /api/ai/proxmox/correlations` +- `GET /api/ai/incidents` (optional `resource_id`, `limit`) +- `GET /api/ai/incidents/{resourceId}` (optional `limit`) +- `GET /api/ai/circuit/status` + +### Knowledge Base +- `GET /api/ai/knowledge?guest_id=` +- `POST /api/ai/knowledge/save` +- `POST /api/ai/knowledge/delete` +- `GET /api/ai/knowledge/export?guest_id=` +- `POST /api/ai/knowledge/import` +- `POST /api/ai/knowledge/clear` + +### Debug +- `GET /api/ai/debug/context` (admin) + ### Cost Tracking - `GET /api/ai/cost/summary` - `POST /api/ai/cost/reset` (admin) @@ -780,6 +895,7 @@ Updates server-side config for an agent (e.g., `commandsEnabled`). ## 🔌 WebSocket Endpoints - `GET /ws` – Primary UI WebSocket (browser sessions). +- `GET /socket.io/` – Legacy Socket.IO compatibility endpoint. - `GET /api/agent/ws` – Agent WebSocket used for AI command execution. --- diff --git a/docs/CENTRALIZED_MANAGEMENT.md b/docs/CENTRALIZED_MANAGEMENT.md index eb89e4d21..6dbc52b04 100644 --- a/docs/CENTRALIZED_MANAGEMENT.md +++ b/docs/CENTRALIZED_MANAGEMENT.md @@ -188,5 +188,8 @@ Profiles and assignments are stored in the Pulse config directory: - `agent_profiles.json` - `agent_profile_assignments.json` +- `profile-versions.json` +- `profile-changelog.json` +- `profile-deployments.json` Deleting a profile automatically removes its assignments. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 51b1dc88e..9d1c6aa2a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -14,12 +14,14 @@ Pulse uses a split-configuration model to ensure security and flexibility. | `webhooks.enc` | Webhook URLs + headers | 🔒 **Encrypted** | | `apprise.enc` | Apprise notification config | 🔒 **Encrypted** | | `oidc.enc` | OIDC provider config | 🔒 **Encrypted** | +| `sso.enc` | SAML/SSO provider config | 🔒 **Encrypted** | | `api_tokens.json` | API token records (hashed) | 🔒 **Sensitive** | | `env_token_suppressions.json` | Suppressed legacy env tokens (migration aid) | 📝 Standard | | `ai.enc` | AI settings and credentials | 🔒 **Encrypted** | | `ai_findings.json` | AI Patrol findings | 📝 Standard | | `ai_patrol_runs.json` | AI Patrol run history | 📝 Standard | | `ai_usage_history.json` | AI usage history | 📝 Standard | +| `ai_chat_sessions.json` | Legacy AI chat sessions (UI sync) | 📝 Standard | | `license.enc` | Pulse Pro license key | 🔒 **Encrypted** | | `host_metadata.json` | Host notes, tags, and AI command overrides | 📝 Standard | | `docker_metadata.json` | Docker metadata cache | 📝 Standard | diff --git a/docs/DEPLOYMENT_MODELS.md b/docs/DEPLOYMENT_MODELS.md index 435be3f02..535d5059b 100644 --- a/docs/DEPLOYMENT_MODELS.md +++ b/docs/DEPLOYMENT_MODELS.md @@ -28,10 +28,13 @@ Pulse uses a split config model: - **System settings**: `system.json` (editable in the UI unless locked by env) - **Nodes and credentials**: `nodes.enc` (encrypted) - **Notification config**: `email.enc`, `webhooks.enc`, `apprise.enc` (encrypted) +- **OIDC config**: `oidc.enc` (encrypted) +- **SSO config**: `sso.enc` (encrypted) - **API tokens**: `api_tokens.json` - **Legacy token suppressions**: `env_token_suppressions.json` - **AI config**: `ai.enc` (encrypted) - **AI patrol data**: `ai_findings.json`, `ai_patrol_runs.json`, `ai_usage_history.json` +- **AI chat sessions**: `ai_chat_sessions.json` (legacy UI sync) - **AI baseline data**: `baselines.json` - **AI correlation data**: `ai_correlations.json` - **AI pattern data**: `ai_patterns.json`