@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "put_cluster_metrics_server_id",
+  "usageNotes": "Use this to modify an existing metrics server entry (InfluxDB, Graphite, or OpenTelemetry) in the cluster-wide metrics configuration; requires Sys.Modify on the root path (/). The 'port' and 'server' fields are always required even on updates — omitting them will fail. Use the 'delete' param (comma-separated field names) to unset optional fields rather than setting them to empty strings.",
+  "examples": [
+    {
+      "summary": "Switch an existing InfluxDB metrics server from UDP to HTTPS v2 API with token auth",
+      "path_params": {
+        "id": "influxdb-prod"
+      },
+      "params": {
+        "server": "metrics.internal.example.com",
+        "port": 8086,
+        "influxdbproto": "https",
+        "bucket": "proxmox",
+        "organization": "nightsquawk",
+        "token": "my-influxdb-api-token",
+        "verify-certificate": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'delete' param accepts a comma-separated pve-configid-list — use it to clear fields like 'token' or 'bucket' when switching protocol types.",
+    "Pass 'digest' (obtained from the GET endpoint) to guard against concurrent edits overwriting each other.",
+    "InfluxDB v2 API requires 'influxdbproto' set to 'http' or 'https' plus 'bucket', 'organization', and 'token'; v1 compatibility uses 'user:password' in the token field.",
+    "For Graphite destinations, set 'path' to a dot-notation prefix (e.g. proxmox.mycluster) and optionally set 'proto' to 'tcp' for reliable delivery.",
+    "Set 'disable' to true to pause metric shipping without deleting the configuration.",
+    "OpenTelemetry params (otel-*) only apply when the server type is OTLP; mixing otel-* params with InfluxDB/Graphite configs has no effect but will not error."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server_id",
+    "get_cluster_metrics_server",
+    "post_cluster_metrics_server",
+    "delete_cluster_metrics_server_id"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_cluster_notifications_endpoints_gotify_name",
+  "usageNotes": "Use this to modify an existing Gotify push-notification endpoint — update its server URL, rotate the secret token, toggle it on/off, or clear optional fields via the `delete` array. Requires `Mapping.Modify` on `/mapping/notifications` plus either `Sys.Modify`/`Sys.Audit` or `Sys.AccessNetwork` on `/`; API tokens are accepted. Pass the `digest` from the current GET response to guard against concurrent edits.",
+  "examples": [
+    {
+      "summary": "Rotate the Gotify token and re-enable a previously disabled endpoint",
+      "path_params": {
+        "name": "gotify-alerts"
+      },
+      "params": {
+        "server": "https://gotify.example.com",
+        "token": "Abc123SecretToken",
+        "disable": false,
+        "digest": "a3f1c2d4e5b6a7d8e9f0a1b2c3d4e5f6a7b8c9d0"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` array to unset optional fields (e.g., `\"delete\": [\"comment\"]`) rather than passing an empty string.",
+    "Always fetch the current endpoint config first (get_gotify_endpoint) to obtain the `digest` before writing — this prevents silent overwrites from concurrent changes.",
+    "Disabling via `disable: true` is non-destructive: the endpoint config is preserved and can be re-enabled without reconfiguring server/token."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_gotify_name",
+    "post_cluster_notifications_endpoints_gotify",
+    "delete_cluster_notifications_endpoints_gotify_name",
+    "get_cluster_notifications_endpoints_gotify"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_cluster_notifications_endpoints_sendmail_name",
+  "usageNotes": "Use this to update an existing sendmail notification endpoint — changing recipients, the from-address, display author, or enabling/disabling the target. Requires `Mapping.Modify` on `/mapping/notifications` combined with either `Sys.Modify`/`Sys.Audit` or `Sys.AccessNetwork` on `/`. Pass the `digest` from the current GET response to guard against concurrent edits; omit fields you do not intend to change, and list any fields to remove in the `delete` array rather than blanking them.",
+  "examples": [
+    {
+      "summary": "Update the 'ops-alerts' sendmail endpoint to add a second recipient and disable it temporarily",
+      "path_params": {
+        "name": "ops-alerts"
+      },
+      "params": {
+        "mailto": ["admin@example.com", "oncall@example.com"],
+        "disable": true,
+        "comment": "Temporarily disabled during mail server maintenance"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` array (e.g. [\"from-address\", \"author\"]) to revert optional fields to their defaults rather than setting them to empty strings.",
+    "The `name` path param must match the pve-configid format (alphanumeric plus hyphens, no spaces).",
+    "Fetch the current endpoint with GET /cluster/notifications/endpoints/sendmail/{name} first to capture the digest for safe concurrent-edit protection.",
+    "`mailto-user` accepts Proxmox user IDs (e.g. 'root@pam'); those users must have a valid email set in their profile for delivery to work."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_sendmail_name",
+    "post_cluster_notifications_endpoints_sendmail",
+    "delete_cluster_notifications_endpoints_sendmail_name",
+    "get_cluster_notifications_endpoints_sendmail"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "put_cluster_notifications_endpoints_smtp_name",
+  "usageNotes": "Use this to update an existing cluster-level SMTP notification endpoint — for example to rotate credentials, change the relay server, or update the recipient list. The endpoint must already exist (create it first with the POST equivalent). The caller needs `Mapping.Modify` on `/mapping/notifications` plus either `Sys.Modify`/`Sys.Audit` or `Sys.AccessNetwork` on `/`; pass the current config `digest` to guard against concurrent edits. Returns null synchronously — there is no async UPID.",
+  "examples": [
+    {
+      "summary": "Update SMTP relay credentials and recipient list for an existing 'alerts-smtp' endpoint",
+      "path_params": {
+        "name": "alerts-smtp"
+      },
+      "params": {
+        "server": "smtp.mailgun.org",
+        "mode": "starttls",
+        "port": 587,
+        "username": "postmaster@mg.nightsquawk.tech",
+        "password": "s3cr3tAppPassword!",
+        "from-address": "noreply@nightsquawk.tech",
+        "author": "NightSquawk Tech Alerts",
+        "mailto": ["hello@nightsquawk.tech"],
+        "comment": "Updated relay credentials 2026-06-28"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting a field leaves its current value unchanged; use the `delete` array to explicitly clear optional fields (e.g., `\"delete\": [\"comment\"]`).",
+    "Default port depends on mode: 465 for tls, 587 for starttls, 25 for insecure — omit `port` to let Proxmox pick the correct default when changing `mode`.",
+    "Fetch the current digest via GET /cluster/notifications/endpoints/smtp/{name} and pass it to prevent a lost-update race between concurrent operators.",
+    "Passwords are write-only in the API response; you cannot retrieve the stored password — store credentials in a secrets manager separately.",
+    "Setting `disable: true` silences alerts from this endpoint without deleting it, useful during maintenance windows."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_smtp_name",
+    "post_cluster_notifications_endpoints_smtp",
+    "delete_cluster_notifications_endpoints_smtp_name",
+    "get_cluster_notifications_endpoints_smtp"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_cluster_notifications_endpoints_webhook_name",
+  "usageNotes": "Use this to update an existing webhook notification endpoint in the cluster — change its URL, HTTP method, headers, secrets, or toggle it on/off without recreating it. Requires 'Mapping.Modify' on '/mapping/notifications' plus either 'Sys.Modify'/'Sys.Audit' or 'Sys.AccessNetwork' on '/'. Supply the 'digest' field (from the GET response) to guard against concurrent edits; omit it only if race conditions are acceptable.",
+  "examples": [
+    {
+      "summary": "Update the target URL and re-enable a previously disabled webhook endpoint",
+      "path_params": {
+        "name": "alerts-webhook"
+      },
+      "params": {
+        "url": "https://hooks.example.com/proxmox/v2/alerts",
+        "method": "post",
+        "disable": false,
+        "comment": "Updated to v2 endpoint URL",
+        "digest": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+      }
+    }
+  ],
+  "tips": [
+    "Header values and secret values must be base64-encoded before being passed in the 'header' and 'secret' arrays, formatted as 'name=<name>,value=<base64>'.",
+    "Use the 'delete' array to remove individual optional fields (e.g. 'body', 'comment') rather than overwriting them with empty strings.",
+    "Fetch the current config with get_cluster_notifications_endpoints_webhook_name first to obtain a fresh 'digest' before submitting updates.",
+    "Returns null on success; any HTTP error indicates the config was not applied."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_webhook_name",
+    "post_cluster_notifications_endpoints_webhook",
+    "delete_cluster_notifications_endpoints_webhook_name",
+    "get_cluster_notifications_endpoints"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "put_cluster_notifications_matchers_name",
+  "usageNotes": "Use this to update an existing notification matcher's targeting rules, severity filters, calendar windows, or assigned targets. Requires Mapping.Modify on /mapping/notifications. Supply the digest from the GET response to guard against concurrent edits overwriting each other. To clear an optional field (e.g. remove match-calendar entries), pass the field name(s) in the delete array rather than setting them empty.",
+  "examples": [
+    {
+      "summary": "Update matcher to route critical and error backup notifications to a Gotify target, effective only on weekdays",
+      "path_params": {
+        "name": "backup-alerts"
+      },
+      "params": {
+        "match-severity": ["critical", "error"],
+        "match-field": ["exact:type=vzdump"],
+        "match-calendar": ["mon..fri 08:00-20:00"],
+        "target": ["gotify-ops"],
+        "mode": "all",
+        "disable": false,
+        "comment": "Weekday backup failure alerts to ops Gotify channel"
+      }
+    }
+  ],
+  "tips": [
+    "The delete param accepts an array of param names (e.g. [\"match-calendar\"]) to unset fields — you cannot clear them by omitting them or passing empty arrays.",
+    "mode: 'all' requires every specified match-* condition to be true simultaneously; mode: 'any' fires on the first match — pick carefully when combining severity and field filters.",
+    "invert-match negates the entire combined result, useful for 'notify on anything except' patterns.",
+    "match-field values must be prefixed with 'exact:' or 'regex:' followed by field=value; omitting the prefix causes a validation error.",
+    "Returns null on success — check for HTTP 200 to confirm the update was applied."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers_name",
+    "post_cluster_notifications_matchers",
+    "delete_cluster_notifications_matchers_name",
+    "get_cluster_notifications_matchers",
+    "get_cluster_notifications_targets"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_cluster_options",
+  "usageNotes": "Use this to update cluster-wide datacenter settings such as migration policy, HA behavior, bandwidth limits, console type, and WebAuthn/U2F configuration. Requires `Sys.Modify` on `/` (root path), so only cluster administrators can call it. The operation returns null synchronously — changes take effect immediately with no task UPID to poll; use `delete` param to unset individual settings rather than omitting them.",
+  "examples": [
+    {
+      "summary": "Set migration to insecure on a private network, cap migration bandwidth to 500 MiB/s, and switch console to xtermjs",
+      "path_params": {},
+      "params": {
+        "migration": "insecure,network=10.10.0.0/24",
+        "bwlimit": "migration=512000",
+        "console": "xtermjs"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` param (comma-separated config key names) to remove a setting back to its default rather than setting it to an empty string.",
+    "`migration_unsecure` is deprecated — set `migration` type=insecure instead.",
+    "Changing `webauthn` id or origin will invalidate existing hardware key registrations for all users.",
+    "`mac_prefix` only affects auto-generated MACs for new guests; existing VMs keep their current MAC.",
+    "The `notify` field sub-keys are largely deprecated in favor of the datacenter notification targets UI — check PVE release notes before relying on them.",
+    "`fencing` modes `hardware` and `both` are marked EXPERIMENTAL — only use `watchdog` in production unless you have tested fence devices configured."
+  ],
+  "relatedOperations": [
+    "get_cluster_options",
+    "get_cluster_ha_status",
+    "put_cluster_ha_groups_group"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_cluster_qemu_custom_cpu_models_cputype",
+  "usageNotes": "Use this to modify an existing cluster-wide custom CPU model definition — for example to add or remove CPU flags, change the reported model, or adjust CPUID visibility settings. The caller must hold the Mapping.Modify privilege on /mapping/cpu/{cputype}; the model must already exist (use the POST endpoint to create it). Pass a digest obtained from the GET response to guard against concurrent edits.",
+  "examples": [
+    {
+      "summary": "Add spec-ctrl and ssbd mitigations to an existing custom CPU model and set reported-model to Haswell",
+      "path_params": {
+        "cputype": "custom-sec-baseline"
+      },
+      "params": {
+        "flags": "+spec-ctrl;+ssbd",
+        "reported-model": "Haswell",
+        "digest": "a3f1c2d4e5b6a7f8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
+      }
+    }
+  ],
+  "tips": [
+    "The 'custom-' prefix in the cputype path segment is optional — Proxmox normalises both 'mycpu' and 'custom-mycpu' to the same model.",
+    "Use the 'delete' param (comma-separated config key names) to unset optional fields like 'flags' or 'hv-vendor-id' rather than passing empty strings.",
+    "Setting 'hidden: true' hides the KVM hypervisor signature from the guest; useful for software that refuses to run under a detected hypervisor.",
+    "Setting 'level: 30' is a documented workaround for Hyper-V boot failures on Windows guests running on recent Intel hosts.",
+    "Avoid setting 'phys-bits: host' if live migration across heterogeneous hardware is required — mismatched values will break migration.",
+    "This endpoint returns null on success; confirm the change by calling the corresponding GET to read back the updated definition."
+  ],
+  "relatedOperations": [
+    "get_cluster_qemu_custom_cpu_models_cputype",
+    "post_cluster_qemu_custom_cpu_models",
+    "delete_cluster_qemu_custom_cpu_models_cputype",
+    "get_cluster_qemu_custom_cpu_models"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_cluster_replication_id",
+  "usageNotes": "Use this to modify an existing replication job's schedule, rate limit, comment, or disabled state — the job must already exist (create via post_cluster_replication). The caller needs VM.Replicate on /vms/<vmid> derived from the job ID; pass the digest from a prior GET to guard against concurrent edits. Setting remove_job triggers a cleanup sequence rather than a simple config change — local snapshots are purged, and 'full' additionally attempts to remove replicated volumes on the target node.",
+  "examples": [
+    {
+      "summary": "Throttle a busy replication job and change its schedule to every 30 minutes",
+      "path_params": {
+        "id": "105-0"
+      },
+      "params": {
+        "rate": 50,
+        "schedule": "*/30",
+        "comment": "Reduced rate during business hours"
+      }
+    }
+  ],
+  "tips": [
+    "The job ID format is '<VMID>-<JOBNUM>' (e.g. '105-0'); the VMID portion drives the permission check on /vms/<vmid>.",
+    "Use the 'delete' param (comma-separated field names) to reset optional fields like 'rate' or 'comment' back to their defaults rather than setting them to an empty string.",
+    "remove_job='local' is safer: it only prunes local replication snapshots and removes the job config. remove_job='full' additionally attempts to delete the replicated volumes on the target — use with caution if the target data is still needed.",
+    "Returns null on success; errors surface as HTTP 4xx/5xx — check that the target node is reachable before updating schedule-related settings."
+  ],
+  "relatedOperations": [
+    "get_cluster_replication_id",
+    "post_cluster_replication",
+    "delete_cluster_replication_id",
+    "get_cluster_replication"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_cluster_sdn",
+  "usageNotes": "Call this after making changes to SDN zones, VNets, or subnets to push the pending configuration to all cluster nodes and reload the SDN controllers (e.g. OVN, EVPN). Requires the `SDN.Allocate` privilege on `/sdn`. If a `lock-token` was acquired before editing (to prevent concurrent SDN edits), pass it here; `release-lock` defaults to true so the lock is dropped automatically on success.",
+  "examples": [
+    {
+      "summary": "Apply pending SDN changes and release the configuration lock",
+      "path_params": {},
+      "params": {
+        "lock-token": "sdn-lock-abc123",
+        "release-lock": true
+      }
+    }
+  ],
+  "tips": [
+    "Returns a task UPID string — poll the task status endpoint to confirm all nodes applied the config before assuming success.",
+    "If no SDN changes are pending, the call still succeeds but triggers a gratuitous reload; safe to call but unnecessary.",
+    "Omit `lock-token` if you did not explicitly acquire a lock before editing; passing a stale or wrong token will cause the commit to fail.",
+    "In large clusters this is a cluster-wide operation — all nodes must be reachable for a clean reload."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn",
+    "get_cluster_sdn_zones",
+    "post_cluster_sdn_zones",
+    "put_cluster_sdn_zones_{zone}",
+    "get_cluster_sdn_vnets",
+    "post_cluster_sdn_vnets"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "put_cluster_sdn_controllers_controller",
+  "usageNotes": "Use this to modify an existing SDN controller object's configuration (e.g. updating BGP peers, ASN, or IS-IS parameters); the controller must already exist (create it first with POST /cluster/sdn/controllers). Requires the SDN.Allocate privilege on /sdn/controllers. Changes are staged in the cluster SDN config and must be applied via POST /cluster/sdn (reload) before they take effect on nodes.",
+  "examples": [
+    {
+      "summary": "Update an EVPN BGP controller to add a new peer and enable eBGP multipath relaxation",
+      "path_params": {
+        "controller": "evpn-ctrl01"
+      },
+      "params": {
+        "asn": 65001,
+        "bgp-mode": "external",
+        "peers": "10.10.0.1,10.10.0.2",
+        "bgp-multipath-as-path-relax": true,
+        "loopback": "lo"
+      }
+    }
+  ],
+  "tips": [
+    "Use the 'digest' param to guard against concurrent edits — fetch the current digest from GET /cluster/sdn/controllers/{controller} and pass it here.",
+    "The 'delete' param accepts a comma-separated list of property names (pve-configid-list format) to unset optional fields rather than setting them to a blank value.",
+    "After any SDN controller update, always call POST /cluster/sdn to push the staged config to all cluster nodes; without the reload, network changes are not applied.",
+    "For IS-IS controllers, 'isis-net' must follow the NSAP NET format (e.g. '49.0001.0100.1001.0001.00') and be unique per node in the IS-IS domain.",
+    "BGP mode 'auto' selects eBGP when a BGP controller is present, otherwise falls back to iBGP — use explicit 'external' or 'internal' to avoid ambiguity in mixed topologies."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_controllers_controller",
+    "post_cluster_sdn_controllers",
+    "delete_cluster_sdn_controllers_controller",
+    "get_cluster_sdn_controllers",
+    "post_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_cluster_sdn_dns_dns",
+  "usageNotes": "Use this to update an existing SDN DNS provider object (e.g. PowerDNS) in the cluster SDN configuration. Requires the `SDN.Allocate` privilege on `/sdn/dns`. After updating, you must apply the pending SDN configuration via `put_cluster_sdn` for the changes to take effect on nodes.",
+  "examples": [
+    {
+      "summary": "Update the API URL and TTL for an existing PowerDNS SDN integration",
+      "path_params": {
+        "dns": "pdns01"
+      },
+      "params": {
+        "url": "https://powerdns.internal:8081",
+        "key": "mysecretapikey",
+        "ttl": 300
+      }
+    }
+  ],
+  "tips": [
+    "Pass `digest` (from the corresponding GET) to guard against concurrent modifications — the API will reject the write if another change has been committed since you read the config.",
+    "Use the `delete` param to unset optional fields (e.g. `fingerprint`) rather than leaving stale values; value is a comma-separated list of config key names.",
+    "The `fingerprint` field (SHA-256, colon-separated hex pairs) is required when the DNS provider uses a self-signed TLS certificate and you want Proxmox to validate it.",
+    "Changes are staged — they do not propagate to SDN-capable nodes until you call the apply endpoint (`put_cluster_sdn`)."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_dns_dns",
+    "get_cluster_sdn_dns",
+    "post_cluster_sdn_dns",
+    "delete_cluster_sdn_dns_dns",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_sdn_fabrics_fabric_id",
+  "usageNotes": "Use this to modify an existing SDN fabric's protocol settings, IP prefix ranges, or routing parameters. The fabric must already exist; use the POST endpoint to create one. Changes take effect after running the SDN apply operation — the PUT itself returns null synchronously, not a task UPID. Requires SDN.Allocate on /sdn/fabrics/{id}; supply the current config digest to prevent race conditions when multiple operators may be editing simultaneously.",
+  "examples": [
+    {
+      "summary": "Update a WireGuard fabric to enable persistent keepalive for NAT traversal",
+      "path_params": {
+        "id": "wgfab01"
+      },
+      "params": {
+        "protocol": "wireguard",
+        "ip_prefix": "10.100.0.0/24",
+        "persistent_keepalive": 25,
+        "delete": [],
+        "redistribute": []
+      }
+    }
+  ],
+  "tips": [
+    "The 'delete' and 'redistribute' params are marked required in the spec even when empty — always pass them as empty arrays if not removing/adding entries.",
+    "After updating a fabric, call POST /cluster/sdn (apply) to push the config to all nodes; without apply the change is staged but not active.",
+    "Pass 'digest' (retrieved from GET /cluster/sdn/fabrics/fabric/{id}) to guard against concurrent modifications in multi-admin environments.",
+    "Protocol-specific params only apply to their respective protocol: 'area' and 'redistribute' for OSPF/Openfabric, 'csnp_interval'/'hello_interval' for Openfabric, 'persistent_keepalive' for WireGuard.",
+    "The 'lock-token' param is only needed when the global SDN config is locked by another operation — typically not required for normal updates."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_fabrics_fabric_id",
+    "post_cluster_sdn_fabrics",
+    "delete_cluster_sdn_fabrics_fabric_id",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "put_cluster_sdn_fabrics_node_fabric_id_node_id",
+  "usageNotes": "Use this to update an existing node's configuration within an SDN fabric — for example, changing its IP address, WireGuard endpoint, allowed CIDRs, or role. Requires both SDN.Allocate on the fabric path and Sys.Modify on the target node; both privileges must be satisfied simultaneously. The 'protocol' field is required on every update call and must match the fabric's protocol type — sending a mismatched protocol will be rejected.",
+  "examples": [
+    {
+      "summary": "Update a WireGuard fabric node's allowed IPs and endpoint",
+      "path_params": {
+        "fabric_id": "wg-core",
+        "node_id": "pve02"
+      },
+      "params": {
+        "protocol": "wireguard",
+        "role": "internal",
+        "ip": "10.10.1.2",
+        "allowed_ips": ["10.10.1.0/24", "192.168.50.0/24"],
+        "endpoint": "203.0.113.45:51820",
+        "delete": [],
+        "interfaces": ["vmbr0"]
+      }
+    }
+  ],
+  "tips": [
+    "Pass the 'digest' from the current node config to guard against concurrent edits overwriting each other.",
+    "The 'delete' and 'interfaces' arrays are marked required in the spec — even when making no changes to those fields, pass empty arrays rather than omitting them.",
+    "For external WireGuard nodes, 'public_key' and 'endpoint' are typically both needed; internal nodes rely on auto-exchanged keys from the cluster.",
+    "Changes to SDN fabric nodes take effect only after running the SDN apply step (PUT /cluster/sdn/fabrics/{fabric_id}/apply or equivalent reload)."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_fabrics_node_fabric_id_node_id",
+    "delete_cluster_sdn_fabrics_node_fabric_id_node_id",
+    "get_cluster_sdn_fabrics_fabric_id",
+    "put_cluster_sdn_fabrics_fabric_id"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_cluster_sdn_ipams_ipam",
+  "usageNotes": "Use this to update an existing SDN IPAM object's configuration (URL, API token, TLS fingerprint, etc.) without recreating it. Requires the SDN.Allocate privilege on /sdn/ipams. Pass the current config digest to guard against concurrent edits; omit fields you are not changing and use the 'delete' param to explicitly remove optional settings.",
+  "examples": [
+    {
+      "summary": "Update a phpIPAM integration's URL and API token",
+      "path_params": {
+        "ipam": "phpipam1"
+      },
+      "params": {
+        "url": "https://ipam.example.com",
+        "token": "myApiToken123",
+        "digest": "a3f1c2e4b5d6a7f8e9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
+      }
+    }
+  ],
+  "tips": [
+    "The endpoint returns null on success; confirm the update by reading the object with get_cluster_sdn_ipams_ipam.",
+    "Use the 'delete' param (comma-separated config key names) to unset optional fields like 'fingerprint' rather than sending an empty string.",
+    "After updating IPAM config, apply the pending SDN configuration via put_cluster_sdn_reload so changes take effect cluster-wide.",
+    "The 'lock-token' param is only needed if another SDN operation holds a global config lock; normal updates can omit it."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_ipams_ipam",
+    "get_cluster_sdn_ipams",
+    "post_cluster_sdn_ipams",
+    "delete_cluster_sdn_ipams_ipam",
+    "put_cluster_sdn_reload"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_cluster_sdn_prefix_lists_id",
+  "usageNotes": "Use this endpoint to update an existing SDN prefix list's entries or remove specific entries — for example, to add or prune CIDR prefixes used in BGP route filtering or firewall policy. Requires the SDN.Allocate privilege on the specific prefix-list path. Always supply the current `digest` in concurrent environments to prevent overwriting another operator's changes; after updating, apply the SDN configuration via the reload endpoint for changes to take effect.",
+  "examples": [
+    {
+      "summary": "Add a new CIDR entry to an existing prefix list",
+      "path_params": {
+        "id": "rfc1918-prefixes"
+      },
+      "params": {
+        "entries": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
+        "digest": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
+      }
+    }
+  ],
+  "tips": [
+    "After updating a prefix list, run the SDN apply/reload operation (POST /cluster/sdn) to push changes to all cluster nodes; the PUT alone does not activate changes.",
+    "Use the `delete` param to remove specific entries by name/key rather than resubmitting the full list.",
+    "The `lock-token` param is only needed when the SDN global config is locked by another operation; normal updates do not require it.",
+    "Prefix list IDs follow the pve-sdn-prefix-list-id format — typically lowercase alphanumeric with hyphens."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_prefix_lists_id",
+    "get_cluster_sdn_prefix_lists",
+    "post_cluster_sdn_prefix_lists",
+    "delete_cluster_sdn_prefix_lists_id",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_sdn_prefix_lists_id_entries_url_seq",
+  "usageNotes": "Use this to modify an existing entry within a named SDN prefix list — changing its CIDR prefix, permit/deny action, or prefix-length range constraints (ge/le). The caller must hold SDN.Allocate on the specific prefix-list path; changes do not take effect cluster-wide until the SDN configuration is applied (reload). Use the digest parameter when making concurrent-safe updates to avoid overwriting another process's changes.",
+  "examples": [
+    {
+      "summary": "Update entry seq 10 in prefix-list 'rfc1918' to permit with a le constraint of 28",
+      "path_params": {
+        "id": "rfc1918",
+        "url_seq": "10"
+      },
+      "params": {
+        "action": "permit",
+        "prefix": "10.0.0.0/8",
+        "le": 28,
+        "seq": 10
+      }
+    }
+  ],
+  "tips": [
+    "ge and le set inclusive prefix-length bounds for more-specific match ranges (e.g., ge=24 le=28 matches /24 through /28 within the base prefix).",
+    "The 'delete' array can be used to unset optional fields (such as ge or le) on the entry without recreating it.",
+    "After updating, call the SDN apply endpoint to push the revised prefix-list to all nodes.",
+    "Obtain the current digest via GET on the entry or parent prefix-list before writing to enable optimistic concurrency control."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_prefix_lists_id_entries_url_seq",
+    "get_cluster_sdn_prefix_lists_id_entries",
+    "post_cluster_sdn_prefix_lists_id_entries",
+    "delete_cluster_sdn_prefix_lists_id_entries_url_seq",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_cluster_sdn_route_maps_entries_route_map_id_entry_order",
+  "usageNotes": "Updates an existing entry within an SDN route map, identified by its zero-based order index. Use this to change the matching policy (permit/deny), add or modify match conditions and set actions, or chain to another route map via the 'call' field. SDN changes made here are staged and require a subsequent apply (POST /cluster/sdn) to take effect in the data plane; requires SDN.Allocate on the specific route-map path.",
+  "examples": [
+    {
+      "summary": "Change entry 10 of route map 'rm-upstream' to deny, with an on-match-next exit action",
+      "path_params": {
+        "route-map-id": "rm-upstream",
+        "order": 10
+      },
+      "params": {
+        "action": "deny",
+        "exit-action": "on-match-next"
+      }
+    }
+  ],
+  "tips": [
+    "Supply the 'digest' param (from the GET response) to guard against concurrent edits overwriting each other.",
+    "The 'order' path param is the current index of the entry — it does not reorder the entry; use it only to target which entry to modify.",
+    "Use the 'delete' array to remove specific sub-fields (e.g. a match condition) without replacing the whole entry.",
+    "The 'call' field delegates to a second route map mid-evaluation; the called map runs and returns control to the next entry in the calling map.",
+    "After updating entries, run POST /cluster/sdn to apply the pending configuration to all SDN nodes."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_route_maps_entries_route_map_id_entry_order",
+    "post_cluster_sdn_route_maps_entries_route_map_id",
+    "delete_cluster_sdn_route_maps_entries_route_map_id_entry_order",
+    "get_cluster_sdn_route_maps_entries_route_map_id",
+    "post_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_cluster_sdn_vnets_vnet",
+  "usageNotes": "Use this to modify an existing SDN VNet's properties such as its VLAN/VXLAN tag, zone assignment, alias, or port-isolation setting. Requires 'SDN.Allocate' on '/sdn/zones/<zone>/<vnet>'; changes are staged and must be applied via POST /cluster/sdn/reload (or the Proxmox UI 'Apply' button) before taking effect on the data plane. Use the 'digest' parameter when making changes programmatically to guard against concurrent edits clobbering each other.",
+  "examples": [
+    {
+      "summary": "Reassign a VNet to a new VXLAN tag and enable VLAN-awareness",
+      "path_params": {
+        "vnet": "prodvnet1"
+      },
+      "params": {
+        "tag": 10200,
+        "vlanaware": true,
+        "alias": "Production Segment 1"
+      }
+    }
+  ],
+  "tips": [
+    "Changes are not live until the SDN configuration is explicitly applied (POST /cluster/sdn/reload); plan for a brief propagation window.",
+    "To clear an optional field (e.g., alias), include its name in the 'delete' param as a comma-separated config-id list rather than passing an empty string.",
+    "The 'isolate-ports' flag affects all VM interfaces attached to this VNet's bridge — use with care on shared-bridge zones.",
+    "The 'vnet' identifier is immutable after creation; to rename, delete and recreate with get_cluster_sdn_vnets + delete_cluster_sdn_vnets_vnet + post_cluster_sdn_vnets."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet",
+    "post_cluster_sdn_vnets",
+    "delete_cluster_sdn_vnets_vnet",
+    "get_cluster_sdn_vnets",
+    "put_cluster_sdn"
+  ]
+}