Skip to content

API Reference

Jump to bottom
Yousef Ghadiri edited this page Jun 14, 2026 · 6 revisions

API Reference

The Rust backend exposes a small HTTP API (served by Axum) that the frontend polls every 2 seconds.

Endpoints

Endpoint Method Description
GET / GET Serves the self-contained view.html dashboard
GET /health GET Returns server status, version, and uptime
GET /info GET Returns server info
GET /screenshot GET Returns a JSON array of base64-encoded PNG screen captures
GET /root_pids GET Returns a list of PIDs being tracked
GET /process/<PID> GET Returns root process info, child processes, CPU/memory stats, and work_done flag
GET /process/root/<PID> GET Returns only the root process snapshot, or 404 if it has exited
GET /process/children/<PID> GET Returns snapshots of all currently live child processes
GET /process/status/<PID> GET Lightweight summary — root alive/dead, child count, and work_done flag
GET /top-processes GET Returns the top N processes sorted by the given key
GET /supported-signals GET Returns a list of signals supported on the current platform
GET /system GET Returns the full system snapshot (CPU, memory, disks, network, battery, thermals, health)
GET /cpu GET Returns the current CPU snapshot only
GET /memory GET Returns the current memory snapshot only
GET /disks GET Returns per-disk snapshots
GET /networks GET Returns per-network-interface snapshots
GET /gpus GET Returns GPU snapshots (empty if no supported GPU detected)
GET /battery GET Returns the battery snapshot, or 404 if no battery present
GET /host-info GET Returns static host information (hostname, OS, kernel, arch, uptime)
GET /temperatures GET Returns thermal sensor readings
GET /docker-containers GET Returns snapshots of all tracked Docker containers (requires --docker)
GET /container/<id_or_name> GET Returns a snapshot for a specific container by ID or name, or 404 if not found
GET /top-containers GET Returns the top N containers sorted by CPU or memory (requires --docker)
GET /systemd GET Returns the full systemd snapshot (units, counts) — Linux only
GET /unit/<unit_name> GET Returns a snapshot for a specific unit by name, or 404 if not found
GET /units/<unit_state> GET Returns all units matching the given active state
GET /failed_units GET Returns all units currently in a failed state
POST /shutdown POST Gracefully shuts down the server

Process Command Endpoints

The following endpoints are only available when the server is started with --allow-process-commands. They always require authentication, regardless of whether --enable-auth is set.

Endpoint Method Description
POST /process/kill/<PID> POST Send a signal to a specific process
POST /process/kill-tree/<PID> POST Send SIGKILL to a root process and its entire descendant subtree
POST /process/track/<PID> POST Begin tracking a new root PID
POST /process/untrack/<PID> POST Stop tracking a root PID and discard its state
POST /process/poll/pause POST Pause the process polling loop
POST /process/poll/resume POST Resume the process polling loop
POST /process/poll/interval POST Change the polling interval

Docker Command Endpoints

The following endpoints are only available when the server is started with --allow-docker-commands. They always require authentication, regardless of whether --enable-auth is set.

Endpoint Method Description
POST /docker/stop-container POST Stop a container by ID or name, with an optional timeout before killing it
POST /docker/kill-container POST Send a signal to a container by ID or name
POST /docker/start-container POST Start a container by ID or name
POST /docker/restart-container POST Restart a container by ID or name, with an optional timeout
POST /docker/pause-container POST Pause (freeze) a container by ID or name
POST /docker/unpause-container POST Resume a paused container by ID or name
POST /docker/poll/pause POST Pause the Docker polling loop
POST /docker/poll/resume POST Resume the Docker polling loop
POST /docker/poll/interval POST Change the Docker polling interval

Response Shapes

GET /screenshot

