Restore backup

POST/api/backup/restore

Writes the volumes in an archive back to the machine, replacing the data in them. Protection: token and confirm_name equal to archive. The restore refuses bind mounts that the archive declares: they come back in refused and nothing is written to them.

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

archivestringrequired

The path of the archive, from List backups.

servicestring

Restore only this service.

confirm_namestringrequired

The same value as archive.

Response

200 · application/json

The services and volumes that were restored.

archivestringrequired

The archive restored.

servicesstring[]required

The services restored.

volumesintegerrequired

The number of mounts written.

refusedobject[]

Mounts the restore would not write.

cURL

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

{
  "archive": "/home/you/backups/backup_2026-10-25_115840.971.tar.gz",
  "services": [
    "gitea"
  ],
  "volumes": 1
}