vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-04-28 11:30:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
Pulse/docs/API.md

39 KiB
Raw Blame History

🔌 Pulse API Reference

Pulse provides a comprehensive REST API for automation and integration.

Base URL: http://<your-pulse-ip>:7655/api

🔐 Authentication

Most API requests require authentication via one of the following methods:

API Token (Recommended)

Pass the token in the X-API-Token header.

curl -H "X-API-Token: your-token" http://localhost:7655/api/health

Bearer Token

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:

{ "username": "admin", "password": "secret", "rememberMe": true }

Public endpoints include:

  • GET /api/health
  • GET /api/version
  • GET /api/agent/version (agent update checks)
  • GET /api/setup-script (requires a setup token)

🔏 Scopes and Admin Access

Some endpoints require admin privileges and/or scopes. Common scopes include:

  • monitoring:read
  • settings:read
  • settings:write
  • agent:config:read
  • agent:manage

Endpoints that require admin access are noted below.

📡 Core Endpoints

System Health

GET /api/health Check if Pulse is running.

{
  "status": "healthy",
  "timestamp": 1700000000,
  "uptime": 3600,
  "devModeSSH": false
}

System State

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 the unified resource list with pagination + aggregations. Requires monitoring:read.

Query params:

  • type: comma-separated list (e.g., agent, vm, system-container, container, docker-service, storage, pbs, pmg, k8s-cluster, k8s-node, pod, k8s-deployment, physical_disk, ceph)
  • source: comma-separated list (e.g., proxmox, agent, docker, pbs, pmg, kubernetes)
  • status: comma-separated list (online, offline, warning, unknown)
  • parent: parent resource ID
  • cluster: cluster name
  • namespace: Kubernetes namespace (filters Kubernetes resources only)
  • q: name search (contains match)
  • tags: comma-separated tags
  • page: page number (default 1)
  • limit: page size (default 50, max 100)
  • sort: name (default), status, type, lastSeen
  • order: asc (default) or desc

Note: GET /api/resources is optimized for list views. Some large, platform-specific fields may be omitted from the list response and are only returned by GET /api/resources/{id}.

GET /api/resources/stats Returns aggregations (counts + health rollups).

GET /api/resources/k8s/namespaces?cluster=<clusterName> Returns namespace-level rollups (pods + deployments) for a Kubernetes cluster. Requires monitoring:read.

{
  "cluster": "prod-k8s",
  "data": [
    {
      "namespace": "default",
      "pods": { "total": 12, "online": 10, "warning": 2, "offline": 0, "unknown": 0 },
      "deployments": { "total": 3, "online": 3, "warning": 0, "offline": 0, "unknown": 0 }
    }
  ]
}

GET /api/resources/{id} Fetch a single resource by ID.

GET /api/resources/{id}/children Returns child resources for the parent ID.

GET /api/resources/{id}/metrics Returns the resource metrics payload.

POST /api/resources/{id}/link Manually link two resources.

{ "targetId": "resource-id", "reason": "optional note" }

POST /api/resources/{id}/unlink Manually unlink two resources.

{ "targetId": "resource-id", "reason": "optional note" }

POST /api/resources/{id}/report-merge Report an incorrect merge (creates exclusions).

{ "sources": ["proxmox", "agent"], "notes": "optional note" }

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)

  • 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/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/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)

Version Info

GET /api/version Returns version, build time, and update status. Example response:

{
  "version": "6.0.0",
  "buildTime": "2026-02-21T00:00:00Z",
  "channel": "stable",
  "deploymentType": "systemd",
  "updateAvailable": false,
  "latestVersion": "6.0.0"
}

Version fields are returned as plain semantic versions (no leading v).

🖥️ Nodes & Config

Public Config

GET /api/config Returns a small public config payload (update channel, auto-update enabled).

List Nodes

GET /api/config/nodes

Add Node

POST /api/config/nodes

{
  "type": "pve",
  "name": "Proxmox 1",
  "host": "https://198.51.100.10:8006",
  "user": "root@pam",
  "password": "password"
}

Test Connection

POST /api/config/nodes/test-connection Validate credentials before saving.

Test Node Config (Validation Only)

POST /api/config/nodes/test-config Validates node config without saving.

Update Node

PUT /api/config/nodes/{id}

Delete Node

DELETE /api/config/nodes/{id}

Test Node (Legacy)

POST /api/config/nodes/{id}/test

