Create backup

POST/api/backup

Archives the volumes of the Docker compose services that are running, into your backup directory. Protection: token. Volumes are read while the containers run, so an archive is not proof it restores: Run backup drill is.

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

servicestring

Back up only this compose service. Without it, every running compose service is backed up.

Example: gitea

excludestring[]

Mount sources to leave out of the archive.

Response

200 · application/json

The archive that was written.

archivestringrequired

The path of the archive.

servicesstring[]required

The compose services in the archive.

volumesintegerrequired

The number of mounts written.

sizestringrequired

The archive size as text, such as 1.7 KB.

skippedstring[]

Mounts left out by exclude, as service:source.

unmatched_excludesstring[]

Entries of exclude that matched no mount.

prunedobject

cURL

curl --request POST \
  --url 'http://localhost:8080/api/backup' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "service": "gitea",
  "exclude": [
    "/nonexistent"
  ]
}'

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