API e integraciones¶
BombVault tiene una pequeña API HTTP para scripts, paneles y domótica. Lee lo mismo que muestra el panel y puede iniciar una copia. Todo lo demás, como las restauraciones, el borrado de copias y los ajustes, se queda en la interfaz web.
Tokens¶
Cada petición necesita un token de API, aunque no haya contraseña de acceso. Créalo en Ajustes, Integraciones, Tokens de API:
- Escribe un nombre que diga dónde se usa el token, por ejemplo «Home Assistant» o «Uptime Kuma».
- Activa Permitir iniciar copias si el token debe poder iniciar copias. Sin eso solo puede leer.
- Haz clic en Crear token. El token se muestra una sola vez. BombVault solo guarda una huella, así que cópialo ahora.
Envía el token en una cabecera, Authorization: Bearer <token> o X-API-Key: <token>. Un token empieza por bvapi_. Solo abre la API: una clave MCP no sirve aquí y un token no sirve para MCP.
Cada token tiene una ficha con su nombre, si puede iniciar copias, sus cuatro últimos caracteres, cuándo y desde dónde se usó por última vez y sus llamadas de hoy. En la ficha puedes renombrarlo, cambiar lo que puede hacer, sustituirlo o revocarlo. Registro muestra las copias que inició y sus últimas llamadas. Restaurar la configuración de BombVault desde una copia revoca todos los tokens, porque la copia puede contener tokens que revocaste después.
Sin contraseña de acceso, cualquiera que pueda abrir la interfaz web también puede crear un token. Si abres BombVault con un nombre que parece público y no hay contraseña, no se pueden crear tokens desde esa dirección, igual que con las claves MCP.
Rutas¶
| Ruta | Qué devuelve o hace | Token |
|---|---|---|
GET /api/v1/health |
Versión, nombre de la instancia, si hay una copia en marcha y qué puede hacer este token | lectura |
GET /api/v1/status |
Estado de protección por dominio: última copia correcta, intervalo esperado, comprobaciones, próximas ejecuciones | lectura |
GET /api/v1/activity |
Lo que está en marcha ahora, con fase y porcentaje | lectura |
GET /api/v1/items |
Cada elemento protegido con su programación, lo que detiene una copia y su última copia; ?domain= para un dominio |
lectura |
GET /api/v1/runs |
Historial de ejecuciones, las más recientes primero; filtros limit, domain, item, status, kind, since |
lectura |
GET /api/v1/anomalies |
Anomalías con un resumen de lo abierto; filtros state, severity, domain, limit |
lectura |
GET /api/v1/anomalies/{id} |
Una anomalía | lectura |
GET /api/v1/storage/{domain} |
Historial de tamaño, crecimiento semanal y espacio libre de cada repositorio de un dominio | lectura |
POST /api/v1/backups |
Copia un elemento ({"domain":"containers","item":"plex"}) o un dominio entero ({"domain":"vms"}) |
inicio |
POST /api/v1/backups/everything |
Ejecuta la Copia total | inicio |
POST /api/v1/runs/{id}/cancel |
Cancela una copia en marcha que inició este token | inicio |
Los dominios son containers, vms, files, zfs, flash y config. Las horas son segundos Unix. Las respuestas son las de las herramientas MCP del mismo nombre, así ambas van a la par.
Una copia iniciada aquí es la misma que inicia la interfaz web: un contenedor en marcha se detiene hasta que termina su copia. La petición vuelve enseguida, y /api/v1/activity y /api/v1/runs muestran cómo va.
Ejemplos¶
# ¿Cómo van las copias?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Copiar un contenedor ahora.
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
Con el certificado autofirmado de BombVault, añade --cacert bombvault-cert.pem (el archivo que da Descargar certificado en la tarjeta MCP) o -k en una red de confianza.
Errores y límites¶
Un error vuelve como {"error": {"code": "...", "message": "..."}} con el estado correspondiente:
| Estado | Códigos | Significado |
|---|---|---|
| 400 | invalid_argument, ambiguous |
Falta un argumento o es incorrecto |
| 401 | no_token, invalid_token |
Sin token, o no es uno activo |
| 403 | not_permitted, forbidden_origin |
El token solo puede leer, o no inició esa ejecución, o la petición vino de una página de otro origen |
| 404 | not_found |
No existe ese elemento, ejecución o anomalía |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Ya hay algo en marcha, el dominio está desactivado o no hay nada que hacer |
| 429 | throttled, rate_limited, cooldown, retention_guard |
Un límite retiene la petición; Retry-After indica cuándo reintentar |
Los inicios siguen los mismos límites que los inicios por MCP: 12 por hora y token, 15 minutos entre dos inicios del mismo elemento, como mucho 4 inicios de un elemento en 24 horas y la protección de retención. Los tres últimos cuentan juntos los inicios por MCP, por la API y desde Home Assistant. Un token puede hacer 120 peticiones por minuto. Cinco intentos fallidos desde una dirección la bloquean durante un minuto.
OpenAPI¶
BombVault sirve una descripción de estas rutas en /api/v1/openapi.json (OpenAPI 3.1). No necesita token. Cárgala en Swagger UI, Postman o un generador de código.
Home Assistant¶
BombVault puede aparecer en Home Assistant como un dispositivo, mediante el descubrimiento MQTT. Home Assistant necesita su integración MQTT y un broker, por ejemplo el complemento Mosquitto. No hace falta ningún componente propio.
- En BombVault, abre Ajustes, Integraciones, Home Assistant.
- Escribe la dirección y el puerto del broker, y el usuario y la contraseña si los pide. Activa Usar TLS si el broker usa TLS, normalmente en el puerto 8883; su certificado tiene que ser válido para la dirección que escribiste. Si cambias la dirección, el puerto o el nombre de usuario, vuelve a escribir la contraseña: BombVault no pasa la guardada a otro broker ni a otro usuario.
- Activa Conectar con Home Assistant y haz clic en Guardar. La tarjeta muestra cuándo está establecida la conexión.
El dispositivo se llama BombVault, o BombVault con el nombre de la instancia entre paréntesis, y tiene estas entidades:
| Entidad | Qué muestra |
|---|---|
| Status | ok, warning, failed u off, el peor de los dominios activados |
| Running job | Lo que está en marcha ahora, o idle |
| Open anomalies | Cuántas anomalías están abiertas |
| Next scheduled backup | Cuándo empieza la próxima copia programada |
| Dominio last backup | Cuándo fue la última copia correcta del dominio |
| Dominio last result | Cómo terminó su última copia |
| Dominio repository free space | El espacio libre donde está su repositorio principal, si BombVault puede leerlo |
| Back up dominio | Un botón que copia el dominio entero |
Los nombres de las entidades están en inglés, porque Home Assistant los toma tal como los envía BombVault. Cada dominio activado tiene sus propias entidades, y uno que desactives las pierde. Los botones aparecen cuando activas Los botones inician copias, que viene desactivado en una instalación nueva. Siguen los mismos límites que los inicios por la API. Además, BombVault atiende una sola pulsación por dominio a la vez y como mucho seis por minuto, e ignora una pulsación que el broker guardó como mensaje retenido. Cualquiera que pueda publicar en el broker puede pulsarlos, así que ponle una contraseña al broker.
BombVault lee su estado cada 15 segundos y lo publica cuando algo cambia, como JSON en <prefijo>/<nodo>/state. El prefijo es bombvault mientras no lo cambies, y el nodo es un identificador corto que BombVault elige una vez. Los mensajes de descubrimiento van al prefijo predeterminado de Home Assistant, homeassistant. Ambos se conservan (retained). Un último mensaje (last will) marca el dispositivo como no disponible si BombVault se detiene sin avisar. Desactivar el enlace quita el dispositivo y sus entidades de Home Assistant.
Encontrar BombVault en la red¶
BombVault anuncia su interfaz web en la red local por mDNS, el protocolo detrás de Bonjour y Avahi. Así un navegador llega a él como https://bombvault.local:3443, o http://bombvault.local:3000 con HTTP_ONLY, y los exploradores de servicios lo muestran como servicio web con el subtipo _bombvault. Sus registros TXT llevan la versión y la ruta. El interruptor está en Ajustes, Integraciones, Encontrar en la red y viene activado. Si otro dispositivo ya usa el nombre, BombVault toma bombvault-2.local y así sucesivamente, y la tarjeta muestra la dirección que obtuvo. Cuando BombVault se detiene o desactivas el anuncio, lo comunica a la red y los navegadores quitan la entrada enseguida.
Que el anuncio llegue a tu red depende de cómo esté conectado el contenedor:
- bridge, el valor por defecto de la plantilla de Unraid: el anuncio se queda dentro de la red de Docker y nadie en la red local lo ve. Abre BombVault por la dirección del host como hasta ahora.
- br0 u otra red macvlan o ipvlan: el contenedor tiene su propia dirección en la red local y el anuncio llega a ella.
- host: el anuncio sale por las interfaces del host, junto al de Unraid. Los puentes de Docker y libvirt quedan fuera.
Solo se anuncian direcciones IPv4.