Refresh Cluster Nodes

POST /api/config/nodes/{id}/refresh-cluster

Export Configuration

POST /api/config/export (admin or API token) Request body:

{ "passphrase": "use-a-strong-passphrase" }

Returns an encrypted export bundle in data. Passphrases must be at least 12 characters.

Import Configuration

POST /api/config/import (admin) Request body:

{
  "data": "<exported-bundle>",
  "passphrase": "use-a-strong-passphrase"
}

🧭 Setup & Discovery

Setup Script (Public)

GET /api/setup-script Returns the Proxmox/PBS setup script as a shell-script download. Accepts an optional temporary setup token in the setup_token query for embedded non-interactive bootstrap; otherwise the script prompts for the one-time setup token at runtime. Canonical callers must send a supported type of pve or pbs plus non-empty host and pulse_url; the route no longer generates placeholder-host scripts for later repair or reconstructs Pulse identity from the request origin. The route now shares the same canonical type boundary as /api/setup-script-url, rejecting unsupported node types instead of treating unknown values as PBS, and it normalizes the supplied host before script generation so downloaded artifacts and rerun URLs preserve the same canonical node identity as the bootstrap response. The optional backup_perms=true query is supported only for type=pve.

Setup Script URL

POST /api/setup-script-url (auth) Generates a one-time setup token and URL for /api/setup-script. Canonical callers must send a supported type of pve or pbs plus a non-empty host; the backend normalizes that host before minting the setup token and now returns the canonical bootstrap identity back in the response as type, host, url, downloadURL, scriptFileName, command, commandWithEnv, commandWithoutEnv, setupToken, tokenHint, and expires. The returned commands are canonical root-or-sudo curl -fsSL bootstrap commands for the generated setup script, while url, downloadURL, and scriptFileName are the runtime-owned artifact metadata used by copy and manual download surfaces. The request body is a single canonical JSON object only; unknown fields and trailing JSON are rejected as invalid request shape, and backupPerms:true is supported only for type:"pve". This route stays on the normal authenticated bootstrap boundary: when Pulse auth is already configured it requires a real authenticated session or API token, and setup tokens do not authorize the request itself. Pulse-managed Proxmox monitor-token names on the setup/bootstrap path derive from the canonical Pulse endpoint, not request-local host fallbacks, so setup-script and turnkey node-add flows stay on one deterministic pulse-<canonical-scope-slug> identity per Pulse instance. setupToken remains bootstrap transport data for /api/setup-script and /api/auto-register, while tokenHint is the operator-facing display field for quick-setup surfaces and must stay masked instead of exposing the full one-time token in UI copy. Shared frontend consumers may validate setupToken, but they should not retain or display it once the returned bootstrap artifact and tokenHint are available; visible quick-setup previews should use the non-secret commandWithoutEnv form while copy actions keep using the token-bearing commandWithEnv artifact, and manual download flows should use the token-bearing downloadURL artifact instead of rebuilding a plain setup-script URL from non-secret preview state. Non-frontend bootstrap consumers such as the runtime-side Unified Agent bootstrap flow and shell installer must fail closed on that same full artifact contract too, rejecting missing or mismatched downloadURL, tokenHint, or expired expires values instead of accepting a reduced setup-token-only response shape.

Auto-Register (Public)

POST /api/auto-register Registers a node through the canonical /api/auto-register contract using a temporary setup token carried in the JSON authToken field. Canonical callers must send a supported type of pve or pbs, an explicit source marker of agent or script, a canonical Pulse-managed tokenId in the form pulse-monitor@{pve|pbs}!pulse-<canonical-scope-slug> matching the requested type, an explicit serverName, and missing-token requests now fail with Pulse setup token required. Incomplete token completion requests now fail with tokenId and tokenValue must be provided together, and other missing canonical request fields fail with explicit Missing required canonical auto-register fields: ... guidance. Success responses now carry the canonical stored identity and caller boundary back to the installer or runtime-side Unified Agent: {"status":"success","action":"use_token","type":"pve|pbs","source":"agent|script","host":"https://...","nodeId":"<stored-name>","nodeName":"<stored-name>",...}.

Agent Install Command

POST /api/agent-install-command (auth) Generates an API token and install command for agent-based Proxmox setup.

Discovery

GET /api/discover (auth) Runs network discovery.

AI Discovery (Service Discovery)

