Get server status

GET/api/servers/{name}/status

Returns the system status of one configured server. A server marked local is read directly; any other is read over SSH by running homebutler status --json on it.

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.

Path parameters

namestringrequired

The name of a server, from List servers.

Example: homelab

Response

200 · application/json

The server's 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/servers/{name}/status' \
  --header 'Authorization: Bearer <token>'

{
  "schema_version": 1,
  "hostname": "homelab",
  "os": "linux",
  "arch": "amd64",
  "uptime": "15h 39m",
  "cpu": {
    "usage_percent": 4.65,
    "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:48-07:00"
}