Skip to content

API Reference

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

API Reference

The Rust backend exposes a small HTTP API (served by Axum) that the frontend polls every 2 seconds. All endpoints are prefixed with /api.

Endpoints

General

Endpoint Method Description
GET /api/health GET Returns server status, version, and uptime
GET /api/info GET Returns server info
POST /api/shutdown POST Gracefully shuts down the server

Screenshots

Endpoint Method Description
GET /api/screenshot GET Returns a JSON array of base64-encoded PNG screen captures

Process Tracking

Endpoint Method Description
GET /api/root_pids GET Returns a list of PIDs being tracked
GET /api/process/<PID> GET Returns root process info, child processes, CPU/memory stats, and work_done flag
GET /api/process/trees GET Returns all process trees currently being tracked
GET /api/process/root/<PID> GET Returns only the root process snapshot, or 404 if it has exited
GET /api/process/children/<PID> GET Returns snapshots of all currently live child processes
GET /api/process/status/<PID> GET Lightweight summary — root alive/dead, child count, and work_done flag
GET /api/process/is-done/<PID> GET Returns whether all children have exited for a given root PID, or 404 if not tracked
GET /api/top-processes GET Returns the top N processes sorted by the given key
GET /api/supported-signals GET Returns a list of signals supported on the current platform

System Resources

Endpoint Method Description
GET /api/system GET Returns the full system snapshot (CPU, memory, disks, network, battery, thermals, health)
GET /api/cpu GET Returns the current CPU snapshot only
GET /api/memory GET Returns the current memory snapshot only
GET /api/disks GET Returns per-disk snapshots
GET /api/networks GET Returns per-network-interface snapshots
GET /api/gpus GET Returns GPU snapshots (empty if no supported GPU detected)
GET /api/battery GET Returns the battery snapshot, or 404 if no battery present
GET /api/host-info GET Returns static host information (hostname, OS, kernel, arch, uptime)
GET /api/temperatures GET Returns thermal sensor readings

Docker

Endpoint Method Description
GET /api/docker-containers GET Returns snapshots of all tracked Docker containers (requires --docker)
GET /api/container/<id_or_name> GET Returns a snapshot for a specific container by ID or name, or 404 if not found
GET /api/top-containers GET Returns the top N containers sorted by CPU or memory (requires --docker)

Systemd

Endpoint Method Description
GET /api/systemd GET Returns the full systemd snapshot (units, counts) — Linux only
GET /api/unit/<unit_name> GET Returns a snapshot for a specific unit by name, or 404 if not found
GET /api/units/<unit_state> GET Returns all units matching the given active state
GET /api/failed_units GET Returns all units currently in a failed state

Auth Endpoints

Available when auth is enabled (see Authentication).

Endpoint Method Description
POST /api/auth/login POST Authenticates a user and returns a session token
POST /api/auth/logout POST Invalidates the current session token

Process Command Endpoints

Only available when started with --allow-process-commands. Always require authentication, regardless of whether --enable-auth is set.

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

Screen Capture Command Endpoints

Only available when started with --allow-screen-commands (and without --blind). Always require authentication.

Endpoint Method Description
POST /api/screen/poll/pause POST Pause the screen capture polling loop
POST /api/screen/poll/resume POST Resume the screen capture polling loop
POST /api/screen/poll/interval POST Change the screen capture polling interval

System Resources Command Endpoints

Only available when started with --allow-system-resources-commands. Always require authentication.

Endpoint Method Description
POST /api/resources/thresholds POST Update alert thresholds for CPU, memory, disk, and battery
POST /api/resources/refresh-mask POST Update which subsystems are collected on each tick
POST /api/resources/poll/pause POST Pause the system resources polling loop
POST /api/resources/poll/resume POST Resume the system resources polling loop
POST /api/resources/poll/interval POST Change the system resources polling interval

Systemd Command Endpoints

Only available when started with --allow-systemd-commands. Always require authentication.

Endpoint Method Description
POST /api/systemd/poll/pause POST Pause the systemd polling loop
POST /api/systemd/poll/resume POST Resume the systemd polling loop
POST /api/systemd/poll/interval POST Change the systemd polling interval

Docker Command Endpoints

Only available when started with --allow-docker-commands. Always require authentication.

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