Service discovery is used by Pulse Assistant and the UI to inventory web services and enrich links.

  • GET /api/discovery (list summaries)
  • GET /api/discovery/status
  • PUT /api/discovery/settings (admin, settings:write)
  • GET /api/discovery/type/{type}
  • GET /api/discovery/agent/{agentId}
  • GET /api/discovery/{type}/{targetId}/{resourceId}
  • POST /api/discovery/{type}/{targetId}/{resourceId} (trigger discovery, optional force)
  • DELETE /api/discovery/{type}/{targetId}/{resourceId}
  • GET /api/discovery/{type}/{targetId}/{resourceId}/progress
  • PUT /api/discovery/{type}/{targetId}/{resourceId}/notes

Test Notification

POST /api/test-notification (auth) Broadcasts a WebSocket test event.

📊 Metrics & Charts

Chart Data

GET /api/charts?range=1h Returns time-series data for CPU, Memory, and Storage. Ranges: 5m, 15m, 30m, 1h, 4h, 12h, 24h, 7d

Storage Charts

GET /api/storage-charts Returns storage chart data.

Storage Stats

GET /api/storage/ Detailed storage usage per node and pool.

Recovery (formerly Backups / Snapshots)

Pulse v6 uses the recovery API to provide a platform-agnostic view of backup and snapshot artifacts. See docs/architecture/RECOVERY_CONTRACT.md for the provider-neutral contract (subjects, points, rollups, and filter semantics).

  • GET /api/recovery/points
    • Query params:
      • Core filters: provider, kind, mode, outcome, subjectResourceId, rollupId
      • Time window: from (RFC3339), to (RFC3339)
      • Paging: page, limit
      • Normalized filters: q, cluster, node, namespace, scope=workload, verification (verified | unverified | unknown)
  • GET /api/recovery/rollups
    • Query params: provider, kind, mode, outcome, subjectResourceId, rollupId, from (RFC3339), to (RFC3339), page, limit
  • GET /api/recovery/series
    • Returns per-day counts for the activity chart.
    • Query params: same filters as /api/recovery/points (except paging), plus tzOffsetMinutes (integer; UTC offset minutes for day bucketing)
  • GET /api/recovery/facets
    • Returns distinct filter values (clusters/nodes/namespaces) and capability flags (size/verification/entity id present).
    • Query params: same filters as /api/recovery/points (except paging)

🔔 Notifications

Send Test Notification

POST /api/notifications/test (admin) Triggers a test alert to all configured channels.

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/health (admin)

Audit Webhooks (Pro)

  • GET /api/admin/webhooks/audit (admin, settings:read)
  • POST /api/admin/webhooks/audit (admin, settings:write)
    • Body: { "urls": ["https://..."] }
    • Strict JSON contract: unknown fields and trailing payload are rejected.
    • Maximum 20 webhook URLs per update request.
    • URLs are normalized (trimmed) and duplicate entries are ignored.
    • Endpoint fails closed if URL validation runtime is unavailable.

Advanced Reporting (Pro)

  • GET /api/admin/reports/generate (admin, settings:read)
    • Query params: format (pdf/csv, default pdf), resourceType, resourceId, metricType (optional), start/end (RFC3339, optional; defaults to last 24h), title (optional)
  • POST /api/admin/reports/generate-multi (admin, settings:read)
    • Body fields: resources (1-50 entries of {resourceType,resourceId}), format, metricType (optional), start/end (RFC3339, optional; defaults to last 24h), title (optional)

Validation and limits:

  • start and end must be RFC3339 when provided.
  • start must be before end.
  • Maximum report window is 366 days.
  • metricType must match [a-zA-Z0-9._:-]+ and be <= 64 chars.
  • title must be <= 256 chars.
  • Multi-report body max size is 1MB and rejects trailing payload or unknown JSON fields.

Common reporting error codes:

  • invalid_format, missing_params, invalid_resource_type, invalid_resource_id
  • invalid_metric_type, invalid_title
  • invalid_start, invalid_end, invalid_range, range_too_large
  • no_resources, too_many_resources, body_too_large, invalid_body

Queue and Dead-Letter Tools

  • GET /api/notifications/queue/stats (admin)
  • GET /api/notifications/dlq (admin)
  • POST /api/notifications/dlq/retry (admin)
  • POST /api/notifications/dlq/delete (admin)

🚨 Alerts

