@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,38 @@
+{
+  "operationId": "post_access_domains",
+  "usageNotes": "Use this to register a new authentication realm (AD, LDAP, OpenID Connect, PAM, or local PVE) so users can log in via that backend. Requires the `Realm.Allocate` privilege on `/access/realm`. The required parameters differ by `type`: AD/LDAP need `server1`, `base_dn`, and `user_attr`; OpenID needs `issuer-url`, `client-id`, and `client-key`; PAM and PVE need only `realm` and `type`.",
+  "examples": [
+    {
+      "summary": "Add an LDAP realm backed by an internal directory server",
+      "path_params": {},
+      "params": {
+        "realm": "corp-ldap",
+        "type": "ldap",
+        "server1": "ldap.corp.example.com",
+        "server2": "ldap2.corp.example.com",
+        "base_dn": "dc=corp,dc=example,dc=com",
+        "bind_dn": "cn=pve-bind,ou=svcaccts,dc=corp,dc=example,dc=com",
+        "user_attr": "uid",
+        "mode": "ldap+starttls",
+        "verify": true,
+        "autocreate": true,
+        "comment": "Corporate LDAP directory"
+      }
+    }
+  ],
+  "tips": [
+    "Set `check-connection: true` to validate bind credentials and server reachability at creation time rather than discovering failures on first login.",
+    "Use `mode: ldap+starttls` or `mode: ldaps` instead of the deprecated `secure` boolean; enforce `sslversion: tlsv1_2` or higher.",
+    "For OpenID realms, `username-claim` defaults to `sub` (an opaque identifier); set it to `email` or `preferred_username` for human-readable PVE usernames.",
+    "The `autocreate` flag creates PVE user records on first successful login but does not assign permissions — assign roles separately after users appear.",
+    "To make this realm the default shown on the login screen, set `default: true`; only one realm can hold this flag at a time.",
+    "The LDAP bind password is stored in `/etc/pve/priv/realm/<REALM>.pw` on the PVE host — treat that file as a secret."
+  ],
+  "relatedOperations": [
+    "get_access_domains",
+    "get_access_domains_realm",
+    "put_access_domains_realm",
+    "delete_access_domains_realm",
+    "post_access_domains_realm_sync"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_access_domains_realm_sync",
+  "usageNotes": "Triggers an LDAP/AD directory sync for the specified realm, writing users and/or groups into Proxmox's user.cfg; the call returns a task UPID immediately and the sync runs asynchronously (poll with the task API to confirm completion). The realm must already be configured as an LDAP/AD domain and the caller needs both 'Realm.AllocateUser' on '/access/realm/<realm>' and 'User.Modify' on '/access/groups/'. Prefer 'remove-vanished' over the deprecated 'full'/'purge' params; synced groups are always suffixed with '-<realm>', so pre-existing groups with that naming pattern will be overwritten.",
+  "examples": [
+    {
+      "summary": "Sync both users and groups from the 'corp' LDAP realm, enabling new accounts and removing vanished entries and their ACLs",
+      "path_params": {
+        "realm": "corp"
+      },
+      "params": {
+        "scope": "both",
+        "enable-new": true,
+        "remove-vanished": "entry;acl"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'dry-run': true first to preview what would be written without touching user.cfg — useful before the first production sync.",
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status to monitor completion.",
+    "Synced group names are always '<ldap-groupname>-<realm>'; ensure no manually created groups share that pattern or they will be overwritten.",
+    "'remove-vanished': 'none' (the default) is the safest option — it adds/updates but never deletes, making it idempotent for most scheduled sync jobs.",
+    "If 'enable-new' is false, newly discovered LDAP users are created in a disabled state and must be manually enabled before they can log in."
+  ],
+  "relatedOperations": [
+    "get_access_domains",
+    "get_access_domains_realm",
+    "post_access_domains",
+    "put_access_domains_realm",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_access_groups",
+  "usageNotes": "Use this to create a new Proxmox access group, which can then be assigned permissions on paths (via put_access_acl) and have users added to it. The caller must hold the Group.Allocate privilege on /access/groups. The groupid must match the pve-groupid format (alphanumeric, hyphens, underscores; max 64 chars) and must not already exist — creating a duplicate returns an error.",
+  "examples": [
+    {
+      "summary": "Create an 'it-admins' group for IT administrators",
+      "path_params": {},
+      "params": {
+        "groupid": "it-admins",
+        "comment": "IT administrators with full node access"
+      }
+    }
+  ],
+  "tips": [
+    "Group names are case-sensitive and must be unique cluster-wide.",
+    "Creating the group does not assign any permissions — follow up with put_access_acl to grant path-based privileges.",
+    "To add users to the group after creation, use put_access_users_userid with the groups field."
+  ],
+  "relatedOperations": [
+    "get_access_groups",
+    "get_access_groups_groupid",
+    "put_access_acl",
+    "delete_access_groups_groupid"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_access_openid_auth_url",
+  "usageNotes": "Use this to initiate an OpenID Connect login flow for a configured OpenID realm — it returns the provider's authorization URL to which the browser should be redirected. The realm must already be configured in Proxmox as an OpenID Connect authentication domain. This is a public endpoint (no auth token required) and is typically the first step before exchanging the callback code via the login endpoint.",
+  "examples": [
+    {
+      "summary": "Get the OpenID authorization URL for the 'sso' realm",
+      "path_params": {},
+      "params": {
+        "realm": "sso",
+        "redirect-url": "https://pve.nightsquawk.tech:8006"
+      }
+    }
+  ],
+  "tips": [
+    "The redirect-url must exactly match the allowed redirect URI configured in your OpenID provider (e.g., Keycloak, Google, Authentik) — a mismatch will cause the provider to reject the flow.",
+    "The returned URL is ephemeral and includes a state/nonce parameter; do not cache or reuse it across login attempts.",
+    "After the user authenticates at the returned URL, the provider redirects back to redirect-url with a code and state — pass these to the OpenID login endpoint to complete the flow."
+  ],
+  "relatedOperations": [
+    "post_access_openid_login",
+    "get_access_domains",
+    "post_access_ticket"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_access_openid_login",
+  "usageNotes": "Call this after the user completes the OpenID Connect authorization flow in the browser — it exchanges the authorization code for a PVE ticket and CSRF token. The `code`, `state`, and `redirect-url` must match exactly what the IdP returned and what was registered as the callback URL; a mismatch will cause the IdP to reject the code. The returned `ticket` and `CSRFPreventionToken` replace a standard username/password login for all subsequent API calls.",
+  "examples": [
+    {
+      "summary": "Exchange an OpenID authorization code for a PVE session ticket",
+      "path_params": {},
+      "params": {
+        "code": "4/0AY0e-g7Kv2eQ1rZmX9bLpNwTsU8dFhOcJiMaVbRqPwXzYeNkLdCuSmTnOoKjIlHg",
+        "redirect-url": "https://pve.nightsquawk.tech:8006",
+        "state": "random-csrf-state-abc123xyz"
+      }
+    }
+  ],
+  "tips": [
+    "The OpenID realm must be configured in Datacenter > Permissions > Realms before this endpoint is usable.",
+    "Use the returned `CSRFPreventionToken` as the `CSRFPreventionToken` header on all subsequent write requests; omitting it will result in 401 errors.",
+    "The `redirect-url` must exactly match the value used when initiating the authorization request — even a trailing slash difference will cause verification to fail.",
+    "Permissions are `world` (no auth required to call this endpoint), since it is the authentication handshake itself.",
+    "The `cap` field in the response contains the caller's capability map, useful for client-side UI permission gating without a separate API call."
+  ],
+  "relatedOperations": [
+    "post_access_ticket",
+    "get_access_openid_auth_url",
+    "delete_access_ticket"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_access_roles",
+  "usageNotes": "Use this to define a custom role that groups one or more Proxmox privileges, which can then be assigned to users or groups via ACL entries. The caller must hold `Sys.Modify` on `/access`. The `privs` field accepts a comma-separated privilege list (e.g. `VM.PowerMgmt,VM.Console`); omitting it creates an empty role that can be populated later with `put_access_roles_{roleid}`.",
+  "examples": [
+    {
+      "summary": "Create a read-only VM monitoring role",
+      "path_params": {},
+      "params": {
+        "roleid": "VMMonitor",
+        "privs": "VM.Audit,VM.Console"
+      }
+    }
+  ],
+  "tips": [
+    "Role IDs must match the `pve-roleid` format: alphanumeric plus hyphens/underscores, no spaces.",
+    "Built-in roles (Administrator, PVEAdmin, etc.) cannot be overwritten; choose a unique roleid.",
+    "An empty role (no privs) is valid and useful as a placeholder before privileges are finalized.",
+    "After creation, assign the role to a user/group with `post_access_acl`."
+  ],
+  "relatedOperations": [
+    "get_access_roles",
+    "get_access_roles_{roleid}",
+    "put_access_roles_{roleid}",
+    "delete_access_roles_{roleid}",
+    "put_access_acl"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_access_tfa_userid",
+  "usageNotes": "Use this to enroll a new TFA credential (TOTP app, WebAuthn/FIDO2 key, Yubico OTP, U2F, or recovery codes) for a specific user. A user may manage their own TFA entries; an admin with User.Modify can manage entries for others. Note that this endpoint does not accept API tokens (allowtoken: false) — callers must authenticate with a full user session ticket. For WebAuthn and U2F types, registration is a two-step flow: the first call returns a challenge, and a second call must supply the signed challenge response in the 'value' field.",
+  "examples": [
+    {
+      "summary": "Enroll a TOTP authenticator app for a local user",
+      "path_params": {
+        "userid": "jsmith@pve"
+      },
+      "params": {
+        "type": "totp",
+        "totp": "otpauth://totp/Proxmox:jsmith@pve?secret=JBSWY3DPEHPK3PXP&issuer=Proxmox&algorithm=SHA1&digits=6&period=30",
+        "value": "847291",
+        "description": "Authy phone app",
+        "password": "currentUserPassword"
+      }
+    }
+  ],
+  "tips": [
+    "Recovery codes (type='recovery') are returned only once in the response 'recovery' array — display them to the user immediately and store them securely; they cannot be retrieved again.",
+    "The 'password' field is required when a non-admin user changes their own TFA, enforcing re-authentication before modifying security settings.",
+    "For TOTP enrollment, generate the URI with a library or authenticator app, then pass the current 6-digit code as 'value' to verify the secret is correct before saving.",
+    "WebAuthn must be configured at the datacenter level (datacenter.cfg) before webauthn entries can be added.",
+    "U2F support is deprecated in newer Proxmox versions; prefer webauthn for new hardware key enrollments."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id",
+    "get_access_tfa"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_access_ticket",
+  "usageNotes": "Use this endpoint to authenticate a user and obtain a PVE ticket (cookie) and CSRFPreventionToken required for all subsequent authenticated API calls. The `password` field also accepts an existing valid ticket for ticket renewal. Note that API tokens (`allowtoken: false`) cannot be used to call this endpoint — it requires real user credentials.",
+  "examples": [
+    {
+      "summary": "Authenticate as the root@pam user to get a session ticket",
+      "path_params": {},
+      "params": {
+        "username": "root@pam",
+        "password": "S3cur3P@ssw0rd!"
+      }
+    }
+  ],
+  "tips": [
+    "The returned `ticket` value must be sent as a cookie named `PVEAuthCookie` on subsequent requests.",
+    "The `CSRFPreventionToken` must be included as the `CSRFPreventionToken` request header on all POST/PUT/DELETE requests; GET requests do not require it.",
+    "Tickets are valid for 2 hours; re-call this endpoint before expiry (or pass the old ticket as `password`) to renew without re-entering credentials.",
+    "If the user has TOTP/WebAuthn configured, the first call returns a `ticket` prefixed with `PVECHALLENGE:` — pass it back as `tfa-challenge` along with the OTP code to complete login.",
+    "The `realm` param lets you separate the realm from the username; otherwise include it directly as `user@realm` in `username`.",
+    "Use the optional `path` + `privs` params to verify a ticket AND check a privilege in a single round-trip instead of a separate ACL check."
+  ],
+  "relatedOperations": [
+    "get_access_ticket",
+    "get_access_users",
+    "post_access_tfa",
+    "get_access_permissions"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_access_users",
+  "usageNotes": "Use this to provision a new Proxmox VE user account in the specified realm (e.g. `pve`, `pam`, or an LDAP/AD realm). The `userid` must follow the `name@realm` format and the realm must already exist. The `password` field is only meaningful for the built-in `pve` realm — users in external realms (LDAP, AD, OpenID) authenticate against that backend, not Proxmox. The caller needs `Realm.AllocateUser` on the target realm and `User.Modify` on any groups being assigned.",
+  "examples": [
+    {
+      "summary": "Create a local PVE user assigned to the 'helpdesk' group with a 1-year expiry",
+      "path_params": {},
+      "params": {
+        "userid": "jsmith@pve",
+        "firstname": "John",
+        "lastname": "Smith",
+        "email": "jsmith@example.com",
+        "password": "TempPass123!",
+        "groups": "helpdesk",
+        "enable": true,
+        "expire": 1782000000,
+        "comment": "Helpdesk tier-1 tech, onboarded 2026-06-28"
+      }
+    }
+  ],
+  "tips": [
+    "The `password` field sets the initial Proxmox-local password and only takes effect for `@pve` realm users; omit it for LDAP/AD/OpenID realm users.",
+    "Use `expire` as a Unix epoch integer (e.g. from `date -d '2027-01-01' +%s`); set to 0 for no expiry.",
+    "Assigning a user to non-existent groups will cause the request to fail — create groups first via POST /access/groups.",
+    "The `keys` field stores YubiKey token IDs for second-factor auth; it does not configure TOTP — that is managed separately.",
+    "New users have no ACL permissions by default; grant access via PUT /access/acl after creation."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_users_userid",
+    "put_access_users_userid",
+    "delete_access_users_userid",
+    "post_access_groups",
+    "put_access_acl"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_access_users_userid_token_tokenid",
+  "usageNotes": "Use this to generate a scoped API token for a user — the only call that returns the raw token secret, which is shown exactly once and cannot be retrieved again, so callers must capture and store the `value` field immediately. Requires either acting as the token owner (`self`) or holding `User.Modify` on the user's group. By default, `privsep` is enabled, meaning the token's effective privileges are the intersection of its own ACLs and the user's ACLs; set `privsep` to false only when you need the token to act with the user's full permissions.",
+  "examples": [
+    {
+      "summary": "Create a 90-day automation token for an API service account with privilege separation enabled",
+      "path_params": {
+        "userid": "automation@pve",
+        "tokenid": "ci-runner"
+      },
+      "params": {
+        "comment": "CI pipeline token — expires 2026-09-26",
+        "expire": 1790438400,
+        "privsep": true
+      }
+    }
+  ],
+  "tips": [
+    "The returned `value` field is the raw secret — store it in a secrets manager immediately; this is the only time it is visible.",
+    "The `full-tokenid` in the response (format: `userid!tokenid`) is the identifier used in the `Authorization: PVEAPIToken=` header alongside the secret value.",
+    "Set `expire` to 0 for non-expiring tokens; omitting the field inherits the parent user's expiration, which may be unintentionally short.",
+    "Even with `privsep: false`, the token cannot exceed the user's own privileges — it does not grant escalation.",
+    "Token IDs must start with a letter and contain only alphanumerics, dots, hyphens, or underscores."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_token_tokenid",
+    "put_access_users_userid_token_tokenid",
+    "delete_access_users_userid_token_tokenid",
+    "get_access_users_userid",
+    "post_access_users"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_access_vncticket",
+  "usageNotes": "Used by VNC proxy services to verify a short-lived VNC ticket issued during console session setup before allowing the WebSocket/TCP connection to proceed. The ticket, issuing user (authid), resource path, and required privileges must all match for validation to succeed. This is a server-side handshake call — clients do not call it directly; it is invoked by the noVNC/SPICE proxy internally after the ticket is generated via the node-level VNC console endpoints.",
+  "examples": [
+    {
+      "summary": "Verify a VNC ticket for a user accessing the console of VM 100",
+      "path_params": {},
+      "params": {
+        "authid": "admin@pam",
+        "path": "/vms/100",
+        "privs": "VM.Console",
+        "vncticket": "PVEVNC:65000000::abcdef1234567890abcdef1234567890::1",
+        "port": 5900
+      }
+    }
+  ],
+  "tips": [
+    "VNC tickets are time-limited (typically ~2 minutes); verification must occur promptly after ticket issuance.",
+    "The 'path' and 'privs' fields mirror those checked when the ticket was originally generated — mismatches cause rejection even with a valid ticket.",
+    "Returns null on success; any non-2xx response indicates an invalid or expired ticket.",
+    "Port verification (the 'port' param) is optional but recommended to prevent ticket reuse on a different port."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_vncproxy",
+    "get_nodes_node_lxc_vmid_vncproxy",
+    "get_nodes_node_vncshell",
+    "get_access_ticket"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_cluster_acme_account",
+  "usageNotes": "Registers a new ACME account with a CA (defaults to Let's Encrypt production) and stores the account credentials in a named config file on the cluster. The `contact` field must be a valid email address that will receive expiry and revocation notices from the CA. If the CA requires External Account Binding (e.g. ZeroSSL, sectigo), supply both `eab-kid` and `eab-hmac-key` together; omitting one will cause registration to fail. You must pass the CA's Terms of Service URL via `tos_url` to indicate acceptance — most CAs will reject registration without it.",
+  "examples": [
+    {
+      "summary": "Register a default Let's Encrypt account with ToS acceptance",
+      "path_params": {},
+      "params": {
+        "name": "default",
+        "contact": "hello@nightsquawk.tech",
+        "directory": "https://acme-v02.api.letsencrypt.org/directory",
+        "tos_url": "https://letsencrypt.org/documents/LE-SA-v1.4-April-3-2024.pdf"
+      }
+    }
+  ],
+  "tips": [
+    "Let's Encrypt staging directory (https://acme-staging-v02.api.letsencrypt.org/directory) is useful for testing; certificates it issues are untrusted but rate limits are much higher.",
+    "The `name` field becomes the config file identifier reused when assigning this account to ACME domain entries — use a descriptive name (e.g. 'letsencrypt', 'zerossl') if you manage multiple CAs.",
+    "Only one account per name is allowed; attempting to register a duplicate name will return an error — use get_cluster_acme_account_name first to check existence.",
+    "EAB credentials are one-time-use secrets provided by the CA dashboard; store them securely before submitting — Proxmox does not echo them back after registration."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account",
+    "get_cluster_acme_account_name",
+    "put_cluster_acme_account_name",
+    "delete_cluster_acme_account_name",
+    "get_cluster_acme_directories",
+    "get_cluster_acme_tos"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_acme_plugins",
+  "usageNotes": "Use this to register a new ACME DNS-01 or standalone challenge plugin at the cluster level before it can be assigned to a certificate order. Requires the `Sys.Modify` privilege on `/`. For DNS-type plugins, the `api` field (provider name) and `data` field (base64-encoded API credentials) are both required in practice even though they are technically optional in the schema; omitting them will cause subsequent certificate issuance to fail. Returns null on success — confirm the plugin was created by calling GET /cluster/acme/plugins/{id}.",
+  "examples": [
+    {
+      "summary": "Add a Cloudflare DNS-01 ACME plugin with API token credentials",
+      "path_params": {},
+      "params": {
+        "id": "cf-plugin",
+        "type": "dns",
+        "api": "cf",
+        "data": "Q0ZfVG9rZW49eW91cl9jbG91ZGZsYXJlX2FwaV90b2tlbg==",
+        "validation-delay": 60,
+        "nodes": "pve1,pve2"
+      }
+    }
+  ],
+  "tips": [
+    "The `data` param must be base64-encoded key=value pairs in the format expected by the acme.sh DNS plugin (e.g., `CF_Token=abc123` → base64 encoded).",
+    "`validation-delay` defaults to 30 seconds; increase it (e.g., 120+) for DNS providers with slow propagation or high TTLs to avoid premature validation failures.",
+    "The `id` field follows the `pve-configid` format: alphanumeric and hyphens only, no spaces. This ID is referenced when assigning the plugin to an ACME account or domain order.",
+    "Omit `nodes` to make the plugin available cluster-wide; specify a comma-separated node list to restrict which nodes can use it.",
+    "The `standalone` type uses the built-in HTTP-01 challenge listener and does not require `api` or `data`."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins",
+    "get_cluster_acme_plugins_{id}",
+    "put_cluster_acme_plugins_{id}",
+    "delete_cluster_acme_plugins_{id}",
+    "get_cluster_acme_accounts",
+    "post_cluster_acme_accounts"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_cluster_backup",
+  "usageNotes": "Use this to create a new scheduled vzdump backup job at the cluster level; the job is persisted in /etc/pve/jobs.cfg and run by the PVE scheduler — it does not trigger an immediate backup run. Requires Sys.Modify on '/'; the 'tmpdir', 'dumpdir', and 'script' parameters are additionally restricted to root@pam. Always supply either 'vmid', 'pool', or 'all' to define scope, and either 'storage' or 'dumpdir' as the backup destination, or the job will be created with no effective targets.",
+  "examples": [
+    {
+      "summary": "Create a nightly zstd-compressed snapshot backup of two VMs to local PBS storage, keeping the last 7 daily backups",
+      "path_params": {},
+      "params": {
+        "vmid": "101,102",
+        "storage": "pbs-local",
+        "mode": "snapshot",
+        "compress": "zstd",
+        "schedule": "daily 02:00",
+        "prune-backups": "keep-daily=7",
+        "enabled": true,
+        "comment": "Nightly production VM backups"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'schedule' (systemd calendar event format, e.g. 'daily 02:00', 'weekly Mon 03:00') instead of the deprecated 'starttime'/'dow' pair.",
+    "The 'remove' param (default: true) prunes old backups per 'prune-backups' after each run — set to false if you want the storage's own retention policy to apply instead.",
+    "zstd compression with 'compress: zstd' is significantly faster than gzip/lzo for large VMs; pair with 'zstd: 0' to use all available cores.",
+    "Backup fleecing ('fleecing' param) allows snapshot-mode backups of running VMs with minimal I/O impact by using a scratch storage for the changed-block journal.",
+    "The 'node' param restricts the job to run only on the specified node; omit it for cluster-wide scope where any node can execute the job.",
+    "Returns null synchronously — job creation is not async. To verify the job was persisted, follow up with get_cluster_backup_id or list_cluster_backup."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup",
+    "get_cluster_backup_id",
+    "put_cluster_backup_id",
+    "delete_cluster_backup_id",
+    "post_nodes_node_vzdump",
+    "get_cluster_backup_id_included_volumes"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_cluster_bulk_action_guest_migrate",
+  "usageNotes": "Use this to evacuate all (or a filtered set of) guests from the cluster to a single target node in one API call — common for scheduled maintenance or emergency node drain. The `online` flag enables live migration for VMs and restart migration for containers, minimizing downtime; omitting it causes VMs to be shut down before moving. Returns a worker UPID immediately; track progress via the tasks API, as the actual migrations run asynchronously.",
+  "examples": [
+    {
+      "summary": "Live-migrate all guests to node pve2, up to 4 concurrent workers",
+      "path_params": {},
+      "params": {
+        "target": "pve2",
+        "online": true,
+        "max-workers": 4
+      }
+    }
+  ],
+  "destructiveReason": "Migrating all guests disrupts any VMs/CTs that cannot live-migrate (e.g., those using local disks without with-local-disks), causing a full shutdown-and-restart cycle and a service outage for those workloads.",
+  "tips": [
+    "Use the `vms` parameter to limit the operation to specific VMIDs rather than migrating every guest on the cluster — safer for production environments.",
+    "Set `with-local-disks: true` only if the target node has sufficient storage and network bandwidth; live storage migration is significantly slower than shared-storage migration.",
+    "Prefer `max-workers` (not the deprecated `maxworkers`) and keep it low (2–4) to avoid saturating cluster network bandwidth during migration.",
+    "The caller needs VM.Migrate on '/' for a full cluster sweep; if scoping to specific VMIDs via `vms`, the permission can be scoped per VM instead."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_cluster_tasks",
+    "post_nodes_node_qemu_vmid_migrate",
+    "post_nodes_node_lxc_vmid_migrate"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_cluster_bulk_action_guest_shutdown",
+  "usageNotes": "Use this to gracefully shut down all (or a filtered subset of) VMs and containers across the entire cluster in one call. Requires 'VM.PowerMgmt' on '/' for a cluster-wide sweep, or on each '/vms/<ID>' when scoping via the 'vms' parameter. Returns a UPID string — poll the task status endpoint to confirm completion before assuming all guests are down.",
+  "examples": [
+    {
+      "summary": "Shut down a specific set of VMs with a 5-minute timeout and force-stop fallback, limiting concurrency to 8 workers",
+      "path_params": {},
+      "params": {
+        "vms": [100, 101, 205],
+        "timeout": 300,
+        "force-stop": true,
+        "max-workers": 8
+      }
+    }
+  ],
+  "destructiveReason": "Issues ACPI shutdown signals (and optionally hard-stops after timeout) to every matched guest, terminating all running workloads and making services unavailable until guests are manually restarted.",
+  "tips": [
+    "Omitting 'vms' targets every running guest on the cluster — double-check scope before submitting.",
+    "The default 'force-stop: true' (default 1) means any guest that does not shut down within 'timeout' seconds will be hard-killed; set it to false and raise 'timeout' if guests need extra time for graceful shutdown scripts.",
+    "Use 'max-workers' to throttle concurrency on large clusters and avoid overloading storage or network during simultaneous shutdowns.",
+    "'maxworkers' is deprecated; always use 'max-workers' in new integrations.",
+    "Poll the returned UPID via GET /nodes/{node}/tasks/{upid}/status to confirm all workers finished before declaring the cluster quiesced."
+  ],
+  "relatedOperations": [
+    "post_cluster_bulk_action_guest_start",
+    "post_cluster_bulk_action_guest_stop",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_cluster_bulk_action_guest_start",
+  "usageNotes": "Use this to start or resume all (or a filtered subset of) guests cluster-wide in a single call — useful after a planned maintenance window or cluster reboot. The caller must hold VM.PowerMgmt on '/' for a blanket start or on each individual '/vms/<ID>' when scoping via the 'vms' parameter. The operation is asynchronous: the response is a UPID that can be polled for completion.",
+  "examples": [
+    {
+      "summary": "Bulk-start a specific set of VMs with increased parallelism and a 120-second timeout",
+      "path_params": {},
+      "params": {
+        "vms": [100, 101, 105],
+        "max-workers": 8,
+        "timeout": 120
+      }
+    }
+  ],
+  "tips": [
+    "Omit 'vms' to target every guest in the cluster — ensure you have VM.PowerMgmt on '/' before doing so.",
+    "Use 'max-workers' (not the deprecated 'maxworkers') to tune parallelism; the default of 4 is conservative and safe for most clusters.",
+    "The 'timeout' parameter applies only to VMs, not to LXC containers.",
+    "Poll the returned UPID via the tasks API (GET /nodes/{node}/tasks/{upid}/status) to confirm all guests reached the running state."
+  ],
+  "relatedOperations": [
+    "post_cluster_bulk_action_guest_stop",
+    "post_cluster_bulk_action_guest_migrate",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_cluster_bulk_action_guest_suspend",
+  "usageNotes": "Suspends all (or a filtered subset of) VMs and containers across the entire cluster in parallel. Use 'to-disk' (hibernate) when you need guests to survive a host reboot or power outage; omit it for a RAM-only suspend that is faster but volatile. Returns a UPID immediately — poll the task API to confirm completion before proceeding with maintenance. Caller must hold 'VM.PowerMgmt' on '/' or individually on each targeted VMID; 'to-disk' additionally requires 'VM.Config.Disk' and 'Datastore.AllocateSpace' on the state storage.",
+  "examples": [
+    {
+      "summary": "Hibernate a specific set of VMs to disk using shared storage, limiting concurrency to 2 workers",
+      "path_params": {},
+      "params": {
+        "to-disk": true,
+        "statestorage": "ceph-vms",
+        "vms": [100, 101, 205],
+        "max-workers": 2
+      }
+    }
+  ],
+  "destructiveReason": "Suspends running guests cluster-wide, interrupting all active workloads; RAM-only suspend is lost if the host reboots before guests are resumed.",
+  "tips": [
+    "Omit 'vms' to target every running guest on the cluster — verify scope before calling in production.",
+    "Use 'to-disk' with a reliable shared storage (Ceph, NFS) so VMs survive unexpected node failures during maintenance.",
+    "Prefer 'max-workers' over the deprecated 'maxworkers' alias.",
+    "After calling, poll the returned UPID via GET /nodes/{node}/tasks/{upid}/status before triggering subsequent cluster operations."
+  ],
+  "relatedOperations": [
+    "post_cluster_bulk_action_guest_start",
+    "post_cluster_bulk_action_guest_stop",
+    "post_cluster_bulk_action_guest_shutdown",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_config",
+  "usageNotes": "Use this endpoint once to bootstrap a new Proxmox VE cluster from a standalone node — it is a one-time, irreversible cluster initialization, not a reconfiguration of an existing cluster. The node must not already belong to a cluster; running this on a node that is already clustered will fail. Returns a task UPID (string) for an async operation; poll the task status before attempting to join additional nodes.",
+  "examples": [
+    {
+      "summary": "Create a two-link cluster named 'pve-cluster' with a dedicated corosync ring",
+      "path_params": {},
+      "params": {
+        "clustername": "pve-cluster",
+        "link0": "address=192.168.10.1,priority=0",
+        "link1": "address=10.0.1.1,priority=10",
+        "nodeid": 1,
+        "votes": 1
+      }
+    }
+  ],
+  "tips": [
+    "clustername follows the pve-node format: max 15 chars, alphanumeric and hyphens only.",
+    "If link[n] is omitted, Proxmox defaults to the node's primary IP as link0 — explicitly set it for multi-NIC or bonded corosync rings.",
+    "token-coefficient tunes the corosync token timeout for high-latency links; leave at default (125) for LAN clusters.",
+    "After this call succeeds and the UPID task completes, use post_cluster_config_nodes to join additional nodes to the cluster.",
+    "You cannot undo cluster creation via the API — to revert a node to standalone you must use pvecm destroycluster from the shell."
+  ],
+  "relatedOperations": [
+    "get_cluster_config",
+    "get_cluster_config_nodes",
+    "post_cluster_config_nodes",
+    "get_cluster_config_join",
+    "post_cluster_config_join"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_config_join",
+  "usageNotes": "Use this to add the current node to an existing Proxmox VE cluster; the node must not already belong to a cluster and must be freshly installed with no VMs or containers running. You must supply the root password of an active cluster member and the cluster's certificate fingerprint (obtainable via get_cluster_config_join on any existing member). If the cluster uses multiple corosync links, pass explicit link[n] addresses — the hostname-based fallback only works for single-link clusters.",
+  "examples": [
+    {
+      "summary": "Join a single-link cluster using an existing member's IP and fingerprint",
+      "path_params": {},
+      "params": {
+        "hostname": "192.168.10.11",
+        "fingerprint": "A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2",
+        "password": "rootpassword",
+        "link0": "address=192.168.10.12",
+        "nodeid": 3,
+        "votes": 1
+      }
+    }
+  ],
+  "tips": [
+    "Retrieve the correct fingerprint and cluster hostname by calling get_cluster_config_join on an existing member before calling this endpoint.",
+    "The password field is the root (superuser) password of the peer node specified in hostname — not of the node being joined.",
+    "For multi-link clusters, specify link0 through link7 matching the existing cluster's link layout; a mismatch will cause corosync communication failures.",
+    "Once joined, the node immediately participates in quorum; ensure the cluster has an odd number of votes (or a QDevice) to avoid split-brain after the join.",
+    "The force flag suppresses errors if the node name already exists in the cluster database but does not resolve underlying membership conflicts — use with caution."
+  ],
+  "relatedOperations": [
+    "get_cluster_config_join",
+    "get_cluster_config",
+    "get_cluster_status",
+    "get_nodes"
+  ]
+}