Pulse/docs/API.md

Pulse API Documentation

Overview

Pulse provides a REST API for monitoring and managing Proxmox VE and PBS instances. All API endpoints are prefixed with /api.

Authentication

API authentication is optional but recommended for production use.

Setting up API Authentication

# Systemd
sudo systemctl edit pulse-backend
# Add:
[Service]
Environment="API_TOKEN=your-secure-token-here"

# Docker
docker run -e API_TOKEN=your-secure-token rcourtman/pulse:latest

Using API Authentication

Include the token in the X-API-Token header:

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

Core Endpoints

Health Check

Check if Pulse is running and healthy.

GET /api/health

Response:

{
  "status": "healthy",
  "timestamp": 1754995749,
  "uptime": 166.187561244
}

Version Information

Get current Pulse version and build info.

GET /api/version

Response:

{
  "version": "v4.2.1",
  "build": "release",
  "runtime": "go",
  "channel": "stable",
  "isDocker": false,
  "isDevelopment": false
}

System State

Get complete system state including all nodes and their metrics.

GET /api/state

Response includes all monitored nodes, VMs, containers, storage, and backups.

Monitoring Data

Charts Data

Get time-series data for charts (CPU, memory, storage).

GET /api/charts
GET /api/charts?range=1h  # Last hour (default)
GET /api/charts?range=24h # Last 24 hours
GET /api/charts?range=7d  # Last 7 days

Storage Information

Get detailed storage information for all nodes.

GET /api/storage/
GET /api/storage/<node-id>

Storage Charts

Get storage usage trends over time.

GET /api/storage-charts

Backup Information

Get backup information across all nodes.

GET /api/backups          # All backups
GET /api/backups/unified  # Unified view
GET /api/backups/pve      # PVE backups only
GET /api/backups/pbs      # PBS backups only

Snapshots

Get snapshot information for VMs and containers.

GET /api/snapshots

Configuration

Node Management

Manage Proxmox VE and PBS nodes.

GET /api/config/nodes                    # List all nodes
POST /api/config/nodes                   # Add new node
PUT /api/config/nodes/<node-id>         # Update node
DELETE /api/config/nodes/<node-id>      # Remove node
POST /api/config/nodes/test-connection  # Test node connection

Add Node Example

curl -X POST http://localhost:7655/api/config/nodes \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "type": "pve",
    "name": "My PVE Node",
    "host": "https://192.168.1.100:8006",
    "user": "monitor@pve",
    "password": "password",
    "verifySSL": false
  }'

System Configuration

Get and update system configuration.

GET /api/config/system   # Get system config
POST /api/config/system  # Update system config

Export/Import Configuration

Backup and restore Pulse configuration.

POST /api/config/export  # Export encrypted config
POST /api/config/import  # Import encrypted config

Note: Requires API_TOKEN or ALLOW_UNPROTECTED_EXPORT=true

Notifications

Email Configuration

Manage email notification settings.

GET /api/notifications/email          # Get email config
POST /api/notifications/email         # Update email config
POST /api/notifications/email/test    # Send test email
GET /api/notifications/email-providers # List email providers

Webhook Configuration

Manage webhook notification endpoints.

GET /api/notifications/webhooks                    # List all webhooks
POST /api/notifications/webhooks                   # Create new webhook
PUT /api/notifications/webhooks/<id>               # Update webhook
DELETE /api/notifications/webhooks/<id>            # Delete webhook
POST /api/notifications/webhooks/test              # Test webhook
GET /api/notifications/webhook-templates           # Get service templates

Create Webhook Example

curl -X POST http://localhost:7655/api/notifications/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "name": "Discord Alert",
    "url": "https://discord.com/api/webhooks/xxx/yyy",
    "method": "POST",
    "service": "discord",
    "enabled": true
  }'

Custom Payload Template Example

curl -X POST http://localhost:7655/api/notifications/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "name": "Custom Webhook",
    "url": "https://my-service.com/webhook",
    "method": "POST",
    "service": "generic",
    "enabled": true,
    "template": "{\"alert\": \"{{.Level}}: {{.Message}}\", \"value\": {{.Value}}}"
  }'

Test Webhook