{
  "screens": [
    {
      "mime": "image/png",
      "data": "<base64>",
      "monitor_name": "Built-in Display",
      "monitor_id": 0,
      "width": 1920,
      "height": 1080,
      "timestamp": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

GET /root_pids

[123, 12345]

GET /process/<PID>

{
  "work_done": false,
  "root": {
    "name": "my-app",
    "pid": 1234,
    "state": "running",
    "cpu_usage": 12.5,
    "memory_human": "128 MB"
  },
  "child_count": 2,
  "children": [...],
  "timestamp": "2025-01-01T00:00:00Z"
}

Process state can be running, sleeping, gone, or any other string (rendered as a warning-colored pill).

GET /process/root/<PID>

Returns a single ProcessInfo object, or 404 if the root process has exited.

GET /process/status/<PID>

{
  "root_alive": true,
  "root_pid": 1234,
  "root_name": "my-app",
  "child_count": 2,
  "work_done": false,
  "timestamp": "2025-01-01T00:00:00Z"
}

GET /health

{
  "status": "healthy",
  "timestamp": "2025-01-01T00:00:00Z",
  "version": "0.1.0",
  "uptime": "3600s"
}

GET /info

{
  "auth_enabled": false,
  "blind": false,
  "pid": [],
  "top_processes": false,
  "limit_processes": 5,
  "telegram_bot": false,
  "system_resources": false,
  "systemd": false,
  "allow_process_commands": false
}

GET /supported-signals

Returns a list of signal names supported on the current platform. On Windows only kill is supported; on all other platforms all five signals are available.

["kill", "int", "stop", "cont", "term"]

GET /top-processes?sort=cpu&limit=1

[
  {
    "name": "my-app",
    "pid": 1234,
    "state": "running",
    "cpu_usage": 12.5,
    "memory_human": "128 MB"
  }
]

POST /process/kill/<PID>

Request body:

{ "signal": "term" }

Valid signal values: kill, int, stop, cont, term. On Windows only kill is supported. Returns 200 OK on success, or 400 if the signal is invalid/unsupported, or 500 on failure.

POST /process/kill-tree/<PID>

No request body required. Sends SIGKILL to the root process and every process in its descendant subtree. Returns the list of PIDs that were successfully signalled:

[1234, 1235, 1236]

POST /process/track/<PID>

No request body required. Begins tracking a new root PID. A no-op if the PID is already tracked. Returns 200 OK.

POST /process/untrack/<PID>

No request body required. Stops tracking a root PID and discards its accumulated state. Returns 200 OK.

POST /process/poll/pause

No request body required. Pauses the polling loop. The tracker continues to handle queries and commands, but will not refresh process snapshots until resumed. Returns 200 OK.

POST /process/poll/resume

No request body required. Resumes polling at the current poll interval. Returns 200 OK.

POST /process/poll/interval

Request body:

{ "interval_ms": 2000 }

Changes the polling interval and restarts the tick timer immediately. Returns 200 OK.

GET /docker-containers

[
  {
    "id": "c6016895b3972516ac6188fe1a1e08903be7d6c4ae7ad5824cd730e6a14bee4c",
    "short_id": "c6016895b397",
    "name": "heuristic_lichterman",
    "image": "ubuntu",
    "status": "running",
    "health": "none",
    "stats": {
      "cpu_percent": 0.0,
      "memory_bytes": 13758464,
      "memory_limit_bytes": 8127688704,
      "memory_percent": 0.0016927892419438804,
      "net_rx_bytes": 1568,
      "net_tx_bytes": 126,
      "block_read_bytes": 12599296,
      "block_write_bytes": 0,
      "pid_count": 1
    }
  }
]

GET /container/<id_or_name>

Returns a single ContainerSnapshot object (same shape as array elements above), or 404 if not found.

GET /top-containers?sort=cpu&limit=5

Returns an array of ContainerSnapshot objects. The sort parameter accepts cpu or memory. limit defaults to all containers if omitted.

POST /docker/stop-container

{ "id_or_name": "my-container", "timeout_secs": 10 }

timeout_secs is optional. Returns 200 OK on success, or 500 on failure.

POST /docker/kill-container

{ "id_or_name": "my-container", "signal": "SIGKILL" }

Returns 200 OK on success, or 500 on failure.

POST /docker/start-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /docker/restart-container

{ "id_or_name": "my-container", "timeout_secs": 5 }

timeout_secs is optional. Returns 200 OK on success, or 500 on failure.

POST /docker/pause-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /docker/unpause-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /docker/poll/pause

No request body required. Pauses the Docker polling loop. The tracker continues to handle queries and commands, but will not refresh container snapshots until resumed. Returns 200 OK.

POST /docker/poll/resume

No request body required. Resumes polling at the current poll interval. Returns 200 OK.

POST /docker/poll/interval

{ "interval_ms": 2000 }

Changes the Docker polling interval and restarts the tick timer immediately. Returns 200 OK.

GET /system

health can be healthy, warning, or critical. Individual sub-endpoints (/cpu, /memory, /disks, /networks, /gpus, /battery, /host-info, /temperatures) return their respective nested objects directly.

Note: On Windows, the /temperatures endpoint requires running the app as administrator.

{
  "timestamp": "2025-01-01T00:00:00Z",
  "health": "healthy",
  "cpu": {
    "usage_percent": 14.2,
    "brand": "Intel(R) Core(TM) i9-13900K",
    "frequency_mhz": 3200,
    "physical_core_count": 24,
    "cores": [{ "name": "cpu0", "usage_percent": 12.1, "frequency_mhz": 3200 }],
    "load_avg": { "one": 0.45, "five": 0.60, "fifteen": 0.72 }
  },
  "memory": {
    "total_bytes": 34359738368,
    "used_bytes": 12884901888,
    "available_bytes": 21474836480,
    "free_bytes": 18253611008,
    "used_percent": 37.5,
    "swap_total_bytes": 4294967296,
    "swap_used_bytes": 0,
    "swap_free_bytes": 4294967296,
    "swap_used_percent": 0.0
  },
  "disks": [
    {
      "name": "/dev/sda1",
      "mount_point": "/",
      "file_system": "ext4",
      "kind": "Ssd",
      "is_removable": false,
      "total_bytes": 500107862016,
      "used_bytes": 120259084288,
      "available_bytes": 379848777728,
      "used_percent": 24.0
    }
  ],
  "networks": [
    {
      "interface": "eth0",
      "rx_bytes_per_sec": 2048,
      "tx_bytes_per_sec": 512,
      "rx_total_bytes": 1073741824,
      "tx_total_bytes": 536870912,
      "rx_packets_per_sec": 4,
      "tx_packets_per_sec": 2,
      "rx_errors": 0,
      "tx_errors": 0
    }
  ],
  "gpus": [],
  "battery": null,
  "temperatures": [
    {
      "label": "coretemp Package id 0",
      "temperature_celsius": 52.0,
      "temperature_max_celsius": 71.0,
      "temperature_critical_celsius": 100.0
    }
  ],
  "host": {
    "hostname": "my-machine",
    "os_name": "Ubuntu 24.04.1 LTS",
    "kernel_version": "6.8.0-40-generic",
    "cpu_arch": "x86_64",
    "uptime_secs": 86400,
    "process_count": 312
  }
}

GET /systemd

Linux only. Returns 404 on non-Linux platforms.

{
  "timestamp": "2025-01-01T00:00:00Z",
  "units": [
    {
      "unit_name": "nginx.service",
      "unit_type": "service",
      "load_state": "loaded",
      "active_state": "active",
      "sub_state": "running",
      "description": "A high performance web server and a reverse proxy server",
      "main_pid": 1234,
      "memory_bytes": 10485760,
      "cpu_usage_ns": 500000000,
      "restart_count": 0,
      "since": "2025-01-01T00:00:00Z",
      "fragment_path": "/lib/systemd/system/nginx.service"
    }
  ],
  "failed_count": 0,
  "active_count": 42,
  "inactive_count": 10
}

unit_type can be service, socket, target, timer, mount, device, or other.
load_state can be loaded, not_found, bad_setting, error, or masked.

GET /unit/<unit_name>

Returns a single UnitSnapshot object (same shape as array elements above), or 404 if not found.

GET /units/<unit_state>

Returns an array of UnitSnapshot objects matching the given active_state. Valid states: active, reloading, inactive, failed, activating, deactivating.

GET /failed_units

Returns an array of UnitSnapshot objects whose active_state is failed.

Clone this wiki locally