API Reference

API Reference

Pankha exposes a REST API for configuration and a WebSocket interface for real-time data. Base URL: http://<server-ip>:3143

---

Health & Status

Method	Endpoint	Description
GET	/health	Backend health check with service statistics
GET	/api/overview	Aggregate stats across all systems
GET	/api/websocket/info	WebSocket connection info and stats
POST	/api/emergency-stop	Set all fans to 100% on all systems

---

Systems

List & CRUD

Method	Endpoint	Description
GET	/api/systems	List all registered agents
POST	/api/systems	Add new system
GET	/api/systems/limit	Get agent limit info (current count, tier limit)
GET	/api/systems/:id	Get system details with sensors/fans
PUT	/api/systems/:id	Update system configuration
DELETE	/api/systems/:id	Remove system
GET	/api/systems/:id/status	Real-time connection status
GET	/api/systems/:id/diagnostics	Get hardware diagnostics from agent

Controller

Method	Endpoint	Description
GET	/api/systems/controller/status	Fan profile controller status
PUT	/api/systems/controller/interval	Set controller update interval

Sensors

Method	Endpoint	Description
GET	/api/systems/:id/sensors	Get all sensors for system
PUT	/api/systems/:id/sensors/:sensorId/label	Set custom sensor label
PUT	/api/systems/:id/sensors/:sensorId/visibility	Show/hide sensor
GET	/api/systems/:id/sensor-visibility	Get visibility settings
PUT	/api/systems/:id/sensor-groups/:groupName/visibility	Show/hide sensor group

Fans

Method	Endpoint	Description
GET	/api/systems/:id/fans	Get all fans for system
PUT	/api/systems/:id/fans/:fanId	Set fan speed (0-100%)
PUT	/api/systems/:id/fans/:fanId/label	Set custom fan label

Agent Settings

Method	Endpoint	Description
PUT	/api/systems/:id/update-interval	Set agent polling interval (seconds)
PUT	/api/systems/:id/fan-step	Set fan speed step % (smoothing)
PUT	/api/systems/:id/hysteresis	Set temperature hysteresis (°C)
PUT	/api/systems/:id/emergency-temp	Set emergency temperature threshold
PUT	/api/systems/:id/failsafe-speed	Set failsafe fan speed (0-100%)
PUT	/api/systems/:id/enable-fan-control	Enable/disable fan control
PUT	/api/systems/:id/log-level	Set agent log level
PUT	/api/systems/:id/name	Set agent display name
POST	/api/systems/:id/update	Trigger remote agent self-update

Backend Settings

Method	Endpoint	Description
GET	/api/systems/settings	Get all backend settings
GET	/api/systems/settings/:key	Get a specific setting by key
PUT	/api/systems/settings/:key	Update a setting ({ "value": "..." })

Allowed setting keys: controller_update_interval, graph_history_hours, data_retention_days, accent_color, hover_tint_color

Profiles & History

Method	Endpoint	Description
PUT	/api/systems/:id/profile	Assign profile to system
POST	/api/systems/:id/profiles	Create system-specific profile
GET	/api/systems/:id/history	Get historical sensor/fan data
GET	/api/systems/:id/charts	Get aggregated chart data

---

Fan Profiles

Method	Endpoint	Description
GET	/api/fan-profiles	List all profiles
GET	/api/fan-profiles/:id	Get profile details
POST	/api/fan-profiles	Create new profile
PUT	/api/fan-profiles/:id	Update profile
DELETE	/api/fan-profiles/:id	Delete profile
GET	/api/fan-profiles/stats	Profile statistics
POST	/api/fan-profiles/assign	Assign profile to fan
GET	/api/fan-profiles/assignments/:systemId	Get fan assignments
POST	/api/fan-profiles/calculate-speed	Calculate speed for temp
GET	/api/fan-profiles/export	Export profiles to JSON
POST	/api/fan-profiles/import	Import profiles from JSON
GET	/api/fan-profiles/defaults	List available default profiles
POST	/api/fan-profiles/load-defaults	Load default profiles into database

---

Fan Configurations

Method	Endpoint	Description
GET	/api/fan-configurations/:systemId	Get fan configurations
POST	/api/fan-configurations/sensor	Configure fan sensor mapping

---

Discovery

Method	Endpoint	Description
POST	/api/discovery/scan	Scan network for agents
GET	/api/discovery/hardware	Get discovered hardware
POST	/api/discovery/test-fan	Test fan control
GET	/api/discovery/systems/:id/sensors/scan	Scan for new sensors
PUT	/api/discovery/systems/:id/sensors/:sensorId	Update discovered sensor
POST	/api/discovery/systems/:id/sensor-mapping	Map sensors to labels

---

Deploy

Method	Endpoint	Description
POST	/api/deploy/templates	Generate a deployment token (expires in 24h)
GET	/api/deploy/linux	Serve dynamic install script (?token=<token>)
GET	/api/deploy/hub/status	Status of locally cached agent binaries
POST	/api/deploy/hub/stage	Download a specific agent version to the hub
DELETE	/api/deploy/hub/clear	Clear all locally cached agent binaries
GET	/api/deploy/binaries/:arch	Serve cached agent binary (x86_64 / aarch64)

---

Config

Method	Endpoint	Description
GET	/api/config/deployment	Get deployment config (hub IP and port)

---

License

Method	Endpoint	Description
GET	/api/license	Get current license info (tier, limits, expiration)
POST	/api/license	Activate license key
DELETE	/api/license	Remove license (revert to free tier)
GET	/api/license/pricing	Get tier pricing info
POST	/api/license/sync	Force sync with license server (check for renewals)

---

WebSocket API

Endpoint: ws://<server-ip>:3143/websocket

Events (Server → Client)

Event	Description
fullState	Complete snapshot on connection
systemDelta	Incremental updates (bandwidth optimized)
agentRegistered	Agent connected
agentOffline	Agent disconnected
agentError	Agent error occurred
agentConfigUpdated	Config change (immediate broadcast)

Example: systemDelta

{
  "type": "systemDelta",
  "data": {
    "agentId": "linux-agent-1",
    "timestamp": "2025-01-01T12:00:00Z",
    "changes": ["sensors", "fans"],
    "sensors": [{ "id": "temp1", "temperature": 45.2 }],
    "fans": [{ "id": "fan1", "rpm": 1200, "speed": 40 }]
  }
}

---

Quick Examples

Set Fan Speed

curl -X PUT http://localhost:3143/api/systems/1/fans/fan1 \
  -H "Content-Type: application/json" \
  -d '{"speed": 75}'

Create Fan Profile

curl -X POST http://localhost:3143/api/fan-profiles \
  -H "Content-Type: application/json" \
  -d '{
    "profile_name": "Silent",
    "curve_points": [
      {"temperature": 30, "fan_speed": 30},
      {"temperature": 50, "fan_speed": 50},
      {"temperature": 70, "fan_speed": 100}
    ]
  }'

Check Health

curl http://localhost:3143/health

---

Error Responses

{
  "success": false,
  "error": "Error message",
  "message": "Detailed description"
}

Code	Meaning
200	Success
201	Created
400	Bad request
403	Forbidden (license limit / read-only mode)
404	Not found
500	Server error
503	Service unavailable

---

Notes

• Authentication: Not required in current version
• Rate Limiting: None enforced; use WebSocket for real-time updates
• URL Parameters: Replace :id, :fanId, etc. with actual values