VPS

Create a backup

POST /v1/vps/{id}/backups · scope vps:write · reversible · asynchronous · idempotent

Queues a vzdump. With mode: snapshot (the default) the machine keeps running. The operation reflects that the task was queued, not that the archive is ready: the final size appears in GET /v1/vps/{id}/backups once the hypervisor finishes.

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

Delete a backup

DELETE /v1/vps/{id}/backups/{backup_id} · scope vps:write · destructive — cannot be undone · idempotent

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

List the VPS backups

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

Restore a backup

POST /v1/vps/{id}/backups/{backup_id}/restore · scope vps:write · destructive — cannot be undone · asynchronous · idempotent

Destructive. Powers off the machine and overwrites the entire disk: everything written after that backup is lost. The backend verifies the backup belongs to this VPS before touching anything.

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

Get the machine configuration

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

Open a console

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

Issues a single-use ticket. It grants full access to the operating system, bypassing the network and SSH, which is why it lives in its own scope (vps:console) instead of falling under vps:write. Do not log it: the SPICE file carries the password inside.

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

Get a VPS with its live state

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

Queries the hypervisor. If it does not respond, the state fields come back null instead of failing: a hypervisor hiccup should not stop you from reading the rest of the resource or its 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

List the IPs assigned to the 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

List VPS instances

GET /v1/vps · scope vps:read

Served from the database, without querying the hypervisor: state, cpu, memory, and disk come back null. Fetching them would cost one backend call per page item. For the live state of one instance, use 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

Get CPU, memory, disk, and network usage series

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

The hypervisor’s RRD series. Resolution is set by timeframe and is not configurable: hour yields minutes, year yields weeks. cpu_percent is a percentage of the allocated total.

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

Start, stop, or reboot

POST /v1/vps/{id}/power · scope vps:power · reversible · asynchronous · idempotent

Returns 202 as soon as the order is issued, not when the machine reaches the requested state. The operation resolves against the VM’s actual state, so it survives the backend taking longer than the HTTP timeout — a reboot is stop, wait, and start, which does not fit in one request. Wait on it with 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

Reinstall the operating system

POST /v1/vps/{id}/reinstall · scope vps:write · destructive — cannot be undone · asynchronous · idempotent

Destructive and irreversible: it wipes the entire disk. Queues a job that runs the same state machine as a fresh provision (provision → wait for boot → health check), so the operation reports real progress and can take several minutes. The IP is preserved.

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

List the operating systems available for reinstall

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

Depends on the machine type and the node it lives on, so it is requested per VPS rather than globally.

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

Rename a VPS

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

Changes the operating system hostname. On LXC it takes effect immediately; on KVM it renames the VM and the operating system picks it up on the next reboot.

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