Save report snapshot

POST/api/report/snapshot

Builds a report and saves it as the snapshot the next report compares against. Protection: token.

Authorizations

Authorizationstringheaderrequired

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 report that was just built, with snapshot_saved set to true. The example is shortened.

The report plus a count of each list, for widgets that cannot take the length of an array.

schema_versionintegerrequired

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

timestampstringrequired

When the report was built, RFC 3339 in UTC.

server_namestringrequired

The name of the server the report is about.

is_baselinebooleanrequired

true when there was no snapshot to compare against.

snapshot_savedbooleanrequired

true when this report was saved as the new snapshot.

compared_tostring

The timestamp of the snapshot this report was compared with. Absent for a baseline.

systemobject

running_countintegerrequired

Running containers. null when Docker did not answer.

stopped_countintegerrequired

Stopped containers. null when Docker did not answer.

public_port_countintegerrequired

Ports open to the network. null when ports could not be listed.

statusstring[]required

One sentence per measured area.

needs_attentionobject[]required

Problems found now.

notable_changesobject[]required

Differences from the snapshot.

suggested_actionsobject[]required

Next steps, each with the command that runs it.

failed_collectorsstring[]

The collectors that failed. A count is trustworthy only when its collector is absent here.

warningsstring[]

Problems that did not stop the report, such as an unreadable snapshot.

summaryobjectrequired

The length of each list.

cURLcURLPythonJavaScript

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

{
  "schema_version": 1,
  "timestamp": "2026-10-25T18:58:26Z",
  "server_name": "homelab",
  "is_baseline": false,
  "snapshot_saved": true,
  "system": {
    "hostname": "homelab",
    "os": "linux",
    "arch": "amd64",
    "uptime": "15h 40m",
    "cpu": {
      "usage_percent": 3.84,
      "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:58:25-07:00"
  },
  "running_count": 8,
  "stopped_count": 11,
  "public_port_count": 11,
  "status": [
    "Host: homelab (linux/amd64), uptime 15h 40m",
    "CPU: 3.8% (4 cores), Memory: 2.8/7.8 GB (37%)",
    "Disk /: 1.2/19.0 GB (7%)",
    "Containers: 8 running, 11 stopped",
    "Public ports: 11"
  ],
  "needs_attention": [
    {
      "kind": "container",
      "text": "11 container(s) stopped"
    },
    {
      "kind": "container",
      "target": "whoami",
      "text": "whoami stopped since the last report"
    }
  ],
  "notable_changes": [
    {
      "kind": "state",
      "target": "whoami",
      "detail": "running → exited",
      "text": "state: whoami — running → exited"
    }
  ],
  "compared_to": "2026-10-25T18:58:09Z",
  "suggested_actions": [
    {
      "text": "Check why whoami is not running: homebutler docker logs whoami",
      "command": "homebutler docker logs whoami",
      "runner": "mcp",
      "tool": "docker_logs"
    }
  ],
  "summary": {
    "needs_attention": 3,
    "notable_changes": 1
  }
}