Alert configuration and history (requires monitoring:read/monitoring:write).

  • GET /api/alerts/config
  • PUT /api/alerts/config
  • POST /api/alerts/activate
  • GET /api/alerts/active
  • GET /api/alerts/history
  • DELETE /api/alerts/history
  • GET /api/alerts/incidents
  • POST /api/alerts/incidents/note
  • POST /api/alerts/bulk/acknowledge
  • POST /api/alerts/bulk/clear
  • POST /api/alerts/acknowledge (body: { "id": "alert-id" })
  • POST /api/alerts/unacknowledge (body: { "id": "alert-id" })
  • POST /api/alerts/clear (body: { "id": "alert-id" })

🛡️ Security

Security Status

GET /api/security/status Returns authentication status, proxy auth state, and security posture flags.

Change Password

POST /api/security/change-password

{ "currentPassword": "old-pass", "newPassword": "new-pass" }

In Docker installs, the response includes a restart notice.

List API Tokens

GET /api/security/tokens

Create API Token

POST /api/security/tokens

{ "name": "ansible-script", "scopes": ["monitoring:read"] }

Revoke Token

DELETE /api/security/tokens/<id>

Recovery (Localhost or Recovery Token)

POST /api/security/recovery Supports actions:

  • generate_token (localhost only)
  • disable_auth
  • enable_auth

GET /api/security/recovery returns recovery mode status.

Reset Account Lockout (Admin)

POST /api/security/reset-lockout

{ "identifier": "admin" }

Identifier can be a username or IP address.

Regenerate API Token (Admin)

POST /api/security/regenerate-token

Returns a new raw token (shown once) and updates stored hashes:

{
  "success": true,
  "token": "raw-token",
  "deploymentType": "systemd",
  "requiresRestart": false,
  "message": "New API token generated and active immediately! Save this token - it won't be shown again."
}

---

## 🧾 Audit Log (Pro)

These endpoints require admin access and the `settings:read` scope. On Community, the list endpoint returns an empty set and `persistentLogging: false`.

### List Audit Events
`GET /api/audit?limit=100&event=login&user=admin&success=true&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z`

