Get system status

GET/api/status

Returns CPU, memory and disk readings for the machine homebutler runs on, or for the server named in server.

Authorizations

Authorizationstringheader

The token you start the server with: homebutler serve --token <token>, or web.token in the config file. Send it as Authorization: Bearer <token>. When the server has a token, every /api/ route except the CORS preflight requires it, reads included.

Query parameters

serverstring

The name of a remote server from List servers. homebutler runs the command on it over SSH and returns its answer. Leave it out, name the local server, or name a server that is not in the config, to read this machine.

Example: nas

Response

200 · application/json

The system status. The example is shortened.

The system status document. It is frozen at schema version 1.

hostnamestringrequired

Host name.

osstringrequired

Operating system, such as linux.

archstringrequired

CPU architecture, such as amd64.

uptimestringrequired

Time since boot, as text such as 15h 15m.

cpuobjectrequired

memoryobjectrequired

disksobject[]required

One entry per mounted disk.

timestringrequired

The time of the reading, RFC 3339 with the machine's offset.

schema_versionintegerrequired

The version of this document's shape. It is 1.

cURLcURLPythonJavaScript

curl --request GET \
  --url 'http://localhost:8080/api/status?server=nas' \
  --header 'Authorization: Bearer <token>'

{
  "schema_version": 1,
  "hostname": "homelab",
  "os": "linux",
  "arch": "amd64",
  "uptime": "15h 39m",
  "cpu": {
    "usage_percent": 0,
    "cores": 4
  },
  "memory": {
    "total_gb": 7.75,
    "used_gb": 2.83,
    "usage_percent": 36.53
  },
  "disks": [
    {
      "mount": "/",
      "total_gb": 19,
      "used_gb": 1.2,
      "usage_percent": 7
    }
  ],
  "time": "2026-10-25T11:57:49-07:00"
}