API and integrations¶
BombVault has a small HTTP API for scripts, dashboards and home automation. It reads the same things the overview shows and can start a backup. Everything else, such as restores, deleting backups, settings and nodes, stays in the web interface.
Tokens¶
Every request needs an API token, even when no login password is set. Create one under Settings, Integrations, API tokens:
- Type a name that says where the token is used, for example "Home Assistant" or "Uptime Kuma".
- Switch Allow starting backups on if the token should be able to start backups. Without it the token can only read.
- Click Create token. The token is shown once. BombVault keeps only a fingerprint of it, so copy it now.
Send the token in a header, either Authorization: Bearer <token> or X-API-Key: <token>. A token starts with bvapi_. It only opens the API: an MCP key does not work here, and a token does not work for MCP.
Each token has a tile with its name, whether it may start backups, the last four characters, when it was last used and from where, and its calls today. On the tile you can rename it, change what it may do, replace it or revoke it. Log shows the backups it started and its recent calls. Restoring BombVault's configuration from a backup revokes every token, because the backup may hold tokens you revoked later.
Without a login password, anyone who can open the web interface can also create a token. If you open BombVault under a public-looking name and no password is set, tokens cannot be created from that address, the same rule as for MCP keys.
Endpoints¶
| Route | What it returns or does | Token |
|---|---|---|
GET /api/v1/health |
Version, instance name, whether a backup is running, and what this token may do | read |
GET /api/v1/status |
Protection status per domain: last successful backup, expected interval, checks, next scheduled runs | read |
GET /api/v1/activity |
What is running right now, with phase and percentage | read |
GET /api/v1/items |
Every protected item with its schedule, what a backup stops and its last backup. ?domain= for one domain |
read |
GET /api/v1/runs |
Run history, newest first. Filters limit, domain, item, status, kind, since |
read |
GET /api/v1/anomalies |
Anomalies with a summary of what is open. Filters state, severity, domain, limit |
read |
GET /api/v1/anomalies/{id} |
One anomaly | read |
GET /api/v1/storage/{domain} |
Size history, growth per week, and free space of each repository of a domain | read |
POST /api/v1/backups |
Backs up one item ({"domain":"containers","item":"plex"}) or a whole domain ({"domain":"vms"}) |
start |
POST /api/v1/backups/everything |
Runs the Backup Everything pass | start |
POST /api/v1/runs/{id}/cancel |
Cancels a running backup that this token started | start |
The domains are containers, vms, files, zfs, flash and config. Times are unix seconds. The answers are the same as those of the MCP tools with the same names, so both stay in step.
A started backup is the same backup the web interface starts: a running container is stopped until its backup is done. The request returns at once, and /api/v1/activity and /api/v1/runs show how it goes.
Examples¶
# How are the backups doing?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Back up one container now.
curl -s -X POST -H "Authorization: Bearer $BOMBVAULT_TOKEN" \
-H "Content-Type: application/json" -d '{"domain":"containers","item":"plex"}' \
https://tower:3443/api/v1/backups
With BombVault's own self-signed certificate, add --cacert bombvault-cert.pem (the file Download certificate on the MCP card gives you) or -k on a network you trust.
Errors and limits¶
An error comes back as {"error": {"code": "...", "message": "..."}} with a matching status:
| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_argument, ambiguous |
An argument is missing or wrong |
| 401 | no_token, invalid_token |
No token, or not an active one |
| 403 | not_permitted, forbidden_origin |
The token may only read, the run was not started by it, or the request came from a page on another origin |
| 404 | not_found |
No such item, run or anomaly |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Something else is running, the domain is off, or there is nothing to do |
| 429 | throttled, rate_limited, cooldown, retention_guard |
A limit holds the request back. Retry-After says when to try again |
Starts follow the same limits as starts through MCP: 12 per hour per token, 15 minutes between two starts of the same item, at most 4 starts of one item in 24 hours, and the retention guard. The last three count starts through MCP, the API and Home Assistant together. A token can make 120 requests a minute. Five failed attempts from one address lock it out for a minute.
OpenAPI¶
BombVault serves a description of these routes at /api/v1/openapi.json (OpenAPI 3.1). It needs no token. Load it into Swagger UI, Postman or a code generator.
Nodes¶
The routes that look after nodes belong to the web interface, not to the token API above. With a login password set they need a browser session from a sign-in at this instance. An API token or an MCP key opens none of them, paired phones do not reach them, and /api/v1/openapi.json does not describe them. Adding a node, showing its compose file again and reaching a node's own routes are refused until a login password is set. A script that changes something sends Content-Type: application/json, as everywhere in the web interface.
| Route | What it does |
|---|---|
GET /api/nodes |
Every node with whether it is online, its version, where its backups go, the plan of each section, its last backup, its errors and its open anomalies |
POST /api/nodes |
Adds a node, such as {"name":"vps-helsinki"}, and returns it with compose: MODE, APP_KEY, NODE_HOME and NODE_NAME |
POST /api/nodes/{id}/compose |
Returns the same compose values again, for Replace |
POST /api/nodes/{id}/placement |
Sends the node's backups somewhere and answers per section whether the node reached its repository, with a warning for a storage location |
PUT /api/nodes/{id}/schedule |
Sets the plans, such as {"containers":"daily 03:00","files":"off"}. A section left out keeps its plan |
DELETE /api/nodes/{id} |
Releases the node. told says whether it heard it now or hears it once it is back |
GET /api/nodes/routes |
The list of the node's own routes that home passes requests to |
GET, POST, PATCH /api/nodes/{id}/api/{path} |
Passes the request to the node's route /api/{path} when that route is on the list, and returns the node's JSON answer |
PUT /api/receiver/node-address |
Sets Address for nodes of the receiving server, such as {"url":"https://backup.tower.example.org","caPem":""}. An empty url takes the nodes off it |
The three placements:
{"kind": "receiver"}
{"kind": "location", "location": "<storage location id>", "signIn": "<sign-in id made for the node>"}
{"kind": "node", "address": "https://203.0.113.7:8443"}
A request to /api/nodes/{id}/api/... carries at most 32 KiB. A route that is not on the list answers 403, a node that has not answered yet or is being released 409 with the code node-not-adopted, and a node that is away 502 with the code node-away. For example, GET /api/nodes/{id}/api/runs?limit=20 returns the node's last 20 runs, and POST /api/nodes/{id}/api/containers/nextcloud/backup backs up its container nextcloud.
Home Assistant¶
BombVault can appear in Home Assistant as a device, through MQTT discovery. Home Assistant needs its MQTT integration and a broker, for example the Mosquitto add-on. No custom component is involved.
- In BombVault, open Settings, Integrations and switch on Home Assistant in the Services card. The fields for the broker appear below it.
- Enter the broker's address and port, and its user name and password if it asks for them. Switch Use TLS on if the broker takes TLS, usually on port 8883. Its certificate has to be valid for the address you entered. If you change the address, the port or the user name, enter the password again: BombVault does not pass the stored one on to another broker or user.
- Click Save. The row shows when the connection is up.
The device is called BombVault, or BombVault with the instance name in brackets, and has these entities:
| Entity | What it shows |
|---|---|
| Status | ok, warning, overdue, failed or off, the worst of the domains that are switched on. A domain waiting for its first backup counts only once that backup was due, and only a current domain makes the status ok. It reads overdue when a domain's last backup is more than two intervals old, as on the overview |
| Running job | What runs now, or idle |
| Open anomalies | How many anomalies are open |
| Next scheduled backup | When the next scheduled backup starts |
| Domain last backup | When the domain's last successful backup ran |
| Domain last result | How its last backup ended |
| Domain repository free space | Free space where its primary repository lives, if BombVault can read it |
| Back up domain | A button that backs up the whole domain |
Every switched-on domain gets its own entities, and a domain you switch off loses them. The buttons appear once you switch Buttons start backups on. A new install has it off. They follow the same limits as starts through the API. On top of that BombVault handles one press per domain at a time and no more than six a minute, and ignores a press the broker kept as a retained message. Anyone who can publish to the broker can press them, so give the broker a password.
BombVault reads its state every 15 seconds and publishes it when something changed, as JSON under <prefix>/<node>/state. The prefix is bombvault unless you change it, and the node is a short id BombVault picks once. The discovery messages go to Home Assistant's default prefix homeassistant. Both are retained. A last will marks the device unavailable if BombVault stops without saying so. Switching the link off removes the device and its entities from Home Assistant.
Example: a card and an alert¶
Home Assistant makes the entity ids from the names, so the device BombVault gets ids such as sensor.bombvault_status. With an instance name in brackets the ids carry that too, so check them under Developer Tools, States first. A card for the dashboard:
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
An automation that tells your phone when the status turns to failed or overdue:
alias: BombVault needs you
trigger:
- platform: state
entity_id: sensor.bombvault_status
to:
- failed
- overdue
action:
- service: notify.mobile_app_my_phone
data:
message: "BombVault status: {{ trigger.to_state.state }}. Open the overview."
Prometheus¶
Expose /metrics in the Services card under Settings, Integrations serves backup status, sizes and timestamps for Prometheus, Grafana or Uptime Kuma, at /metrics on the web interface's port. It is off by default. Scrape token (optional) makes the scraper send a bearer token. The labels carry no secrets and no paths.
Dashboard widget¶
The Dashboard widget card under Settings, Integrations generates a read-only token and gives you an address for any dashboard that shows an iframe, such as Homepage, Organizr or Heimdall. The address opens a small page at /widget with just the live activity log. The token grants that log and nothing else, and Disable revokes it at once. The embedded page is in English only.
Find BombVault on the network¶
BombVault announces its web interface on the local network over mDNS, the protocol behind Bonjour and Avahi. A browser then reaches it as https://bombvault.local:3443, or http://bombvault.local:3000 with HTTP_ONLY, and service browsers list it as a web service with the subtype _bombvault. Its TXT records carry the version and the path. The switch is Find on the network in the Services card under Settings, Integrations and is on by default. If another device already uses the name, BombVault takes bombvault-2.local and so on, and the card shows the address it got. When BombVault stops or you switch the announcement off, it tells the network, so browsers drop the entry at once.
Whether the announcement reaches your network depends on how the container is connected:
- bridge, the default in the Unraid template: the announcement stays inside Docker's network and nobody on the LAN sees it. Open BombVault by the host's address as before.
- br0 or another macvlan or ipvlan network: the container has its own address on the LAN, and the announcement reaches it.
- host: the announcement goes out on the host's interfaces, next to Unraid's own. It skips Docker's and libvirt's bridges.
Only IPv4 addresses are announced.