Run backup drill

POST/api/backup/drill

Proves an archive restores. The drill checks the archive, boots the app from its data on an isolated network and a free port, and asks the app's health endpoint for an answer. Protection: token. Without app, the drill runs for every app in the archive that has a health check. Without archive, it uses the newest archive.

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.

Body

application/json

appstring

The app to drill, such as gitea. Without it, every app in the archive that has a health check is drilled.

Example: gitea

archivestring

The path of the archive. Without it, the newest archive in the backup directory.

Response

200 · application/json

One result when you name an app, or a report with a results array when you do not. A drill that ran and failed is still 200: read passed and error.

objectobject

cURLcURLPythonJavaScript

curl --request POST \
  --url 'http://localhost:8080/api/backup/drill' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app": "gitea",
  "archive": "/home/you/backups/backup_2026-10-25_115840.971.tar.gz"
}'

{
  "app": "gitea",
  "archive": "/home/you/backups/backup_2026-10-25_115840.971.tar.gz",
  "size": "1.7 KB",
  "file_count": 9,
  "integrity": true,
  "booted": true,
  "boot_seconds": 0,
  "health_status": 200,
  "health_port": "41397",
  "passed": true,
  "total_seconds": 3,
  "drilled_at": "2026-10-25T18:58:42Z"
}