@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_config_nodes_node",
+  "usageNotes": "Called internally by the PVE join process to register a new node in the cluster's corosync configuration; do not call directly — use the cluster join workflow (pvecm add) instead, which invokes this endpoint on the existing cluster. The response returns the corosync authkey and updated corosync.conf that the joining node needs to bootstrap cluster membership. Supplying at least one link[n] parameter is strongly recommended for multi-NIC corosync configurations; if omitted, new_node_ip is used as fallback and a single link is assumed.",
+  "examples": [
+    {
+      "summary": "Register a new node 'pve-node3' with a dedicated corosync link",
+      "path_params": {
+        "node": "pve-node3"
+      },
+      "params": {
+        "link0": "192.168.10.13",
+        "new_node_ip": "192.168.10.13",
+        "nodeid": 3,
+        "votes": 1,
+        "apiversion": 1
+      }
+    }
+  ],
+  "tips": [
+    "The returned corosync_authkey and corosync_conf must be written to the joining node before it can participate in quorum — this is handled automatically by pvecm/pvejoin.",
+    "Check the warnings array in the response; non-fatal issues (e.g. link address not reachable) are reported there rather than as errors.",
+    "Use force=true only when retrying a partially failed join where the node entry already exists in the config — not as a general workaround.",
+    "nodeid must be unique across all cluster members; if omitted, PVE assigns the next available ID automatically.",
+    "link[n] supports up to 8 corosync rings (link0..link7); the priority field is silently ignored on node-add (it only applies during cluster creation)."
+  ],
+  "relatedOperations": [
+    "get_cluster_config_nodes",
+    "delete_cluster_config_nodes_node",
+    "get_cluster_config_join",
+    "post_cluster_config_join",
+    "get_cluster_config_totem"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_cluster_firewall_aliases",
+  "usageNotes": "Use this to define a reusable named alias for an IP address or CIDR range that can then be referenced by name in cluster-level firewall rules. The alias name must start with a letter and can only contain letters, digits, hyphens, and underscores (2–64 characters). Requires the Sys.Modify privilege on the root path '/'.",
+  "examples": [
+    {
+      "summary": "Create an alias for a trusted management network",
+      "path_params": {},
+      "params": {
+        "name": "mgmt-network",
+        "cidr": "10.10.0.0/24",
+        "comment": "Internal management VLAN"
+      }
+    }
+  ],
+  "tips": [
+    "Aliases are cluster-wide; once created they are available in both cluster-level and node/VM-level firewall rule editors.",
+    "The name pattern requires at least 2 characters and must begin with a letter — purely numeric names are rejected.",
+    "Returns null on success; check for a 4xx/5xx HTTP status to detect conflicts (e.g., duplicate alias name).",
+    "Alias names are case-sensitive in the API but may display differently in the UI — use consistent casing to avoid confusion."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_aliases",
+    "get_cluster_firewall_aliases_name",
+    "put_cluster_firewall_aliases_name",
+    "delete_cluster_firewall_aliases_name",
+    "post_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_cluster_firewall_groups",
+  "usageNotes": "Creates a new cluster-level firewall security group, which acts as a named, reusable set of firewall rules that can be referenced in VM, container, or host firewall policies. Requires the `Sys.Modify` privilege at the root (`/`) path — API tokens must have this privilege explicitly granted. The `rename` parameter doubles as an update path: POST with `rename` set to an existing group name and `group` set to the new name (or the same name to update only the comment) to rename or annotate an existing group without deleting it.",
+  "examples": [
+    {
+      "summary": "Create a security group for web-tier VMs allowing HTTP/HTTPS inbound",
+      "path_params": {},
+      "params": {
+        "group": "web-tier",
+        "comment": "Allow HTTP and HTTPS inbound for web-facing VMs"
+      }
+    }
+  ],
+  "tips": [
+    "Group names must start with a letter and can contain letters, digits, hyphens, and underscores (2–18 chars); plan a naming scheme before creating many groups.",
+    "Use the `digest` param when scripting bulk changes to detect race conditions — fetch the current digest from `get_cluster_firewall_groups` first.",
+    "Security groups created here are cluster-wide but contain no rules until you add them via the rule-creation endpoints (e.g., `post_cluster_firewall_groups_{group}_rules`).",
+    "To rename an existing group without losing its rules, POST with `rename` = current name and `group` = new name; rules are preserved under the new name."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups",
+    "delete_cluster_firewall_groups_{group}",
+    "get_cluster_firewall_groups_{group}",
+    "post_cluster_firewall_groups_{group}_rules",
+    "get_cluster_firewall_groups_{group}_rules"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_cluster_firewall_groups_group",
+  "usageNotes": "Use this to append a new firewall rule to an existing cluster-level security group; the security group must already exist (create it first via POST /cluster/firewall/groups). Requires 'Sys.Modify' on the root path, so only cluster administrators can call it. Rules are appended at the end by default — use 'pos' to insert at a specific position, keeping in mind that rules are evaluated top-down.",
+  "examples": [
+    {
+      "summary": "Block inbound SSH from the internet to any VM in the 'external-vms' security group, logged at warning level",
+      "path_params": {
+        "group": "external-vms"
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "dport": "22",
+        "comment": "Block inbound SSH from untrusted sources",
+        "log": "warning",
+        "enable": 1
+      }
+    }
+  ],
+  "tips": [
+    "The 'group' path parameter must match an existing security group name (2–18 chars, starts with a letter); creating a rule against a non-existent group returns an error.",
+    "Omitting 'enable' leaves the rule disabled by default in some PVE versions — explicitly set enable=1 to activate immediately.",
+    "Use the 'macro' field (e.g., 'SSH', 'HTTP', 'HTTPS') to apply predefined port+protocol combinations instead of manually setting proto/dport.",
+    "Set 'digest' to the current ruleset digest to guard against concurrent edits overwriting each other in multi-admin environments.",
+    "Rules referencing IP sets must prefix the set name with '+' (e.g., '+trusted-hosts') and the IP set must already exist at the cluster firewall level."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups",
+    "post_cluster_firewall_groups",
+    "get_cluster_firewall_groups_group",
+    "put_cluster_firewall_groups_group_pos",
+    "delete_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_groups_group_pos"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_cluster_firewall_ipset",
+  "usageNotes": "Creates a new cluster-level firewall IPSet, which is a named group of IP addresses or CIDRs that can be referenced by alias in firewall rules. Requires the `Sys.Modify` privilege on the root path. To rename an existing IPSet or update its comment without deleting it, pass the current name in `rename` and the new name (or same name) in `name`.",
+  "examples": [
+    {
+      "summary": "Create a new IPSet for trusted management hosts",
+      "path_params": {},
+      "params": {
+        "name": "mgmt-hosts",
+        "comment": "Trusted management workstations and jump hosts"
+      }
+    }
+  ],
+  "tips": [
+    "IPSet names must start with a letter and may only contain letters, digits, hyphens, and underscores (pattern: [A-Za-z][A-Za-z0-9\\-\\_]+).",
+    "Creating the IPSet is just the container — add individual IP/CIDR entries afterward using the POST /cluster/firewall/ipset/{name} endpoint.",
+    "Use the `digest` param to guard against concurrent modifications when scripting bulk changes.",
+    "The `rename` field doubles as an in-place update: set rename=<oldName> and name=<newName> to rename, or rename=name=<sameName> to update only the comment."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipset",
+    "post_cluster_firewall_ipset_name",
+    "get_cluster_firewall_ipset_name",
+    "delete_cluster_firewall_ipset_name"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_cluster_firewall_ipset_name",
+  "usageNotes": "Adds a single IP address, CIDR block, or alias to an existing cluster-level IPSet; the IPSet must already exist (create it first with POST /cluster/firewall/ipset). Requires the Sys.Modify privilege on '/'. Set nomatch=true to invert the entry, causing firewall rules that reference this IPSet to treat matching traffic as NOT belonging to the set.",
+  "examples": [
+    {
+      "summary": "Add a private subnet to the 'trusted-mgmt' IPSet with a descriptive comment",
+      "path_params": {
+        "name": "trusted-mgmt"
+      },
+      "params": {
+        "cidr": "10.10.20.0/24",
+        "comment": "Management VLAN - internal only"
+      }
+    }
+  ],
+  "tips": [
+    "The 'cidr' field accepts plain IPs (e.g. 192.168.1.5), CIDR ranges (e.g. 10.0.0.0/8), or an IPSet alias prefixed with '+' (e.g. +dc-hosts) if the alias is already defined.",
+    "nomatch entries are displayed with '!' in the Proxmox UI and flip the match logic for that entry — useful for blacklisting a subnet inside a broader allowed range.",
+    "This endpoint returns null on success; verify the entry was added with GET /cluster/firewall/ipset/{name}.",
+    "IPSet names must start with a letter and contain only letters, digits, hyphens, and underscores (2–64 chars); validate before calling."
+  ],
+  "relatedOperations": [
+    "post_cluster_firewall_ipset",
+    "get_cluster_firewall_ipset_name",
+    "put_cluster_firewall_ipset_name_cidr",
+    "delete_cluster_firewall_ipset_name_cidr",
+    "get_cluster_firewall_ipset"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_firewall_rules",
+  "usageNotes": "Use this to append a new firewall rule to the cluster-level ruleset, which applies globally across all nodes and VMs unless overridden at a lower scope. Requires the Sys.Modify privilege on the root path (/). Rules are inserted at the end of the list by default; supply 'pos' to insert at a specific zero-based position, which shifts existing rules down.",
+  "examples": [
+    {
+      "summary": "Block inbound SSH from a specific external subnet at the cluster level",
+      "path_params": {},
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "source": "198.51.100.0/24",
+        "dport": "22",
+        "comment": "Block SSH brute-force attempts from known bad subnet",
+        "enable": 1,
+        "log": "warning"
+      }
+    }
+  ],
+  "tips": [
+    "The 'action' field accepts either a standard verdict (ACCEPT, DROP, REJECT) or the name of an existing security group — use the 'group' type when referencing a security group.",
+    "New rules are disabled by default (enable=0) unless you explicitly pass enable=1; always verify the rule is active after creation.",
+    "Use the 'digest' param when scripting back-to-back changes to guard against race conditions with concurrent edits.",
+    "Do not mix IPv4 and IPv6 addresses in the same 'source' or 'dest' field; use separate rules for each address family.",
+    "Cluster-level rules are evaluated before node- and VM-level rules; an overly broad DROP here can silently block traffic across the entire cluster."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rules",
+    "get_cluster_firewall_rules_pos",
+    "put_cluster_firewall_rules_pos",
+    "delete_cluster_firewall_rules_pos",
+    "get_cluster_firewall_groups",
+    "post_cluster_firewall_groups"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_cluster_ha_groups",
+  "usageNotes": "Creates a new HA group that controls which cluster nodes can run HA-managed resources and in what priority order. Note: Proxmox has deprecated HA groups in favor of HA rules, so prefer the rules API for new deployments. Requires `Sys.Console` at the root path (`/`); all nodes listed in the `nodes` parameter must already be members of the cluster.",
+  "examples": [
+    {
+      "summary": "Create a restricted HA group pinning two VMs to primary node with a failover node",
+      "path_params": {},
+      "params": {
+        "group": "prod_ha_group",
+        "nodes": "pve-node1:100,pve-node2:50",
+        "restricted": true,
+        "nofailback": false,
+        "comment": "Production VMs - prefer pve-node1, failover to pve-node2"
+      }
+    }
+  ],
+  "tips": [
+    "Node priority is specified as `nodename:priority` (integer, higher = preferred); omit priority to treat all nodes equally.",
+    "With `restricted: true`, HA services in this group will never migrate to nodes outside the group list — use this when VMs must stay on licensed or high-spec nodes.",
+    "With `nofailback: false` (default), the CRM will migrate services back to the highest-priority node once it recovers; set `nofailback: true` to suppress that automatic migration.",
+    "The `group` identifier follows `pve-configid` format: lowercase alphanumeric and underscores only, no spaces.",
+    "This endpoint returns null on success; verify creation with GET /cluster/ha/groups/{group}."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_groups",
+    "get_cluster_ha_groups_group",
+    "put_cluster_ha_groups_group",
+    "delete_cluster_ha_groups_group",
+    "get_cluster_ha_resources",
+    "post_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_ha_resources",
+  "usageNotes": "Use this to register a VM or container with the Proxmox HA manager so the cluster can automatically start, restart, and migrate it when nodes fail. The target resource (VM or CT) must already exist on a cluster node before adding it to HA — the HA manager does not create resources. Requires the 'Sys.Console' privilege at the root path, so only cluster administrators can add HA resources.",
+  "examples": [
+    {
+      "summary": "Enable HA for VM 105, pinned to group 'production', with failback on",
+      "path_params": {},
+      "params": {
+        "sid": "vm:105",
+        "state": "started",
+        "group": "production",
+        "failback": true,
+        "max_restart": 2,
+        "max_relocate": 2,
+        "comment": "Primary web server — keep running"
+      }
+    }
+  ],
+  "tips": [
+    "The 'sid' shorthand (e.g. '105') resolves to 'vm:105' or 'ct:105' automatically, but using the explicit form avoids ambiguity when VM and CT IDs overlap.",
+    "Setting 'state' to 'stopped' at creation is useful for registering a resource without immediately letting the HA manager start it — helpful when you want HA tracking but control the first start manually.",
+    "The 'group' field references an HA group created via POST /cluster/ha/groups; omit it to let the HA manager use any available node.",
+    "After creating the resource, verify it appears with GET /cluster/ha/resources and that the 'status' field transitions from 'fence' or 'recovery' to 'started' within a few seconds on a healthy cluster.",
+    "auto-rebalance defaults to true (1); set it to false on latency-sensitive workloads to prevent unexpected live migrations during routine cluster rebalancing."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources",
+    "get_cluster_ha_resources_sid",
+    "put_cluster_ha_resources_sid",
+    "delete_cluster_ha_resources_sid",
+    "get_cluster_ha_groups",
+    "post_cluster_ha_groups",
+    "get_cluster_ha_status_current"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_cluster_ha_resources_sid_migrate",
+  "usageNotes": "Triggers a live (online) migration of an HA-managed VM or container to a specified node; the HA manager handles the actual move and the response returns immediately with migration metadata rather than a UPID. The caller needs `Sys.Console` on `/` (cluster root), and the target node must be online and a member of the HA cluster. Check the `blocking-resources` array in the response — if it is non-empty the migration was blocked due to node-affinity or resource-affinity constraints and the resource did not move.",
+  "examples": [
+    {
+      "summary": "Migrate VM 105 to node pve2",
+      "path_params": {
+        "sid": "vm:105"
+      },
+      "params": {
+        "node": "pve2"
+      }
+    }
+  ],
+  "destructiveReason": "The running VM or container is live-migrated away from its current node, causing a brief service interruption if live migration is not fully supported by the workload or storage backend.",
+  "tips": [
+    "Use the shorthand integer form for sid (e.g. '105') instead of 'vm:105' — both are accepted.",
+    "Check `comigrated-resources` in the response to discover any affinity-linked resources that will move with this resource.",
+    "If `blocking-resources` is returned, resolve affinity rules before retrying — affinity constraints override the migration request.",
+    "This endpoint requests migration; use `get_cluster_ha_resources_sid` to poll the resource's current node and state until the move completes.",
+    "For offline relocation (when the node is fenced/unavailable), use the relocate endpoint instead of migrate."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources_sid",
+    "post_cluster_ha_resources_sid_relocate",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_status_current"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_cluster_ha_resources_sid_relocate",
+  "usageNotes": "Use this to manually force an HA-managed VM or container to run on a specific node — for example, before maintenance or to rebalance load. The resource is stopped on its current node and restarted on the target node via the HA manager, so the target node must be online and a member of the HA cluster. The response is synchronous and reports affinity side-effects (co-migrated or blocking resources) rather than a UPID; actual migration is driven by the HA manager daemon after the request is accepted.",
+  "examples": [
+    {
+      "summary": "Relocate VM 105 to node pve2",
+      "path_params": {
+        "sid": "vm:105"
+      },
+      "params": {
+        "node": "pve2"
+      }
+    }
+  ],
+  "tips": [
+    "If the response includes 'blocking-resources', the relocation will not proceed until those affinity conflicts are resolved — check node-affinity and resource-affinity rules on the blocking SIDs.",
+    "Resources listed in 'comigrated-resources' will be moved to the same target node automatically due to positive affinity rules — verify this is acceptable before issuing the request.",
+    "The HA manager must be in the 'enabled' state for relocation to take effect; if HA is in maintenance or frozen mode, the request is accepted but the move will be deferred.",
+    "The shorthand SID format (e.g. '105' instead of 'vm:105') is accepted for VMs and containers."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources_sid",
+    "post_cluster_ha_resources_sid_migrate",
+    "get_cluster_ha_status_current",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_cluster_ha_rules",
+  "usageNotes": "Use this to define an HA placement rule that controls whether a set of HA-managed resources must share the same node (positive affinity) or must be kept on separate nodes (negative affinity). Requires the `Sys.Console` privilege at the root path — typically reserved for cluster administrators. Returns null on success; verify the rule was created with the corresponding GET /cluster/ha/rules endpoint.",
+  "examples": [
+    {
+      "summary": "Keep two VMs on the same node (positive node-affinity, strict)",
+      "path_params": {},
+      "params": {
+        "rule": "collocate-web-db",
+        "type": "node-affinity",
+        "affinity": "positive",
+        "resources": "vm:101,vm:102",
+        "nodes": "pve-node1:10,pve-node2:5",
+        "strict": true,
+        "comment": "Keep web and DB VMs colocated for low-latency access"
+      }
+    }
+  ],
+  "tips": [
+    "The `rule` identifier must be a valid pve-configid (alphanumeric, hyphens allowed, no spaces).",
+    "For `resource-affinity` type, the `nodes` param is ignored — only `resources` and `affinity` apply.",
+    "Setting `strict: true` means HA will refuse to migrate if the rule cannot be satisfied; use with caution in small clusters.",
+    "A disabled rule (`disable: true`) is stored but has no effect on HA scheduling — useful for temporarily suspending a rule without deleting it.",
+    "Nodes in the `nodes` list can include optional priority weights (e.g., `pve-node1:10`); higher priority nodes are preferred targets."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_rules",
+    "get_cluster_ha_rules_{rule}",
+    "put_cluster_ha_rules_{rule}",
+    "delete_cluster_ha_rules_{rule}",
+    "get_cluster_ha_resources",
+    "post_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "post_cluster_ha_status_arm_ha",
+  "usageNotes": "Use this endpoint to re-arm the Proxmox HA stack after it has been intentionally disarmed (e.g., following a manual quorum override or maintenance window). The call takes no parameters, returns null synchronously, and requires the Sys.Console privilege on the root path. Verify HA status via get_cluster_ha_status after calling to confirm the manager has resumed normal operation.",
+  "examples": [
+    {
+      "summary": "Re-arm the HA stack after a maintenance window",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The HA manager will only honor the re-arm once cluster quorum is restored; if the cluster is still partitioned or lacks quorum the manager will remain disarmed.",
+    "After calling this endpoint, poll GET /cluster/ha/status to confirm the HA manager state transitions back to 'master' or 'slave' (not 'error' or 'stopped').",
+    "This endpoint is idempotent — calling it when the HA stack is already armed has no effect and does not return an error."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_status",
+    "get_cluster_ha_status_manager_status",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_cluster_ha_status_disarm_ha",
+  "usageNotes": "Use this to disable the cluster-wide HA watchdog stack, typically during planned maintenance or controlled cluster shutdown where HA self-healing would interfere. The `resource-mode` parameter is required: choose `freeze` to pause HA command processing while leaving resources in place, or `ignore` to drop HA tracking entirely so resources can be managed manually. Requires `Sys.Console` on the root path (`/`), which is a privileged permission not granted by default to most API tokens.",
+  "examples": [
+    {
+      "summary": "Disarm HA in freeze mode before a rolling maintenance window",
+      "path_params": {},
+      "params": {
+        "resource-mode": "freeze"
+      }
+    }
+  ],
+  "tips": [
+    "Use `freeze` when you want to resume HA management after maintenance without reconfiguring resources; use `ignore` only if you intend to manage resources manually for an extended period.",
+    "After the maintenance window, re-arm HA via the corresponding arm-ha endpoint to restore watchdog supervision cluster-wide.",
+    "Returns null on success — no UPID; the operation is synchronous from the API perspective but watchdog release propagates across cluster nodes asynchronously.",
+    "Ensure all cluster nodes are reachable before disarming; a partitioned node may continue its local watchdog behavior independently."
+  ],
+  "relatedOperations": [
+    "post_cluster_ha_status_arm_ha",
+    "get_cluster_ha_status",
+    "get_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_jobs_realm_sync_id",
+  "usageNotes": "Creates a scheduled realm-sync job that periodically imports users and/or groups from an external authentication domain (e.g., LDAP, AD) into Proxmox. The `schedule` field uses systemd calendar event syntax (e.g., `daily`, `0/6:00`) and is required. The caller must hold `Realm.AllocateUser` on the target realm and `User.Modify` on `/access/groups/`; this is a cluster-level config write and returns null on success (not a UPID — the job runs on its own schedule, not immediately).",
+  "examples": [
+    {
+      "summary": "Create a nightly LDAP sync job that enables new users and removes vanished entries",
+      "path_params": {
+        "id": "ldap-nightly-sync"
+      },
+      "params": {
+        "realm": "company-ldap",
+        "schedule": "daily",
+        "scope": "both",
+        "enable-new": true,
+        "enabled": true,
+        "remove-vanished": "entry;acl",
+        "comment": "Nightly sync of all users and groups from company LDAP"
+      }
+    }
+  ],
+  "tips": [
+    "The `id` must conform to pve-configid format (alphanumeric plus hyphen/underscore, max 64 chars) and must be unique across all realm-sync jobs.",
+    "Set `remove-vanished` cautiously: including `properties` will strip custom PVE attributes on existing users that are not present in the LDAP source.",
+    "This endpoint creates the job definition only — to trigger an immediate sync run, use the separate run/trigger endpoint for realm-sync jobs.",
+    "The `realm` body param must match an existing authentication domain configured under Datacenter > Permissions > Realms.",
+    "Disabling `enable-new` (set to false) lets you review imported accounts before they can log in, useful for staged rollouts."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync",
+    "get_cluster_jobs_realm_sync_id",
+    "put_cluster_jobs_realm_sync_id",
+    "delete_cluster_jobs_realm_sync_id",
+    "post_access_domains_realm_sync"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_cluster_mapping_dir",
+  "usageNotes": "Use this to register a new cluster-wide directory mapping that abstracts host-specific local paths behind a shared identifier — required before you can reference the mapping in storage or VM configurations. The caller must hold `Mapping.Modify` on `/mapping/dir`. The `map` array must contain at least one node-to-path entry; the mapping ID (`id`) must be a valid PVE config identifier (alphanumeric plus hyphens/underscores, no spaces).",
+  "examples": [
+    {
+      "summary": "Create a directory mapping for a shared ISO store path that differs by node",
+      "path_params": {},
+      "params": {
+        "id": "iso-store",
+        "description": "Per-node ISO image directory mapping",
+        "map": [
+          "node=pve01,path=/mnt/iso",
+          "node=pve02,path=/mnt/iso"
+        ]
+      }
+    }
+  ],
+  "tips": [
+    "The mapping ID must follow pve-configid format: start with a letter, use only [A-Za-z0-9_-], max 64 chars.",
+    "Each entry in `map` is a string in `node=<nodename>,path=<absolute-path>` format; every cluster node you want covered needs its own entry.",
+    "Returns null on success — confirm creation with get_cluster_mapping_dir or list_cluster_mapping_dir.",
+    "Directory mappings are cluster-wide metadata; the underlying path must exist on each referenced node independently."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir",
+    "put_cluster_mapping_dir",
+    "delete_cluster_mapping_dir",
+    "get_cluster_mapping_dir_id"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_mapping_pci",
+  "usageNotes": "Use this to create a cluster-wide logical PCI device mapping that can be referenced in VM configurations instead of hard-coding physical addresses. The `map` array must list per-node entries in `node=<name>,path=<DDDD:BB:SS.F>,id=<vendor:device>` format so Proxmox can resolve the correct physical device on each node at VM start time. Requires the `Mapping.Modify` privilege on `/mapping/pci`; returns null on success (no UPID — operation is synchronous).",
+  "examples": [
+    {
+      "summary": "Create a logical PCI mapping for a GPU present on two cluster nodes",
+      "path_params": {},
+      "params": {
+        "id": "rtx3090",
+        "description": "NVIDIA RTX 3090 GPU — available on pve1 and pve2",
+        "map": [
+          "node=pve1,path=0000:01:00.0,id=10de:2204",
+          "node=pve2,path=0000:03:00.0,id=10de:2204"
+        ],
+        "mdev": false,
+        "live-migration-capable": false
+      }
+    }
+  ],
+  "tips": [
+    "The `id` field must follow the pve-configid format: lowercase alphanumeric plus hyphens, no spaces.",
+    "Each entry in `map` is a comma-separated key=value string: node, path (PCI address in DDDD:BB:SS.F notation), and id (vendor:device hex).",
+    "Set `mdev: true` only for devices that expose mediated device (vGPU) interfaces; setting it on a bare-passthrough device has no effect.",
+    "`live-migration-capable` is experimental — only set it when both hardware IOMMU ACS and the guest driver explicitly support peer-to-peer DMA migration.",
+    "After creating a mapping here, reference it in a VM config via `hostpci0: mapping=<id>` rather than a raw PCI address."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_pci",
+    "get_cluster_mapping_pci_id",
+    "put_cluster_mapping_pci_id",
+    "delete_cluster_mapping_pci_id"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_cluster_mapping_usb",
+  "usageNotes": "Use this to define a named, cluster-wide USB device mapping so VMs can reference a logical ID rather than node-specific hardware paths. The caller must hold the Mapping.Modify privilege on /mapping/usb. Each entry in the map array ties a cluster node to the physical USB device identifiers (vendor/product ID or device path) on that node.",
+  "examples": [
+    {
+      "summary": "Create a USB mapping for a Yubikey hardware token available on two nodes",
+      "path_params": {},
+      "params": {
+        "id": "yubikey-auth",
+        "description": "Yubico YubiKey 5 NFC - shared auth token for privileged VMs",
+        "map": [
+          "node=pve01,vendorid=1050,productid=0407",
+          "node=pve02,vendorid=1050,productid=0407"
+        ]
+      }
+    }
+  ],
+  "tips": [
+    "The id field must be a valid pve-configid (alphanumeric and hyphens, no spaces); choose a name that reflects the device purpose rather than a hardware identifier.",
+    "Each map entry must name at least one cluster node; nodes not listed will not expose the mapping to VMs scheduled on them.",
+    "After creation, assign the mapping to a VM via the VM's hardware config (usb0: mapping=<id>); the mapping itself does not attach anything automatically.",
+    "Returns null on success — confirm creation by calling get_cluster_mapping_usb_id or listing mappings with get_cluster_mapping_usb."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_usb",
+    "get_cluster_mapping_usb_id",
+    "put_cluster_mapping_usb_id",
+    "delete_cluster_mapping_usb_id"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_metrics_server_id",
+  "usageNotes": "Use this to register a new external metrics backend (Graphite, InfluxDB, or OpenTelemetry) that all cluster nodes will push performance data to. The `type` field determines which set of optional params apply: InfluxDB HTTP v2 needs `bucket`, `organization`, and `token`; Graphite needs `path` and optionally `proto`; OpenTelemetry uses the `otel-*` params. Requires `Sys.Modify` on `/` — API tokens must explicitly hold this privilege.",
+  "examples": [
+    {
+      "summary": "Add an InfluxDB v2 HTTP metrics server",
+      "path_params": {
+        "id": "influx-prod"
+      },
+      "params": {
+        "type": "influxdb",
+        "server": "influxdb.internal.example.com",
+        "port": 8086,
+        "influxdbproto": "https",
+        "bucket": "proxmox",
+        "organization": "nightsquawk",
+        "token": "my-influxdb-api-token",
+        "verify-certificate": true
+      }
+    }
+  ],
+  "tips": [
+    "The `id` path param must match the pve-configid format (alphanumeric, hyphens allowed, no spaces) and must be unique across all existing metric server entries.",
+    "For InfluxDB v1 compatibility API, omit `organization` and use `user:password` as the `token` value.",
+    "Set `disable: true` to register the config without activating it — useful for staging before cutover.",
+    "UDP (the InfluxDB default) has no delivery guarantee; switch to `influxdbproto: http` or `https` for reliable delivery in production.",
+    "OpenTelemetry `otel-headers` and `otel-resource-attributes` must be base64-encoded JSON strings."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server",
+    "get_cluster_metrics_server_id",
+    "put_cluster_metrics_server_id",
+    "delete_cluster_metrics_server_id"
+  ]
+}