@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pve/enrichment/post_nodes_node_stopall.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_stopall",
+  "usageNotes": "Use this to gracefully (or forcefully) shut down all VMs and containers on a specific node — typically before a planned node maintenance window, hardware reboot, or controlled power-off. The `vms` parameter lets you limit the scope to specific VMIDs instead of everything on the node. By default, each guest gets 180 seconds to shut down cleanly before a hard-stop is forced; lower `timeout` or set `force-stop` to false if you want a pure graceful-only approach. Returns a task UPID you can poll to track overall completion.",
+  "examples": [
+    {
+      "summary": "Stop all guests on node pve1 with a 5-minute timeout and hard-stop fallback",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "force-stop": true,
+        "timeout": 300,
+        "max-workers": 4
+      }
+    }
+  ],
+  "destructiveReason": "Sends a shutdown (or hard-stop) signal to every running VM and container on the target node, causing immediate service disruption and potential data loss for guests that do not gracefully handle ACPI shutdown.",
+  "tips": [
+    "Use the `vms` parameter (comma-separated VMIDs) to stop a subset of guests without touching the rest of the node.",
+    "The returned string is a UPID — poll it via GET /nodes/{node}/tasks/{upid}/status to know when all stop tasks have completed.",
+    "max-workers caps parallel stop tasks; keeping it low (2–4) reduces I/O contention during flushing and is safer for storage-heavy guests.",
+    "force-stop defaults to true (1); explicitly set it to false if you need a strictly graceful shutdown with no hard-kill fallback."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_startall",
+    "post_nodes_node_migrateall",
+    "get_nodes_node_tasks"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_storage_storage_content.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_storage_storage_content",
+  "usageNotes": "Use this endpoint to allocate a new disk image on a storage pool and assign it to a specific VM owner. The caller requires `Datastore.AllocateSpace` on the target storage. The operation returns the new volume identifier (e.g. `local-lvm:vm-100-disk-0`) synchronously — there is no async UPID; the disk is ready to attach once the response is received.",
+  "examples": [
+    {
+      "summary": "Allocate a 32 GB qcow2 disk on local storage for VM 101",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local"
+      },
+      "params": {
+        "filename": "vm-101-disk-1",
+        "vmid": 101,
+        "size": "32G",
+        "format": "qcow2"
+      }
+    }
+  ],
+  "tips": [
+    "The `format` parameter must be compatible with the storage type: `raw`/`qcow2`/`vmdk` for file-based stores (dir, NFS), `raw` only for block/LVM stores, `subvol` for ZFS/btrfs container volumes.",
+    "The returned volume ID (e.g. `local-lvm:vm-100-disk-0`) is what you pass to VM config endpoints to attach the disk.",
+    "Allocating a disk does not attach it to the VM — follow up with a PUT to the VM's config endpoint (e.g. `put_nodes_node_qemu_vmid_config`) and add the volume ID to the desired SCSI/VirtIO/IDE slot.",
+    "Use suffix `G` or `M` for human-readable sizes; bare numbers are interpreted as kilobytes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "put_nodes_node_qemu_vmid_config",
+    "delete_nodes_node_storage_storage_content_volume",
+    "post_nodes_node_qemu_vmid_move_disk"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_storage_storage_content_volume.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_storage_storage_content_volume",
+  "usageNotes": "Copies a storage volume to a new target volume on the same or a different node; the source node must be online and both storage backends must be accessible. This endpoint is explicitly marked experimental by Proxmox and is not recommended for production use. The return value is a string (likely a task UPID or target volume ID) — check task status via the task API if a UPID is returned.",
+  "examples": [
+    {
+      "summary": "Copy a VM disk image to a different storage on a remote node",
+      "path_params": {
+        "node": "pve-htz-01",
+        "storage": "local-lvm",
+        "volume": "vm-100-disk-0"
+      },
+      "params": {
+        "target": "vm-100-disk-0-copy",
+        "target_node": "pve-htz-02"
+      }
+    }
+  ],
+  "tips": [
+    "This API is flagged experimental in Proxmox source; prefer snapshot-and-clone workflows (clone VM disk via POST /nodes/{node}/qemu/{vmid}/clone) for reliable volume duplication in production.",
+    "Omitting target_node defaults the copy to the same node as the source; specify it explicitly when copying cross-node.",
+    "The storage path param is marked required:false in the spec but is required in practice to resolve the volume — always supply it.",
+    "If the return value looks like 'UPID:...', poll GET /nodes/{node}/tasks/{upid}/status to confirm completion before using the target volume."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content_volume",
+    "delete_nodes_node_storage_storage_content_volume",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_storage_storage_download_url.json

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_nodes_node_storage_storage_download_url",
+  "usageNotes": "Use this to pull ISO images, container templates, or importable VM images from a public URL directly onto a Proxmox node's storage — no local upload needed. The operation is asynchronous: it returns a task UPID that you must poll (via get_nodes_node_tasks_upid_status) to confirm completion. The target node must be online and have outbound HTTP/HTTPS access to the URL; the storage must support the requested content type (e.g., ISO requires a storage configured for 'iso' content).",
+  "examples": [
+    {
+      "summary": "Download a Debian 12 ISO to local storage on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local"
+      },
+      "params": {
+        "content": "iso",
+        "filename": "debian-12.11.0-amd64-netinst.iso",
+        "url": "https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-12.11.0-amd64-netinst.iso",
+        "checksum": "3ade9e3459ce0fdea31f3cbfb7574f3eca9c0e5f89c5748c3e3b70e43e8b0e14",
+        "checksum-algorithm": "sha256",
+        "verify-certificates": true
+      }
+    }
+  ],
+  "tips": [
+    "The returned string is a UPID (e.g., UPID:pve01:...). Track it with the task-status endpoint to detect download failures or checksum mismatches.",
+    "Filename will be normalized by Proxmox (spaces replaced, certain characters stripped) — use the task log or storage browse to confirm the final name.",
+    "Set verify-certificates to false only for internal/self-signed URLs; production public downloads should always verify.",
+    "The 'import' content type is for OVA/VMDK images intended for VM import, not ISOs or LXC templates — choose content type to match what the storage expects.",
+    "Downloading large images over a slow or metered uplink blocks storage I/O on that node for the duration; prefer off-peak scheduling for large files."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "get_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_storage_storage_oci_registry_pull.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_storage_storage_oci_registry_pull",
+  "usageNotes": "Use this to pull a container image from a public or authenticated OCI registry into a Proxmox storage pool (e.g. for use as an LXC template or CT image). The storage must be of a type that supports OCI images and the target node must be online and able to reach the registry. The `reference` must include a tag (e.g. `docker.io/library/ubuntu:22.04`); digest-only references are not permitted by the format pattern. Returns a UPID string — poll the tasks API to track completion.",
+  "examples": [
+    {
+      "summary": "Pull the Ubuntu 22.04 OCI image from Docker Hub into local storage on pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local"
+      },
+      "params": {
+        "reference": "docker.io/library/ubuntu:22.04",
+        "filename": "ubuntu-22.04-oci.tar"
+      }
+    }
+  ],
+  "tips": [
+    "The `filename` value is normalized by Proxmox — do not rely on the exact string you provide being preserved verbatim.",
+    "Both `Datastore.AllocateTemplate` on the storage path and `Sys.AccessNetwork` on the node are required; missing either privilege causes a permission denied error.",
+    "The returned string is a UPID (Proxmox task ID). Use `get_nodes_node_tasks_upid_status` to poll task status and confirm the pull succeeded before referencing the image.",
+    "OCI registry pull support was introduced in PVE 8.x — verify your cluster version before relying on this endpoint.",
+    "For private registries, ensure the registry URL and credentials are configured in the Proxmox storage or node registry config before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "get_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_storage_storage_upload.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_storage_storage_upload",
+  "usageNotes": "Use this endpoint to upload ISO images, LXC container templates, or OVA/VM import images directly to a storage pool on a specific node. The caller must hold the Datastore.AllocateTemplate privilege on the target storage path. The response returns a task UPID string — poll the task API to confirm completion before referencing the uploaded file.",
+  "examples": [
+    {
+      "summary": "Upload an Ubuntu 24.04 ISO to local storage on pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local"
+      },
+      "params": {
+        "content": "iso",
+        "filename": "ubuntu-24.04-live-server-amd64.iso",
+        "checksum-algorithm": "sha256",
+        "checksum": "8762f7e74e4d64d72fceb5f70682e6b069932deedb4949c6975d0f0fe0a91be3"
+      }
+    }
+  ],
+  "tips": [
+    "The filename field is normalized by Proxmox (spaces replaced, etc.) — verify the final stored name via the storage content list after the task completes.",
+    "The 'import' content type is for OVA/VM disk images; use 'iso' for installation media and 'vztmpl' for LXC container templates.",
+    "This endpoint expects a multipart file upload in practice (via the web UI or curl with --form); the JSON body sample only shows metadata fields.",
+    "tmpfilename is restricted to localhost trusted-port use only — do not set it from remote API clients.",
+    "Providing a checksum and checksum-algorithm is strongly recommended for large ISOs to detect transfer corruption."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume",
+    "get_nodes_node_tasks"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_subscription.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_subscription",
+  "usageNotes": "Triggers an on-demand refresh of the Proxmox VE subscription status for the specified node by contacting the Proxmox licensing server; the result is cached locally so normal reads use GET instead. Use the `force` flag when a subscription key was just activated or renewed and the cached status is stale. Requires `Sys.Modify` on `/nodes/{node}` and the node must be reachable by the PVE host to contact the upstream server.",
+  "examples": [
+    {
+      "summary": "Force-refresh subscription status on node pve1 after renewing a license key",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "force": true
+      }
+    }
+  ],
+  "tips": [
+    "Without force=true, the call is a no-op when the local cache is still within its validity window — use force=true after any key change.",
+    "Returns null on success; treat an HTTP 2xx with null body as confirmation the refresh was queued.",
+    "If the node cannot reach shop.proxmox.com (e.g., air-gapped), the call will fail or leave the node in an 'offline' subscription state — whitelist the licensing endpoint in firewall rules first.",
+    "Use GET /nodes/{node}/subscription afterward to confirm the updated status and expiry date."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_subscription",
+    "put_nodes_node_subscription",
+    "delete_nodes_node_subscription"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_suspendall.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_suspendall",
+  "usageNotes": "Use this to suspend (RAM-to-disk or RAM freeze) all running VMs on a node simultaneously — typical before node maintenance when a full shutdown is not desired and VMs should resume where they left off. Requires 'VM.PowerMgmt' on '/' or per-VM, plus 'VM.Config.Disk' and 'Datastore.AllocateSpace' for the state storage; ensure sufficient free space on the configured suspend storage before calling. Returns a task UPID string — poll the task API to confirm completion before proceeding with maintenance.",
+  "examples": [
+    {
+      "summary": "Suspend all VMs on node 'pve01' using up to 4 parallel workers",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "max-workers": 4
+      }
+    }
+  ],
+  "tips": [
+    "Omitting 'vms' suspends every running VM on the node; pass a comma-separated VMID list to target specific guests only.",
+    "Suspend writes VM RAM state to disk — ensure the configured state-storage has free space equal to or greater than the combined RAM of all targeted VMs.",
+    "The returned UPID can be tracked via GET /nodes/{node}/tasks/{upid}/status to detect failures on individual VMs before starting maintenance.",
+    "KVM hardware-assisted suspend ('freeze') is faster than full hibernate but may not be supported by all guest OSes; verify guest tools are installed."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_startall",
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_termproxy.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_termproxy",
+  "usageNotes": "Creates a terminal proxy session on the target node, returning a port, VNC ticket, UPID, and authenticated user — all required to open a WebSocket-based shell in the Proxmox web UI or a compatible VNC/xterm client. The calling user must hold Sys.Console on /nodes/{node}; using cmd values other than 'login' (e.g. 'upgrade', 'ceph_install') additionally requires the token or session to be authenticated as root@pam. The node must be online and reachable at the time of the call.",
+  "examples": [
+    {
+      "summary": "Open an interactive login shell on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "cmd": "login"
+      }
+    }
+  ],
+  "tips": [
+    "The returned 'port' is ephemeral — connect to it promptly before the termproxy worker times out.",
+    "Use the 'ticket' value as the VNC password when establishing the WebSocket connection via /nodes/{node}/vncwebsocket.",
+    "The 'upid' can be polled with the tasks API to confirm the worker is still alive.",
+    "cmd='upgrade' runs an interactive apt dist-upgrade session and requires root@pam authentication, not just Sys.Console."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_vncwebsocket",
+    "get_nodes_node_tasks",
+    "get_nodes_node_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_vncshell.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_vncshell",
+  "usageNotes": "Creates a VNC shell proxy for direct node-level console access — use this for host OS access rather than VM/container console (which have their own vncproxy endpoints). The caller must hold Sys.Console on /nodes/{node}; the special-purpose commands 'ceph_install' and 'upgrade' additionally require root@pam authentication — API tokens cannot satisfy that requirement. Returns connection credentials (ticket, cert, port) consumed immediately by a VNC or noVNC websocket client; the session is ephemeral and the ticket expires quickly, so the client should connect without delay.",
+  "examples": [
+    {
+      "summary": "Open a standard login shell on node pve01 via websocket",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "cmd": "login",
+        "websocket": true,
+        "width": 1280,
+        "height": 800
+      }
+    }
+  ],
+  "tips": [
+    "The returned 'ticket' and 'password' fields are used as VNC credentials; pass 'ticket' as the VNC password when connecting via the standard VNC protocol path.",
+    "Set 'websocket: true' for noVNC browser clients — the Proxmox web UI always uses websocket mode.",
+    "The 'cmd-opts' field is null-byte delimited, not space delimited; construct it carefully if passing arguments to 'upgrade' or 'ceph_install'.",
+    "Width and height are cosmetic hints to the spawned terminal; the VNC client can resize after connection."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_vncwebsocket",
+    "post_nodes_node_termproxy",
+    "post_nodes_node_spiceshell"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_vzdump.json

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_nodes_node_vzdump",
+  "usageNotes": "Use this to trigger an on-demand vzdump backup of one or more guests on a specific node; it returns a UPID string (task ID) immediately — poll the task log via GET /nodes/{node}/tasks/{upid}/log to track completion. Caller must have VM.Backup on the target VMs and Datastore.AllocateSpace on the backup storage; privileged params (tmpdir, dumpdir, script, job-id) are root@pam only. Either vmid, all, or pool is required to select guests — omitting all three starts the job but backs up nothing.",
+  "examples": [
+    {
+      "summary": "Back up a single VM (ID 101) to PBS storage using zstd compression in snapshot mode",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "vmid": "101",
+        "storage": "pbs-main",
+        "mode": "snapshot",
+        "compress": "zstd",
+        "zstd": 2,
+        "prune-backups": "keep-last=7,keep-weekly=4",
+        "notes-template": "{{guestname}} backup on {{node}}"
+      }
+    }
+  ],
+  "tips": [
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status or /log to follow progress.",
+    "snapshot mode is the default and keeps VMs running; use stop mode only if snapshot consistency is not achievable (e.g., no guest agent).",
+    "remove defaults to true — existing backups on the target storage will be pruned per prune-backups; set remove=false to retain all previous backups.",
+    "bwlimit, performance, and ionice require Sys.Modify on / — non-root API tokens without that privilege must omit these parameters.",
+    "fleecing (VM only) offloads dirty-block tracking to a separate storage, reducing I/O impact on production; specify a fast scratch storage via fleecing=enabled=1,storage=<id>.",
+    "mailto and mailnotification are deprecated; prefer notification-mode=notification-system and configure notification targets in the PVE notification panel."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "get_nodes_node_vzdump_defaults",
+    "get_cluster_backup",
+    "post_cluster_backup"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_wakeonlan.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_nodes_node_wakeonlan",
+  "usageNotes": "Sends a Wake-on-LAN magic packet to bring an offline Proxmox node back up. The target node must have WoL enabled in its BIOS/UEFI and the network interface must support it; the API call is made against a currently online node that forwards the magic packet on behalf of the offline one. Returns the MAC address that was used to construct the packet — useful for confirming the correct NIC was targeted.",
+  "examples": [
+    {
+      "summary": "Wake an offline node named 'pve2' via WoL",
+      "path_params": {
+        "node": "pve2"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint is called on an online node (e.g. pve1) to wake a peer node (pve2) — not on the offline node itself.",
+    "The MAC address in the response reflects what Proxmox has configured for that node's WoL NIC; verify it matches the physical NIC in the BIOS if WoL silently fails.",
+    "WoL requires the offline node to be on the same broadcast domain (L2 segment) as the sending node or a properly configured directed broadcast."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "post_nodes_node_shutdown",
+    "post_nodes_node_startall"
+  ]
+}

package/dist/catalog-pve/enrichment/post_pools.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_pools",
+  "usageNotes": "Use this to create a new resource pool, which is the prerequisite for grouping VMs, containers, and storage under a shared permission scope. The caller must hold Pool.Allocate on /pool/{poolid} — this is typically a datacenter-level admin privilege. The API returns null on success; there is no task UPID since pool creation is synchronous.",
+  "examples": [
+    {
+      "summary": "Create a pool for a client tenant with a descriptive comment",
+      "path_params": {},
+      "params": {
+        "poolid": "client-acme",
+        "comment": "ACME Corp managed resources"
+      }
+    }
+  ],
+  "tips": [
+    "Pool IDs must match the pve-poolid format: alphanumeric, hyphens, and underscores; no spaces.",
+    "Pool IDs are case-sensitive and cannot be renamed after creation — choose a stable identifier.",
+    "After creating the pool, use PUT /pools/{poolid} to add VMs, containers, or storage members."
+  ],
+  "relatedOperations": [
+    "get_pools",
+    "get_pools_{poolid}",
+    "put_pools_{poolid}",
+    "delete_pools_{poolid}"
+  ]
+}

package/dist/catalog-pve/enrichment/post_storage.json

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_storage",
+  "usageNotes": "Use this to register a new storage backend in the cluster-wide Proxmox storage configuration. Both 'storage' (the unique ID) and 'type' are required; all other params are type-specific — for example, NFS requires 'server' and 'export', PBS requires 'server' and 'datastore', and CIFS requires 'server' and 'share'. The operation is synchronous and returns the created storage ID and type immediately (no UPID); requires the Datastore.Allocate privilege on /storage.",
+  "examples": [
+    {
+      "summary": "Add an NFS share as a storage backend available to all nodes for VM images and backups",
+      "path_params": {},
+      "params": {
+        "storage": "nas-nfs",
+        "type": "nfs",
+        "server": "192.168.10.50",
+        "export": "/mnt/pool/proxmox",
+        "content": "images,backup",
+        "nodes": "pve01,pve02",
+        "shared": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'storage' ID must be unique across the cluster and follow pve-storage-id format (alphanumeric, hyphens allowed, no spaces).",
+    "Setting 'shared: true' only marks the storage as shared in the config — it does not mount or replicate data; the underlying share must already be accessible on all listed nodes.",
+    "For PBS storage, set 'datastore' to the PBS datastore name and 'fingerprint' to the PBS server's TLS certificate fingerprint to avoid using skip-cert-verification.",
+    "If using 'encryption-key: autogen' for PBS, save the returned key from the response 'config.encryption-key' field immediately — it cannot be retrieved again.",
+    "The 'content' field controls what can be stored: use 'images' for VM disks, 'rootdir' for CT volumes, 'backup' for vzdump archives, 'iso' for ISO images, 'snippets' for hook scripts.",
+    "Omitting 'nodes' makes the storage available cluster-wide; specify 'nodes' to restrict to specific hosts (useful for local storage types like dir or lvmthin)."
+  ],
+  "relatedOperations": [
+    "get_storage",
+    "get_storage_storage",
+    "put_storage_storage",
+    "delete_storage_storage",
+    "get_nodes_node_storage",
+    "get_nodes_node_storage_storage_status"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_acl.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_access_acl",
+  "usageNotes": "Use this to grant or revoke role-based permissions on a Proxmox resource path (e.g. /vms/100, /storage/local, /nodes/pve1). The caller must hold the 'Modify' privilege on the target path itself. Supplying delete=true removes the matching ACL entry instead of adding it; at least one of users, groups, or tokens must be provided alongside the required path and roles.",
+  "examples": [
+    {
+      "summary": "Grant PVEVMAdmin role to a user on a specific VM, propagating to child paths",
+      "path_params": {},
+      "params": {
+        "path": "/vms/100",
+        "roles": "PVEVMAdmin",
+        "users": "jsmith@pve",
+        "propagate": true
+      }
+    }
+  ],
+  "tips": [
+    "The path /vms/{vmid} targets a single VM; /vms/ (root) targets all VMs — be specific to avoid over-granting.",
+    "propagate defaults to true; set it to false when you want the permission to apply only at the exact path level and not be inherited by child objects.",
+    "Built-in roles (PVEAdmin, PVEVMAdmin, PVEAuditor, etc.) cannot be deleted — use get_access_roles to confirm a custom role exists before assigning it.",
+    "API tokens inherit at most the privileges of their owning user; assigning a role broader than the user's own permissions has no net effect for the token.",
+    "Removing a non-existent ACL entry (delete=true on an entry that doesn't exist) is a no-op and returns null without error."
+  ],
+  "relatedOperations": [
+    "get_access_acl",
+    "get_access_roles",
+    "post_access_users",
+    "get_access_users",
+    "post_access_groups"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_domains_realm.json

@@ -0,0 +1,35 @@
+{
+  "operationId": "put_access_domains_realm",
+  "usageNotes": "Use this to modify an existing authentication realm's settings (LDAP/AD server addresses, bind credentials, OpenID client config, sync behavior, etc.) without recreating it. The realm must already exist — use POST /access/domains to create it. Requires the Realm.Allocate privilege on /access/realm; use the 'digest' param to guard against concurrent modifications.",
+  "examples": [
+    {
+      "summary": "Update an AD/LDAP realm to add a fallback server and enforce LDAPS with TLS 1.2",
+      "path_params": {
+        "realm": "corp-ad"
+      },
+      "params": {
+        "server1": "dc01.corp.example.com",
+        "server2": "dc02.corp.example.com",
+        "mode": "ldaps",
+        "sslversion": "tlsv1_2",
+        "verify": true,
+        "port": 636,
+        "comment": "Primary AD realm — dual DC, LDAPS enforced"
+      }
+    }
+  ],
+  "tips": [
+    "The 'delete' param accepts a comma-separated list of setting keys (pve-configid-list format) to unset/reset to defaults — useful for removing stale bind passwords or obsolete filters.",
+    "Avoid setting 'secure: true'; it is deprecated. Use 'mode: ldaps' or 'mode: ldap+starttls' instead.",
+    "Setting 'default: true' on a realm makes it the pre-selected realm on the PVE login screen — only one realm can be default at a time.",
+    "LDAP bind passwords are stored in /etc/pve/priv/realm/<REALM>.pw on the cluster; this is a protected path only accessible to root.",
+    "For OpenID realms, 'autocreate' must be enabled if users logging in for the first time should be provisioned automatically; otherwise they must be pre-created in PVE.",
+    "Use 'check-connection: true' to validate the LDAP bind during the API call itself — useful for confirming connectivity before saving."
+  ],
+  "relatedOperations": [
+    "get_access_domains_realm",
+    "post_access_domains",
+    "delete_access_domains_realm",
+    "post_access_domains_realm_sync"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_groups_groupid.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "put_access_groups_groupid",
+  "usageNotes": "Use this to update the comment/description on an existing Proxmox group. The only modifiable field is `comment`; group membership is managed separately via user operations. Requires the `Group.Allocate` privilege on `/access/groups` — the same privilege needed to create or delete groups.",
+  "examples": [
+    {
+      "summary": "Add a descriptive comment to the 'admins' group",
+      "path_params": {
+        "groupid": "admins"
+      },
+      "params": {
+        "comment": "Full cluster administrators - break-glass access only"
+      }
+    }
+  ],
+  "tips": [
+    "Returns null on success — no response body confirms the change; follow up with get_access_groups_groupid to verify.",
+    "To clear a comment, send an empty string for the comment field.",
+    "Group membership changes require separate user-update calls (put_access_users_userid), not this endpoint."
+  ],
+  "relatedOperations": [
+    "get_access_groups_groupid",
+    "post_access_groups",
+    "delete_access_groups_groupid",
+    "get_access_groups"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_password.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_access_password",
+  "usageNotes": "Use this to change a PVE user's password; each user may change their own password, or an admin with Realm.AllocateUser + User.Modify on a shared group can change another user's password. API tokens are not accepted (allowtoken: false), so the caller must authenticate with a full user session or ticket. For PAM realm users, the change only applies to the local node — not cluster-wide.",
+  "examples": [
+    {
+      "summary": "Admin resets password for a local PVE user",
+      "path_params": {},
+      "params": {
+        "userid": "jsmith@pve",
+        "password": "S3cur3P@ssw0rd!",
+        "confirmation-password": "AdminCurrentP@ss1"
+      }
+    }
+  ],
+  "tips": [
+    "allowtoken is false — API token auth will be rejected; use a user ticket (POST /access/ticket) instead.",
+    "PAM realm password changes are node-local only; for cluster-wide effect the underlying Linux account must be synced externally.",
+    "The confirmation-password field is required when a non-admin user changes their own password to confirm current credentials; admins changing another user's password typically omit it.",
+    "Passwords must be 8–64 characters; enforce complexity at the application layer since the API only validates length.",
+    "Returns null on success — treat any non-2xx response as failure."
+  ],
+  "relatedOperations": [
+    "post_access_ticket",
+    "get_access_users",
+    "put_access_users_userid"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_roles_roleid.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_access_roles_roleid",
+  "usageNotes": "Use this to modify the privilege set of a custom Proxmox role. By default the update replaces the role's entire privilege list; pass `append: true` to add privileges without removing existing ones. The role must already exist (use `post_access_roles` to create it), and the caller requires `Sys.Modify` on `/access`.",
+  "examples": [
+    {
+      "summary": "Grant VM.PowerMgmt and VM.Console to the existing 'HelpDesk' role, preserving current privileges",
+      "path_params": {
+        "roleid": "HelpDesk"
+      },
+      "params": {
+        "privs": "VM.PowerMgmt,VM.Console",
+        "append": true
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `append` (or setting it false) performs a full replacement — all existing privileges are discarded and only the supplied `privs` list remains.",
+    "`privs` is a comma-separated list of Proxmox privilege strings (e.g. VM.Allocate, Datastore.AllocateSpace). Pass an empty string to clear all privileges from the role.",
+    "Built-in roles (Administrator, PVEVMUser, etc.) cannot be modified; only custom roles created via the API or UI are editable.",
+    "Returns null on success; any error is signalled by a non-2xx HTTP status with a JSON error body."
+  ],
+  "relatedOperations": [
+    "get_access_roles",
+    "get_access_roles_roleid",
+    "post_access_roles",
+    "delete_access_roles_roleid",
+    "put_access_acl"
+  ]
+}

package/dist/catalog-pve/enrichment/put_access_tfa_userid_id.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_access_tfa_userid_id",
+  "usageNotes": "Use this to modify an existing TFA entry for a user — typically to toggle it enabled/disabled or update its description. A user can edit their own entries; editing another user's entries requires the User.Modify privilege. Note that `allowtoken` is false, so this call must be authenticated with a real user session or ticket, not an API token.",
+  "examples": [
+    {
+      "summary": "Disable a TOTP entry for a user (e.g. during account recovery)",
+      "path_params": {
+        "userid": "jsmith@pve",
+        "id": "totp-7f3a2b1c"
+      },
+      "params": {
+        "enable": false,
+        "description": "Authenticator app (disabled for recovery)",
+        "password": "currentpassword123"
+      }
+    }
+  ],
+  "tips": [
+    "The `password` field is the current password of the user making the request, not the target user — required when a non-admin user modifies their own TFA entry.",
+    "To find a valid TFA entry `id`, first call GET /access/tfa/{userid} to list all entries for the user.",
+    "API tokens cannot call this endpoint (`allowtoken: false`); use a user ticket obtained via POST /access/ticket."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "delete_access_tfa_userid_id",
+    "get_access_tfa_userid_id"
+  ]
+}