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.
    

    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).
    

    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.
    

    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.
    

    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.
    

    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.
    

    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.
    

    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.
    

    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.
    

    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.
    

    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.
    

    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}.
    

    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.
    

    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.
    

    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).
    

    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.
    

    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.
    

    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}.
    

    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.
    

    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}.
    

    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.
    

    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).
    

    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.