| pve_cluster_statusA | Cluster and node health, including quorum. Applies to: the whole cluster (also works on a single, unclustered node,
which reports one entry of type ``node``).
Returns a JSON list of entries. Cluster entries carry ``quorate`` and the
node count; node entries carry ``online``, ``ip`` and ``nodeid``.
Source: GET /cluster/status.
|
| pve_list_nodesA | List all nodes with CPU, memory, disk usage and online status. Applies to: every node in the cluster.
Returns a JSON list. ``cpu`` is a 0..1 load fraction; ``mem``/``maxmem``
and ``disk``/``maxdisk`` are bytes (with ``*_human`` companions);
``uptime`` is seconds (with ``uptime_human``). Source: GET /nodes.
|
| pve_node_statusA | Detailed status of a single node (load, kernel, PVE version, memory). Applies to: one node, identified by its name (e.g. ``pve1``).
Returns a JSON object with ``uptime`` (+human), ``loadavg``, ``cpu``
(0..1), ``cpuinfo`` (model, cpus), and ``memory``/``swap``/``rootfs``
each as ``{total, used, free/avail}`` bytes with ``*_human`` companions.
Source: GET /nodes/{node}/status.
|
| pve_list_vmsA | List QEMU VMs and LXC containers across the cluster. Applies to: both VMs and CTs. Optional filters: ``node`` (name),
``type`` (``qemu`` or ``lxc``), ``status`` (``running`` or ``stopped``).
Returns a JSON list with ``vmid``, ``name``, ``status``, ``node``,
``type``, cpu, and byte-valued ``mem``/``maxmem``/``disk``/``maxdisk``
(with ``*_human``) plus ``uptime`` (+human).
Source: GET /cluster/resources?type=vm.
|
| pve_vm_statusA | Live runtime status of one VM or container. Applies to: a single VM or CT, located by ``vmid`` (``node`` optional and
auto-resolved). Returns a JSON object with ``status``, live cpu/memory,
network and disk I/O counters (bytes, with ``*_human``), ``uptime``
(+human) and, for QEMU, whether the guest ``agent`` is enabled.
Source: GET /nodes/{node}/{qemu|lxc}/{vmid}/status/current.
|
| pve_vm_configA | Full configuration of one VM or container. Applies to: a single VM or CT, located by ``vmid`` (``node`` optional and
auto-resolved). Returns the complete config object (cores, memory, disk
entries like ``scsi0``, network entries like ``net0``, ``onboot`` ...),
with ``vmid``/``node``/``type`` context added.
Source: GET /nodes/{node}/{qemu|lxc}/{vmid}/config.
|
| pve_list_storageA | List storages with usage figures. Applies to: all storages. If ``node`` is given, reports that node's view
(GET /nodes/{node}/storage); otherwise reports a cluster-wide view
(GET /cluster/resources?type=storage).
Returns a JSON list; ``total``/``used``/``avail`` are bytes with
``*_human`` companions.
|
| pve_storage_contentA | List the contents of a storage on a node. Applies to: one storage on one node. ``content`` optionally filters by
kind: ``iso``, ``backup``, ``vztmpl`` (CT templates) or ``images`` (VM
disks).
Returns a JSON list of volumes with ``volid``, ``size`` (bytes, +human),
``format``, ``vmid`` and ``ctime`` (+human).
Source: GET /nodes/{node}/storage/{storage}/content.
|
| pve_list_backupsA | List backup archives across storages, optionally filtered. Applies to: VM and CT backups (vzdump archives). ``vmid`` filters to one
guest; ``storage`` filters to one storage. Convenience wrapper that scans
every backup-capable storage (via /cluster/resources?type=storage) and
aggregates their ``content=backup`` listings.
Returns a JSON list with ``volid``, ``vmid``, ``storage``, ``node``,
``size`` (bytes, +human) and ``ctime`` (+human), newest first.
|
| pve_list_snapshotsA | List snapshots of one VM or container. Applies to: a single VM or CT, located by ``vmid`` (``node`` optional and
auto-resolved). PVE includes a synthetic ``current`` entry representing
the live state; ``parent`` links form the snapshot tree.
Returns a JSON list with ``name``, ``description``, ``parent``,
``snaptime`` (+human) and ``vmstate`` (1 = includes RAM).
Source: GET /nodes/{node}/{qemu|lxc}/{vmid}/snapshot.
|
| pve_list_tasksA | List recent tasks, newest first. Applies to: task history. If ``node`` is given, lists that node's tasks;
otherwise aggregates across all nodes. ``limit`` caps the number of
entries returned; ``errors_only`` keeps only failed tasks.
Returns a JSON list with ``upid``, ``type``, ``id`` (often the vmid),
``user``, ``status`` (final status / "OK"), ``starttime``/``endtime``
(+human). Source: GET /nodes/{node}/tasks.
|
| pve_task_statusA | Status of a single task; attaches the log tail when it failed. Applies to: any PVE task, identified by its ``upid``. ``node`` is optional
and, when omitted, is parsed from the UPID.
Returns a JSON object with ``status`` (``running``/``stopped``),
``exitstatus`` (``OK`` or the error), ``type``, ``id``, ``user`` and
``starttime`` (+human). On failure, a ``log_tail`` array of the last log
lines is included. Source: GET .../tasks/{upid}/status (+ .../log).
|
| pve_vm_powerA | Change the power state of a VM or container. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``action`` is one of ``start``,
``shutdown`` (clean, via guest), ``stop``, ``reboot``, ``suspend``,
``resume``. NOTE: ``stop`` is a hard power-off (like pulling the plug) —
prefer ``shutdown`` unless the guest is unresponsive. ``suspend`` /
``resume`` are QEMU-only; containers must use shutdown/stop/start.
``timeout`` (seconds) applies to shutdown/reboot (and QEMU stop) as the
max wait for the guest.
Side effects: changes guest power state. Waits up to PVE_MCP_TASK_WAIT
seconds for the PVE task; returns JSON with ``vmid``/``node``/``type``/
``action`` and ``task`` (``exitstatus`` "OK", failure + ``log_tail``, or
``status`` "running" with the ``upid`` to follow up via pve_task_status).
Source: POST /nodes/{node}/{qemu|lxc}/{vmid}/status/{action}.
|
| pve_vm_migrateA | Migrate a VM or container to another node. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (source
``node`` optional and auto-resolved). For a running QEMU VM pass
``online=true`` for live migration. LXC containers cannot live-migrate:
for them ``online=true`` is mapped to PVE restart migration (the CT is
stopped, migrated, and started on ``target_node``).
Side effects: moves the guest (brief downtime for CT restart migration).
Waits up to PVE_MCP_TASK_WAIT seconds for the PVE task; returns JSON with
``vmid``/``node`` (source)/``target_node``/``type`` and ``task``
(``exitstatus`` "OK", failure + ``log_tail``, or ``status`` "running"
with the ``upid`` to follow up via pve_task_status — migrations often
outlast the wait window).
Source: POST /nodes/{node}/{qemu|lxc}/{vmid}/migrate.
|
| pve_vm_set_configA | Change configuration options of a VM or container. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``config`` is a dict of PVE config keys to
values, e.g. ``{"cores": 4, "memory": 8192, "name": "web02",
"onboot": 1}`` — the same keys pve_vm_config returns.
Side effects: updates the guest config. NOTE: most changes (cores,
memory without hotplug, disks, NICs) only take effect after the guest
is restarted; PVE applies hotpluggable changes immediately and stages
the rest as "pending". Waits up to PVE_MCP_TASK_WAIT seconds when PVE
runs the change as a task; returns JSON with ``vmid``/``node``/``type``/
``applied`` (the submitted config) and ``task``.
Source: POST /nodes/{node}/qemu/{vmid}/config (async) or
PUT /nodes/{node}/lxc/{vmid}/config (LXC has no async variant).
|
| pve_vm_resize_diskA | Grow a disk of a VM or container. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``disk`` is the config key (e.g. ``scsi0``,
``virtio1``, or ``rootfs``/``mp0`` for containers). ``size`` is either
relative (``+10G`` — add 10 GiB) or an absolute new size (``64G``);
units K/M/G/T. GROW ONLY: PVE does not support shrinking disks, and an
absolute size smaller than the current one is rejected by PVE.
Side effects: enlarges the disk volume (the filesystem inside the guest
usually must be grown separately). Waits up to PVE_MCP_TASK_WAIT
seconds; returns JSON with ``vmid``/``node``/``type``/``disk``/``size``
and ``task``. Source: PUT /nodes/{node}/{qemu|lxc}/{vmid}/resize.
|
| pve_vm_cloneA | Clone a VM or container to a new vmid. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``newid`` must be unused. ``full=true``
makes an independent full copy (required when the source is not a
template); linked clones (``full=false``) need a template source.
``storage`` sets the target storage for a full clone; ``target_node``
places the clone on another node (shared storage required).
Side effects: creates a new guest (stopped). Clones often outlast the
PVE_MCP_TASK_WAIT window — then ``task.status`` is "running" and the
``upid`` can be followed with pve_task_status. Returns JSON with
``vmid`` (source), ``newid``, ``node``/``type`` and ``task``.
Source: POST /nodes/{node}/{qemu|lxc}/{vmid}/clone.
|
| pve_vm_deleteA | Delete a VM or container permanently. DESTRUCTIVE. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). Requires ``confirm=true``: the guest and
ALL of its disks are destroyed irreversibly (backups on backup storage
are kept). ``purge=true`` additionally removes the vmid from backup
jobs, replication and HA configuration.
Side effects: permanently destroys the guest. The guest must be stopped
first (PVE rejects deleting a running guest). Waits up to
PVE_MCP_TASK_WAIT seconds; returns JSON with the deleted ``vmid``/
``node``/``type`` and ``task``.
Source: DELETE /nodes/{node}/{qemu|lxc}/{vmid}.
|
| pve_snapshot_createA | Create a snapshot of a VM or container. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``name`` is the snapshot identifier.
``vmstate=true`` also saves the RAM state (live snapshot) — QEMU only;
LXC containers reject it with an error.
Side effects: creates a snapshot (disk space usage grows over time).
Waits up to PVE_MCP_TASK_WAIT seconds for the PVE task; returns JSON with
``vmid``/``node``/``type``/``snapshot`` and ``task`` (``exitstatus``
"OK", failure + ``log_tail``, or ``status`` "running" with the ``upid``).
Source: POST /nodes/{node}/{qemu|lxc}/{vmid}/snapshot.
|
| pve_snapshot_rollbackA | Roll a VM or container back to a snapshot. DESTRUCTIVE. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). Requires ``confirm=true``: rolling back
DISCARDS ALL CHANGES (disk data and config) made after snapshot ``name``
was taken, irreversibly.
Side effects: guest disk/config revert to the snapshot; a running guest
is stopped unless the snapshot includes RAM state. Waits up to
PVE_MCP_TASK_WAIT seconds; returns JSON with ``vmid``/``node``/``type``/
``snapshot`` and ``task``.
Source: POST /nodes/{node}/{qemu|lxc}/{vmid}/snapshot/{name}/rollback.
|
| pve_snapshot_deleteA | Delete a snapshot of a VM or container. DESTRUCTIVE. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). Requires ``confirm=true``: the snapshot
``name`` is removed permanently and can no longer be rolled back to.
Side effects: frees the snapshot's disk space; the guest keeps running
unaffected. Waits up to PVE_MCP_TASK_WAIT seconds; returns JSON with
``vmid``/``node``/``type``/``snapshot`` and ``task``.
Source: DELETE /nodes/{node}/{qemu|lxc}/{vmid}/snapshot/{name}.
|
| pve_backup_createA | Create a vzdump backup of a VM or container. Applies to: QEMU VMs and LXC containers, located by ``vmid`` (``node``
optional and auto-resolved). ``storage`` is the target backup storage.
``mode``: ``snapshot`` (default, no downtime), ``suspend`` (brief
pause), or ``stop`` (guest is shut down for the backup). ``compress``
defaults to ``zstd`` (valid: 0, 1, gzip, lzo, zstd). ``notes`` attaches
a comment to the archive; ``{{...}}`` template variables (e.g.
``{{guestname}}``) are expanded by PVE.
Side effects: creates a backup archive on ``storage``; ``stop`` mode
shuts the guest down during the backup. Backups often outlast the
PVE_MCP_TASK_WAIT window — then ``task.status`` is "running" and the
``upid`` can be followed with pve_task_status. Returns JSON with
``vmid``/``node``/``type``/``storage``/``mode`` and ``task``.
Source: POST /nodes/{node}/vzdump.
|
| pve_backup_restoreA | Restore a backup archive to a VM/CT id. DESTRUCTIVE when overwriting. Applies to: vzdump/PBS backup archives (``archive`` is the volid, e.g.
``local:backup/vzdump-qemu-100-....vma.zst``); the guest type
(QEMU vs LXC) is inferred from the archive name. ``node`` is required —
the target may not exist yet, so it cannot be auto-resolved. ``storage``
optionally overrides where restored disks are placed.
Restoring to a NEW (unused) ``vmid`` needs no confirmation. Overwriting
an EXISTING ``vmid`` destroys that guest's current disks and config:
it requires ``force=true`` AND ``confirm=true``.
Waits up to PVE_MCP_TASK_WAIT seconds (restores often run longer — then
``task.status`` is "running"; follow the ``upid`` with pve_task_status).
Returns JSON with ``vmid``/``node``/``type``/``archive`` and ``task``.
Source: POST /nodes/{node}/qemu (archive=...) or
POST /nodes/{node}/lxc (ostemplate=..., restore=1).
|
