VPS

Crear un backup

POST /v1/vps/{id}/backups · scope vps:write · reversible · asincrona · idempotente

Encola un vzdump. Con mode: snapshot (default) la máquina sigue andando. La operación refleja que la tarea quedó encolada, no que el archivo esté listo: el tamaño final aparece en GET /v1/vps/{id}/backups cuando el hipervisor termina.

curl https://api.truo.cloud/v1/vps/svc_10432/backups \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps backup create svc_10432

await truo.vps.backups.create("svc_10432");

truo_vps({
  "action": "backup_create",
  "id": "svc_10432"
})

operationId: vps.backups.create

Borrar un backup

DELETE /v1/vps/{id}/backups/{backup_id} · scope vps:write · destructiva — no tiene vuelta atras · idempotente

curl https://api.truo.cloud/v1/vps/svc_10432/backups/local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps backup delete svc_10432 local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst

await truo.vps.backups.delete("svc_10432", "local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst");

truo_vps({
  "action": "backup_delete",
  "id": "svc_10432",
  "backupId": "local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst"
})

operationId: vps.backups.delete

Backups del VPS

GET /v1/vps/{id}/backups · scope vps:read

curl https://api.truo.cloud/v1/vps/svc_10432/backups \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps backup list svc_10432

await truo.vps.backups.list("svc_10432");

truo_vps({
  "action": "backup_list",
  "id": "svc_10432"
})

operationId: vps.backups.list

Restaurar un backup

POST /v1/vps/{id}/backups/{backup_id}/restore · scope vps:write · destructiva — no tiene vuelta atras · asincrona · idempotente

Destructivo. Apaga la máquina y sobreescribe el disco entero: todo lo escrito después de ese backup se pierde. El backend verifica que el backup pertenezca a este VPS antes de tocar nada.

curl https://api.truo.cloud/v1/vps/svc_10432/backups/local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst/restore \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps backup restore svc_10432 local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst

await truo.vps.backups.restore("svc_10432", "local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst");

truo_vps({
  "action": "backup_restore",
  "id": "svc_10432",
  "backupId": "local:backup/vzdump-qemu-101-2026_07_27-03_00_01.vma.zst"
})

operationId: vps.backups.restore

Configuración de la máquina

GET /v1/vps/{id}/config · scope vps:read

curl https://api.truo.cloud/v1/vps/svc_10432/config \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps config svc_10432

await truo.vps.config.get("svc_10432");

truo_vps({
  "action": "config",
  "id": "svc_10432"
})

operationId: vps.config.get

Abrir una consola

POST /v1/vps/{id}/console · scope vps:console · reversible

Emite un ticket de un solo uso. Da acceso total al sistema operativo, sin pasar por la red ni por SSH, y por eso vive en su propio scope (vps:console) en vez de caer bajo vps:write. No lo loguees: el file de SPICE lleva la contraseña adentro.

curl https://api.truo.cloud/v1/vps/svc_10432/console \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps console svc_10432

await truo.vps.console.create("svc_10432");

truo_vps({
  "action": "console",
  "id": "svc_10432"
})

operationId: vps.console.create

Obtener un VPS con su estado real

GET /v1/vps/{id} · scope vps:read

Consulta el hipervisor. Si no responde, los campos de estado vuelven en null en vez de fallar: que el hipervisor tenga un hipo no debería impedirte leer el resto del recurso ni sus capabilities.

curl https://api.truo.cloud/v1/vps/svc_10432 \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps get svc_10432

await truo.vps.get("svc_10432");

truo_vps({
  "action": "get",
  "id": "svc_10432"
})

operationId: vps.get

IPs asignadas al VPS

GET /v1/vps/{id}/ips · scope vps:read

curl https://api.truo.cloud/v1/vps/svc_10432/ips \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps ip list svc_10432

await truo.vps.ips.list("svc_10432");

truo_vps({
  "action": "ips",
  "id": "svc_10432"
})

operationId: vps.ips.list

Listar los VPS de la cuenta

GET /v1/vps · scope vps:read

Sale de la base, sin consultar el hipervisor: state, cpu, memory y disk vienen en null. Traerlos costaría una llamada al backend por cada elemento de la página. Para el estado vivo de uno, GET /v1/vps/{id}.

curl https://api.truo.cloud/v1/vps \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps list

await truo.vps.list();

truo_vps({
  "action": "list"
})

operationId: vps.list

Serie de uso de CPU, memoria, disco y red

GET /v1/vps/{id}/metrics · scope vps:read

Serie RRD del hipervisor. La resolución la fija el timeframe y no es configurable: hour da minutos, year da semanas. cpu_percent es porcentaje del total asignado.

curl https://api.truo.cloud/v1/vps/svc_10432/metrics \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps stats svc_10432

await truo.vps.metrics.list("svc_10432");

truo_vps({
  "action": "metrics",
  "id": "svc_10432"
})

operationId: vps.metrics.list

Encender, apagar o reiniciar

POST /v1/vps/{id}/power · scope vps:power · reversible · asincrona · idempotente

Devuelve 202 en cuanto la orden sale, no cuando la máquina llegó al estado pedido. La operación se resuelve contra el estado real de la VM, así que sobrevive a que el backend tarde más que el timeout HTTP — un reboot es apagar, esperar y encender, y eso no entra en una request. Esperá con GET /v1/operations/{id}.

curl https://api.truo.cloud/v1/vps/svc_10432/power \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"start"}'

truo vps power svc_10432 <action>

await truo.vps.power("svc_10432", {"action":"start"});

truo_vps({
  "action": "power",
  "id": "svc_10432"
})

operationId: vps.power

Reinstalar el sistema operativo

POST /v1/vps/{id}/reinstall · scope vps:write · destructiva — no tiene vuelta atras · asincrona · idempotente

Destructivo e irreversible: borra el disco entero. Encola un job que corre la misma máquina de estados que un alta nueva (aprovisionar → esperar el boot → chequeo de salud), así que la operación reporta progreso real y puede tardar varios minutos. La IP se conserva.

curl https://api.truo.cloud/v1/vps/svc_10432/reinstall \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template":"<template>","root_password":"<root_password>"}'

truo vps reinstall svc_10432

await truo.vps.reinstall("svc_10432", {"template":"<template>","root_password":"<root_password>"});

truo_vps({
  "action": "reinstall",
  "id": "svc_10432"
})

operationId: vps.reinstall

Sistemas operativos disponibles para reinstalar

GET /v1/vps/{id}/templates · scope vps:read

Depende del tipo de máquina y del nodo donde vive, así que se pide por VPS y no global.

curl https://api.truo.cloud/v1/vps/svc_10432/templates \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo vps template list svc_10432

await truo.vps.templates.list("svc_10432");

truo_vps({
  "action": "templates",
  "id": "svc_10432"
})

operationId: vps.templates.list

Renombrar un VPS

PATCH /v1/vps/{id} · scope vps:write · reversible · idempotente

Cambia el hostname del sistema operativo. En LXC toma efecto al vuelo; en KVM cambia el nombre de la VM y el sistema operativo lo adopta al reiniciar.

curl https://api.truo.cloud/v1/vps/svc_10432 \
  -X PATCH \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"<hostname>"}'

truo vps rename svc_10432

await truo.vps.update("svc_10432", {"hostname":"<hostname>"});

truo_vps({
  "action": "rename",
  "id": "svc_10432"
})

operationId: vps.update