curl -X POST http://localhost:7655/api/notifications/webhooks/test \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "name": "Test",
    "url": "https://example.com/webhook",
    "service": "generic"
  }'

Alert Thresholds

Manage alert thresholds and overrides.

GET /api/notifications/thresholds            # Get thresholds
POST /api/notifications/thresholds           # Update thresholds
GET /api/notifications/thresholds/overrides  # Get overrides
POST /api/notifications/thresholds/overrides # Set overrides

Alert History

View alert history and manage alerts.

GET /api/notifications/alerts         # Get recent alerts
POST /api/notifications/alerts/clear  # Clear alert history

Auto-Registration

Setup Script

Generate setup script for automatic node configuration.

POST /api/setup-script

Request:

{
  "type": "pve",
  "host": "https://192.168.1.100:8006"
}

Auto-Register Node

Register a node automatically (used by setup scripts).

POST /api/auto-register

With registration token (if required):

curl -X POST http://localhost:7655/api/auto-register \
  -H "X-Registration-Token: PULSE-REG-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pve",
    "host": "https://node.local:8006",
    "name": "Node Name",
    "username": "monitor@pam",
    "tokenId": "token-id",
    "tokenValue": "token-secret"
  }'

Registration Tokens

Manage registration tokens for secure node registration.

POST /api/tokens/generate  # Generate new token
GET /api/tokens/list       # List active tokens
DELETE /api/tokens/revoke  # Revoke a token

Generate Token Example

curl -X POST http://localhost:7655/api/tokens/generate \
  -H "X-API-Token: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "validityMinutes": 30,
    "maxUses": 5,
    "allowedTypes": ["pve", "pbs"],
    "description": "Production cluster setup"
  }'

Updates

Check for Updates

Check if a new version is available.

GET /api/updates/check

Apply Update

Download and apply an available update.

POST /api/updates/apply

Update Status

Get current update operation status.

GET /api/updates/status

WebSocket

Real-time updates are available via WebSocket connection.

const ws = new WebSocket('ws://localhost:7655/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

The WebSocket broadcasts state updates every few seconds with the complete system state.

Rate Limiting

Some endpoints have rate limiting:

• Export/Import: 5 requests per minute
• Test email: 10 requests per minute
• Update check: 10 requests per hour

Error Responses

All endpoints return standard HTTP status codes:

• 200 OK - Success
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Missing or invalid API token
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limited
• 500 Internal Server Error - Server error

Error response format:

{
  "error": "Error message description"
}

Examples

Full Example: Monitor a New Node

# 1. Test connection to node
curl -X POST http://localhost:7655/api/config/nodes/test-connection \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "type": "pve",
    "host": "https://192.168.1.100:8006",
    "user": "root@pam",
    "password": "password"
  }'

# 2. Add the node if test succeeds
curl -X POST http://localhost:7655/api/config/nodes \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your-token" \
  -d '{
    "type": "pve",
    "name": "pve-node-1",
    "host": "https://192.168.1.100:8006",
    "user": "root@pam",
    "password": "password",
    "verifySSL": false
  }'

# 3. Get monitoring data
curl -H "X-API-Token: your-token" http://localhost:7655/api/state

# 4. Get chart data
curl -H "X-API-Token: your-token" http://localhost:7655/api/charts?range=1h

PowerShell Example

# Set variables
$apiUrl = "http://localhost:7655/api"
$apiToken = "your-secure-token"
$headers = @{ "X-API-Token" = $apiToken }

# Check health
$health = Invoke-RestMethod -Uri "$apiUrl/health" -Headers $headers
Write-Host "Status: $($health.status)"

# Get all nodes
$nodes = Invoke-RestMethod -Uri "$apiUrl/config/nodes" -Headers $headers
$nodes | ForEach-Object { Write-Host "Node: $($_.name) - $($_.status)" }

Python Example

import requests

API_URL = "http://localhost:7655/api"
API_TOKEN = "your-secure-token"
headers = {"X-API-Token": API_TOKEN}

# Check health
response = requests.get(f"{API_URL}/health", headers=headers)
health = response.json()
print(f"Status: {health['status']}")

# Get monitoring data
response = requests.get(f"{API_URL}/state", headers=headers)
state = response.json()
for node in state.get("nodes", []):
    print(f"Node: {node['name']} - {node['status']}")