Response:
```json
{
  "events": [
    {
      "id": "6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45",
      "timestamp": "2024-01-12T10:15:30Z",
      "event": "login",
      "user": "admin",
      "ip": "198.51.100.10",
      "path": "/api/login",
      "success": true,
      "details": "Successful login",
      "signature": "..."
    }
  ],
  "total": 1,
  "persistentLogging": true
}

Verify Audit Event Signature

GET /api/audit/<id>/verify

Response:

{
  "available": true,
  "verified": true,
  "message": "Event signature verified"
}

Validate API Token (Admin)

POST /api/security/validate-token

{ "token": "raw-token" }

Returns:

{ "valid": true, "message": "Token is valid" }

Bootstrap Token Validation (Public)

POST /api/security/validate-bootstrap-token

Provide the token via header X-Setup-Token or JSON body:

{ "token": "bootstrap-token" }

Returns 204 No Content on success.

Quick Security Setup (Public, bootstrap token required)

POST /api/security/quick-setup

Requires a valid bootstrap token (header X-Setup-Token) or an authenticated session.

{
  "username": "admin",
  "password": "StrongPass!1",
  "apiToken": "token",
  "enableNotifications": false,
  "darkMode": false,
  "force": false,
  "setupToken": "optional-bootstrap-token"
}

Apply Security Restart (Systemd Only)

POST /api/security/apply-restart Applies auth changes by restarting the service (systemd deployments only).

⚙️ System Settings

Get Settings

GET /api/system/settings Retrieve current system settings.

Update Settings

POST /api/system/settings/update Update system settings. Requires admin + settings:write.

Legacy System Settings (Read Only)

GET /api/config/system Legacy system settings endpoint (read-only).

Toggle Mock Mode

GET /api/system/mock-mode POST /api/system/mock-mode PUT /api/system/mock-mode Enable or disable mock data generation (dev/demo only).

SSH Config (Temperature Monitoring)

POST /api/system/ssh-config Writes the SSH config used for temperature collection (requires setup token or auth).

Verify Temperature SSH

POST /api/system/verify-temperature-ssh Tests SSH connectivity for temperature collection (requires setup token or auth).

Scheduler Health

GET /api/monitoring/scheduler/health Returns scheduler health, DLQ, and breaker status. Requires monitoring:read.

Updates (Admin)

  • GET /api/updates/check
  • POST /api/updates/apply
  • GET /api/updates/status
  • GET /api/updates/stream
  • GET /api/updates/plan?version=X.Y.Z (optional channel, accepts v prefix)
  • GET /api/updates/history
  • GET /api/updates/history/entry?id=<event_id>

Infrastructure Updates

  • GET /api/infra-updates (requires monitoring:read)
  • GET /api/infra-updates/summary (requires monitoring:read)
  • POST /api/infra-updates/check (requires monitoring:write)
  • GET /api/infra-updates/agent/{agentId} (requires monitoring:read)
  • GET /api/infra-updates/{resourceId} (requires monitoring:read)

Diagnostics

  • GET /api/diagnostics (auth)
  • POST /api/diagnostics/docker/prepare-token (admin, settings:write)

Logs (Admin)

  • GET /api/logs/stream (server-sent stream)
  • GET /api/logs/download (bundled logs)
  • GET /api/logs/level
  • POST /api/logs/level (set log level)

Server Info

GET /api/server/info Returns minimal server info for installer scripts.

🔑 OIDC / SSO

Provider Login

  • GET /api/oidc/{providerID}/login
  • GET /api/oidc/{providerID}/callback

OIDC and SAML configuration is managed via SSO providers.

SSO Provider Management (Pro)

  • 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)

Provider mutation request contract:

  • Max request body: 1MB.
  • Strict JSON contract: unknown fields and trailing payload are rejected.
  • Provider IDs must match server validation.
  • SAML providers require advanced_sso feature entitlement.

SSO Test and Metadata Preview (Pro)

  • POST /api/security/sso/providers/test (admin)
  • POST /api/security/sso/providers/metadata/preview (admin)

Test/preview request contract:

  • Max request body: 32KB.
  • Strict JSON contract: unknown fields and trailing payload are rejected.
  • Common errors include invalid_json, validation_error, rate_limited, body_too_large.

💳 License (Relay / Pro / Pro+ / Cloud)

License Status (Admin)

GET /api/license/status

License Features (Authenticated)

GET /api/license/features

Activate License (Admin)

POST /api/license/activate

{ "license_key": "PASTE_KEY_HERE" }

Clear License (Admin)

POST /api/license/clear

👥 RBAC / Role Management (Pro)

Role-based access control endpoints for managing roles and user assignments. Requires admin access and the rbac license feature.

List Roles

GET /api/admin/roles Returns all defined roles.

Create Role

POST /api/admin/roles

{
  "id": "operator",
  "name": "Operator",
  "description": "Can view and manage alerts",
  "permissions": [
    { "action": "read", "resource": "alerts" },
    { "action": "write", "resource": "alerts" }
  ]
}

Update Role

PUT /api/admin/roles/{id} Update an existing role's name, description, or permissions.

Delete Role

DELETE /api/admin/roles/{id}

List Users

GET /api/admin/users Returns all users with their role assignments.

Assign Role to User

POST /api/admin/users/{username}/roles

{ "role_id": "operator" }

Remove Role from User

DELETE /api/admin/users/{username}/roles/{role_id}

Note

: OIDC group-to-role mapping can automatically assign roles on login. See OIDC.md for configuration.

🏢 Organizations (Enterprise)

Multi-tenant organization management. Requires PULSE_MULTI_TENANT_ENABLED=true and an Enterprise license with the multi_tenant feature. All endpoints require authentication.

See MULTI_TENANT.md for setup and architecture details.

List Organizations

GET /api/orgs (requires settings:read) Returns organizations accessible to the authenticated user.

Create Organization

POST /api/orgs (requires settings:write, session auth only)

{ "id": "acme-corp", "displayName": "Acme Corporation" }

The creator becomes the owner and first member. Organization IDs must be lowercase alphanumeric with hyphens, 3-64 characters.

Get Organization

GET /api/orgs/{id} (requires settings:read) Returns organization details. User must be a member.

Update Organization

PUT /api/orgs/{id} (requires settings:write, session auth only)

{ "displayName": "Updated Name" }

Admin or owner role required. The default organization cannot be updated.

Delete Organization

DELETE /api/orgs/{id} (requires settings:write, session auth only) Admin or owner role required. The default organization cannot be deleted.

List Members

GET /api/orgs/{id}/members (requires settings:read) Returns all members with their roles. User must be a member of the org.

Add or Update Member

POST /api/orgs/{id}/members (requires settings:write, session auth only)

{ "userId": "jane", "role": "editor" }

Roles: owner, admin, editor, viewer. Admin or owner role required. Setting role to owner transfers ownership (only current owner can do this). Default org members cannot be managed.

Remove Member

DELETE /api/orgs/{id}/members/{userId} (requires settings:write, session auth only) Admin or owner role required. The organization owner cannot be removed.

List Outgoing Shares

GET /api/orgs/{id}/shares (requires settings:read) Returns resources shared outbound from this organization to others.

List Incoming Shares

GET /api/orgs/{id}/shares/incoming (requires settings:read) Returns resources shared inbound to this organization from other organizations.

Create Share

POST /api/orgs/{id}/shares (requires settings:write, session auth only)

{
  "targetOrgId": "partner-org",
  "resourceType": "vm",
  "resourceId": "vm-101",
  "resourceName": "Web Server",
  "accessRole": "viewer"
}

Share a resource with another organization. Valid resource types: vm, container, agent, storage, pbs, pmg. Access roles: viewer, editor, admin. Admin or owner role required on the source org.

Delete Share

DELETE /api/orgs/{id}/shares/{shareId} (requires settings:write, session auth only) Revoke a resource share. Admin or owner role required.

🤖 Pulse AI

Paid gating: endpoints labeled with a paid plan require the relevant Relay, Pro, Pro+, or Cloud capability and return 402 Payment Required if the feature is not licensed.

Get AI Settings

GET /api/settings/ai Returns current AI configuration (providers, models, patrol status). Requires admin + settings:read.

Update AI Settings

PUT /api/settings/ai/update (or POST /api/settings/ai/update) Configure AI providers, API keys, and preferences. Requires admin + settings:write.

List Models

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)
  • GET /api/ai/oauth/callback (public, IdP redirect)
  • POST /api/ai/oauth/disconnect (admin)

Execute (Chat + Tools)

POST /api/ai/execute Runs an AI request which may return tool calls, findings, or suggested actions.

Execute (Streaming)

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

Question Answers

  • POST /api/ai/question/{id}/answer

Kubernetes AI Analysis (Pro)

POST /api/ai/kubernetes/analyze

{ "cluster_id": "cluster-id" }

Requires Pro, Pro+, or Cloud 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)
  • GET /api/ai/patrol/history
  • GET /api/ai/patrol/runs
  • GET /api/ai/patrol/stream (Pro)
  • 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)
  • GET /api/ai/patrol/suppressions (Pro)
  • POST /api/ai/patrol/suppressions (Pro)
  • 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=<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 (canonical unified-resource timeline first, patrol-local memory fallback)
  • 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=<id>
  • POST /api/ai/knowledge/save
  • POST /api/ai/knowledge/delete
  • GET /api/ai/knowledge/export?guest_id=<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)
  • GET /api/ai/cost/export (admin)

📈 Metrics Store

Auth required: monitoring:read.

Store Stats

GET /api/metrics-store/stats Returns stats for the persistent metrics store (SQLite-backed).

History

GET /api/metrics-store/history Returns historical metric series for a resource and time range.

Query params:

  • resourceType (required): node, vm, container, storage, dockerHost, dockerContainer
  • resourceId (required)
  • metric (optional): cpu, memory, disk, etc. Omit for all metrics
  • range (optional): 1h, 6h, 12h, 24h, 1d, 7d, 30d, 90d (default 24h; duration strings also accepted)
  • maxPoints (optional): Downsample to a target number of points

License: Requests beyond Community's 7d floor require the paid long_term_metrics entitlement. Relay unlocks 14d, Pro and Pro+ unlock 90d, and requests beyond the active tier's limit return 402 Payment Required. Aliases: guest (VM/LXC) and docker (Docker container) are accepted, but persistent store data uses the canonical types above.

🤖 Agent Endpoints

Unified Agent (Recommended)

GET /download/pulse-agent Downloads the unified agent binary. Without arch, Pulse serves the local binary on the server host.

Optional query:

  • ?arch=linux-amd64 (supported: linux-amd64, linux-arm64, linux-armv7, linux-armv6, linux-386, darwin-amd64, darwin-arm64, freebsd-amd64, freebsd-arm64, windows-amd64, windows-arm64, windows-386)

The response includes X-Checksum-Sha256 for verification.

The unified agent combines host, Docker, and Kubernetes monitoring. Use --enable-docker or --enable-kubernetes to enable additional metrics.

See UNIFIED_AGENT.md for installation instructions.

Agent Version

GET /api/agent/version Returns the current server version for agent update checks.

Unified Agent Installer Script

GET /install.sh Serves the universal install.sh used to install pulse-agent on target machines.

Unified Agent Installer (Windows)

GET /install.ps1 Serves the PowerShell installer for Windows.

Submit Reports

POST /api/agents/agent/report - Agent metrics POST /api/agents/docker/report - Docker container metrics POST /api/agents/kubernetes/report - Kubernetes cluster metrics

Agent Management

GET /api/agents/agent/lookup?id=<agent_id>
GET /api/agents/agent/lookup?hostname=<hostname>
Looks up an agent by ID or hostname/display name. Requires agent:report.

POST /api/agents/agent/uninstall
Agent self-unregister during uninstall. Requires agent:report.

POST /api/agents/agent/unlink (admin, agent:manage)
Unlinks an agent from a node.

DELETE /api/agents/agent/{agent_id} (admin, agent:manage)
Removes an agent from state.

Agent Linking (Admin)

  • POST /api/agents/agent/link (admin, agent:manage)
  • POST /api/agents/agent/unlink (admin, agent:manage)

Agent Remote Config

GET /api/agents/agent/{agent_id}/config
Returns the server-side config payload for an agent (used by remote config and debugging). Requires agent:config:read.

PATCH /api/agents/agent/{agent_id}/config (admin, agent:manage)
Updates server-side config for an agent (e.g., commandsEnabled).

Docker Agent Management (Admin)

  • POST /api/agents/docker/commands/{commandId}/ack (docker:report)
  • DELETE /api/agents/docker/runtimes/{agentId} (docker:manage, supports ?hide=true or ?force=true)
  • POST /api/agents/docker/runtimes/{agentId}/allow-reenroll (docker:manage)
  • PUT /api/agents/docker/runtimes/{agentId}/unhide (docker:manage)
  • PUT /api/agents/docker/runtimes/{agentId}/pending-uninstall (docker:manage)
  • PUT /api/agents/docker/runtimes/{agentId}/display-name (docker:manage)
  • POST /api/agents/docker/runtimes/{agentId}/check-updates (docker:manage)
  • POST /api/agents/docker/runtimes/{agentId}/update-all (docker:manage)
  • POST /api/agents/docker/containers/update (docker:manage)

Kubernetes Agent Management (Admin)

  • DELETE /api/agents/kubernetes/clusters/{clusterId} (kubernetes:manage, supports ?hide=true or ?force=true)
  • POST /api/agents/kubernetes/clusters/{clusterId}/allow-reenroll (kubernetes:manage)
  • PUT /api/agents/kubernetes/clusters/{clusterId}/unhide (kubernetes:manage)
  • PUT /api/agents/kubernetes/clusters/{clusterId}/pending-uninstall (kubernetes:manage)
  • 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)

🐟 TrueNAS

TrueNAS connection management endpoints for adding, testing, and removing TrueNAS SCALE/CORE instances.

Connection Management (Admin)

  • 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.
  • DELETE /api/truenas/connections/{id} (admin, settings:write) — Remove a TrueNAS connection.

TrueNAS resources (pools, datasets, disks, ZFS snapshots, replication tasks, alerts) are surfaced through the unified /api/resources endpoint with source=truenas.

📱 Relay / Mobile Remote Access (Relay and Above)

End-to-end encrypted relay protocol for mobile connectivity.

Mobile app status: public rollout is coming soon; current pairing endpoints are primarily used for staged beta onboarding.

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.

Mobile Onboarding

  • GET /api/onboarding/qr (settings:read) — Generate QR code for mobile app pairing.
  • POST /api/onboarding/validate (settings:read) — Validate a mobile onboarding connection.
  • GET /api/onboarding/deep-link (settings:read) — Generate deep-link URL for mobile app.

🔌 WebSocket Endpoints

  • GET /ws – Primary UI WebSocket (browser sessions).
  • GET /api/agent/ws – Agent WebSocket used for AI command execution.

Note

: This is a summary of the most common endpoints. For a complete list, inspect the network traffic of the Pulse dashboard or check the source code in internal/api/router.go.