API reference

The HTTP API behind the homebutler web dashboard. homebutler serve starts it, and every route on this page is the same one the dashboard calls, so anything the dashboard shows or does you can read or run from a script.

Reads answer without a token when the server starts without one. Routes that change something exist only when the server starts with a token. Without a token those routes are not registered at all and answer 404, not 401.

Every error is a JSON object with one field: {"error": "<message>"}.

Base URL

http://localhost:8080

Authentication

• bearerAuth: send Authorization: Bearer <token>. 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. Each endpoint's page says whether it needs this.

OpenAPI specification

Download the full spec to import into Postman or Insomnia, generate a client, or give to an AI tool: openapi.yaml.

Endpoints

Overview and servers

Read the machine homebutler runs on, and the servers in your configuration.

	Endpoint
GET	/api/overview	Get overview
GET	/api/servers	List servers
GET	/api/servers/{name}/status	Get server status
GET	/api/status	Get system status
GET	/api/processes	List top processes
GET	/api/ports	List open ports

Report and doctor

Compare the machine with its last saved snapshot, and check it for problems.

	Endpoint
GET	/api/report	Get report
POST	/api/report/snapshot	Save report snapshot
GET	/api/doctor	Run doctor

Docker

List containers and their usage, and restart or stop a container.

	Endpoint
GET	/api/docker	List containers
GET	/api/docker/stats	Get container stats
POST	/api/docker/{name}/restart	Restart container
POST	/api/docker/{name}/stop	Stop container

Watch and alerts

Check alert thresholds, manage the watch list, and read recorded incidents.

	Endpoint
GET	/api/alerts	Check alerts
GET	/api/watch	Get watch list
GET	/api/watch/incidents	List incidents
GET	/api/watch/incidents/{id}	Get incident
POST	/api/watch/targets	Add watch target
POST	/api/watch/targets/{name}/remove	Remove watch target
POST	/api/watch/check	Run watch check

Backups

Create, list, drill and restore Docker compose backups.

	Endpoint
GET	/api/backup	List backups
POST	/api/backup	Create backup
POST	/api/backup/drill	Run backup drill
POST	/api/backup/restore	Restore backup

Install

Install, inspect, uninstall and purge the apps in the catalogue.

	Endpoint
GET	/api/install	List apps
GET	/api/install/{app}	Get app status
POST	/api/install/{app}	Install app
POST	/api/install/{app}/uninstall	Uninstall app
POST	/api/install/{app}/purge	Purge app

Proxmox

Read Proxmox VE endpoints and guests, and start, reboot or shut down a guest.

	Endpoint
GET	/api/proxmox/endpoints	List Proxmox endpoints
GET	/api/proxmox/status	Get Proxmox status
GET	/api/proxmox/guests	List Proxmox guests
POST	/api/proxmox/guests/{vmid}/start	Start Proxmox guest
POST	/api/proxmox/guests/{vmid}/reboot	Reboot Proxmox guest
POST	/api/proxmox/guests/{vmid}/shutdown	Shut down Proxmox guest

Wake and notify

Send a Wake-on-LAN packet and test your notification channels.

	Endpoint
GET	/api/wake	List wake targets
POST	/api/wake/{name}	Send wake packet
POST	/api/notify/test	Send test notification

Config

Read the settings the dashboard shows, and save changes to the config file.

	Endpoint
GET	/api/config	Get config
PUT	/api/config/alerts	Save alert thresholds
PUT	/api/config/notify	Save notification channels
PUT	/api/config/wake	Save wake targets
PUT	/api/config/servers	Save servers
PUT	/api/config/proxmox	Save Proxmox endpoints

Meta

Ask the server what it can do, which version it is, and what its CORS preflight allows.

	Endpoint
GET	/api/capabilities	List capabilities
GET	/api/version	Get version
OPTIONS	/api/	Answer a CORS preflight