Authentication

Auth is automatically enabled when any of the following flags are set: --enable-auth, --allow-process-commands, --allow-screen-commands, --allow-system-resources-commands, --allow-systemd-commands, --allow-docker-commands.

POST /api/auth/login

Request body:

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

Response:

{ "token": "550e8400-e29b-41d4-a716-446655440000" }

Returns 401 Unauthorized if credentials are invalid, or 404 Not Found if no users are configured.

POST /api/auth/logout

Requires a Bearer token in the Authorization header. Returns 200 OK on success.

Response Shapes

GET /api/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 /api/root_pids

[123, 12345]

GET /api/process/<PID>

{
  "root_pid": 1234,
  "root": {
    "pid": 1234,
    "name": "my-app",
    "state": "running",
    "cpu_usage": 12.5,
    "memory_bytes": 134217728,
    "disk_usage": 0
  },
  "children": [...],
  "child_count": 2,
  "work_done": false,
  "timestamp": "2025-01-01T00:00:00Z"
}

GET /api/process/trees

Returns an array of ProcessTree objects (same shape as GET /api/process/<PID>).

GET /api/process/root/<PID>

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

{
  "pid": 1234,
  "name": "my-app",
  "state": "running",
  "cpu_usage": 12.5,
  "memory_bytes": 134217728,
  "disk_usage": 0
}

Note (Linux only): ProcessSnapshot may also include cwd (string or null), cmdline (array of strings), open_files (array of file descriptor info), and io_stats (object or null).

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

GET /api/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 /api/process/is-done/<PID>

Returns a JSON boolean. 404 if the root PID is not tracked.

false

GET /api/health

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

GET /api/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 /api/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 /api/top-processes?sort=cpu&limit=1

Query parameters:

  • sort: cpu, memory, or disk
  • limit: number of results (default: all)
[
  {
    "pid": 1234,
    "name": "my-app",
    "state": "running",
    "cpu_usage": 12.5,
    "memory_bytes": 134217728,
    "disk_usage": 0
  }
]

POST /api/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, 400 if the signal is invalid/unsupported, or 500 on failure.

POST /api/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 /api/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 /api/process/untrack/<PID>

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

POST /api/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 /api/process/poll/resume

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

POST /api/process/poll/interval

{ "interval_ms": 2000 }

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

POST /api/resources/thresholds

{
  "cpu_warn": 85.0,
  "memory_warn": 90.0,
  "disk_warn": 95.0,
  "battery_low": 20.0
}

All fields are optional. Returns 200 OK on success.

POST /api/resources/refresh-mask

{
  "cpu": true,
  "memory": true,
  "disks": true,
  "networks": true,
  "temperatures": false,
  "gpus": false
}

Controls which subsystems are collected on each polling tick. Returns 200 OK on success.

POST /api/resources/poll/pause / POST /api/resources/poll/resume

No request body required. Returns 200 OK.

POST /api/resources/poll/interval

{ "interval_ms": 2000 }

Returns 200 OK.

POST /api/screen/poll/pause / POST /api/screen/poll/resume

No request body required. Returns 200 OK.

POST /api/screen/poll/interval

{ "interval_ms": 2000 }

Returns 200 OK.

GET /api/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 /api/container/<id_or_name>

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

GET /api/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 /api/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 /api/docker/kill-container

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

Returns 200 OK on success, or 500 on failure.

POST /api/docker/start-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /api/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 /api/docker/pause-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /api/docker/unpause-container

{ "id_or_name": "my-container" }

Returns 200 OK on success, or 500 on failure.

POST /api/docker/poll/pause / POST /api/docker/poll/resume

No request body required. Returns 200 OK.

POST /api/docker/poll/interval

{ "interval_ms": 2000 }

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

POST /api/systemd/poll/pause / POST /api/systemd/poll/resume

No request body required. Returns 200 OK.

POST /api/systemd/poll/interval

{ "interval_ms": 2000 }

Returns 200 OK.

GET /api/system

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

Note: On Windows, the /api/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 /api/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 /api/unit/<unit_name>

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

GET /api/units/<unit_state>

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

GET /api/failed_units

Returns an array of UnitSnapshot objects whose active_state is failed.

Clone this wiki locally