@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_notifications_endpoints_gotify",
+  "usageNotes": "Use this to register a Gotify push-notification server as a cluster-level notification endpoint; the endpoint can then be referenced in notification matchers to route alerts. The caller must hold Mapping.Modify on /mapping/notifications and either Sys.Modify (or Sys.Audit) or Sys.AccessNetwork on /. The name field must be a valid pve-configid (alphanumeric plus hyphens, no spaces), and the token is the Gotify application token — store it securely as it is sent in plaintext to the API.",
+  "examples": [
+    {
+      "summary": "Register a self-hosted Gotify server for cluster alert delivery",
+      "path_params": {},
+      "params": {
+        "name": "gotify-alerts",
+        "server": "https://gotify.nightsquawk.tech",
+        "token": "AbCdEfGhIjKlMnOp1234",
+        "comment": "Primary Gotify endpoint for Proxmox cluster alerts",
+        "disable": false
+      }
+    }
+  ],
+  "tips": [
+    "The endpoint name must satisfy pve-configid format — use only lowercase letters, digits, and hyphens; no underscores or spaces.",
+    "After creation, verify delivery by triggering a test notification via the Proxmox web UI under Datacenter > Notifications.",
+    "Set disable: true if you want to pre-register the endpoint without activating it in any matcher yet.",
+    "The Gotify application token must be created in the Gotify UI under Applications before registering the endpoint here."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_gotify",
+    "get_cluster_notifications_endpoints_gotify_name",
+    "put_cluster_notifications_endpoints_gotify_name",
+    "delete_cluster_notifications_endpoints_gotify_name",
+    "post_cluster_notifications_matchers",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_notifications_endpoints_sendmail",
+  "usageNotes": "Use this to register a new sendmail endpoint in the cluster notification system so that alerts and notification rules can route email via the local sendmail binary. At least one of 'mailto' (explicit email addresses) or 'mailto-user' (Proxmox user accounts) must be provided to make the endpoint useful; an endpoint with neither will accept no mail. Requires 'Mapping.Modify' on '/mapping/notifications' plus either 'Sys.Audit'/'Sys.Modify' or 'Sys.AccessNetwork' at the root level.",
+  "examples": [
+    {
+      "summary": "Create a sendmail endpoint that routes cluster alerts to an admin address",
+      "path_params": {},
+      "params": {
+        "name": "admin-alerts",
+        "author": "NightSquawk Tech Alerts",
+        "from-address": "proxmox-alerts@nightsquawk.tech",
+        "mailto": ["hello@nightsquawk.tech"],
+        "comment": "Primary alert endpoint for cluster health notifications",
+        "disable": false
+      }
+    }
+  ],
+  "tips": [
+    "The 'name' field must satisfy the 'pve-configid' format: alphanumeric plus hyphens/underscores, no spaces.",
+    "sendmail relies on the local MTA (Postfix by default on PVE nodes); ensure the MTA is configured and able to relay before testing this endpoint.",
+    "After creation, wire this endpoint to a notification rule via the matchers/policies API — creating the endpoint alone does not cause any notifications to be sent.",
+    "To update an existing endpoint use PUT /cluster/notifications/endpoints/sendmail/{name} instead of re-POSTing; duplicate names return an error.",
+    "The 'disable' flag lets you temporarily silence an endpoint without deleting its references in notification rules."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_sendmail",
+    "get_cluster_notifications_endpoints_sendmail_name",
+    "put_cluster_notifications_endpoints_sendmail_name",
+    "delete_cluster_notifications_endpoints_sendmail_name",
+    "post_cluster_notifications_matchers",
+    "get_cluster_notifications_endpoints"
+  ]
+}

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

@@ -0,0 +1,38 @@
+{
+  "operationId": "post_cluster_notifications_endpoints_smtp",
+  "usageNotes": "Use this to register a new SMTP notification endpoint in the cluster-wide notification system, which can then be referenced by notification matchers to route alerts via email. The caller must hold Mapping.Modify on /mapping/notifications plus either Sys.Modify or Sys.AccessNetwork on /. At least one of `mailto` or `mailto-user` should be provided alongside the three required fields (name, server, from-address), otherwise the endpoint is valid but will silently deliver to no one.",
+  "examples": [
+    {
+      "summary": "Create a TLS SMTP endpoint using a transactional mail service (e.g., SendGrid) with two alert recipients",
+      "path_params": {},
+      "params": {
+        "name": "alerts-sendgrid",
+        "server": "smtp.sendgrid.net",
+        "port": 465,
+        "mode": "tls",
+        "from-address": "proxmox-alerts@nightsquawk.tech",
+        "author": "Proxmox Alerts",
+        "username": "apikey",
+        "password": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "mailto": ["hello@nightsquawk.tech", "oncall@nightsquawk.tech"],
+        "comment": "Primary alert relay via SendGrid"
+      }
+    }
+  ],
+  "tips": [
+    "The `name` field uses pve-configid format: lowercase alphanumeric and hyphens only, no spaces.",
+    "Port defaults are applied automatically (465 for tls, 587 for starttls, 25 for insecure) — omit `port` unless overriding.",
+    "An endpoint created with `disable: true` is stored but ignored by matchers until re-enabled via the PUT endpoint.",
+    "Passwords are write-only in the API; a subsequent GET will not return the stored credential.",
+    "`mailto-user` accepts Proxmox user IDs (e.g., root@pam) and resolves their configured email at send time, so it stays accurate if the user's address changes.",
+    "After creation, wire the endpoint into a notification matcher using the notification matcher POST/PUT endpoints so it actually receives alerts."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_smtp",
+    "get_cluster_notifications_endpoints_smtp_name",
+    "put_cluster_notifications_endpoints_smtp_name",
+    "delete_cluster_notifications_endpoints_smtp_name",
+    "post_cluster_notifications_matchers",
+    "get_cluster_notifications_endpoints"
+  ]
+}

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

@@ -0,0 +1,40 @@
+{
+  "operationId": "post_cluster_notifications_endpoints_webhook",
+  "usageNotes": "Use this to register a new webhook endpoint in the cluster notification system so Proxmox can push alerts (backups, HA events, etc.) to an external HTTP receiver. Requires `Mapping.Modify` on `/mapping/notifications` plus either `Sys.Audit`+`Sys.Modify` or `Sys.AccessNetwork` on `/`. Both the `body` and `header` values must be base64-encoded; secrets follow the same property-string format (`name=<name>,value=<base64>`) and are stored encrypted server-side.",
+  "examples": [
+    {
+      "summary": "Create a webhook that POSTs JSON alerts with an Authorization header and a Bearer token secret",
+      "path_params": {},
+      "params": {
+        "name": "ops-alertmanager",
+        "url": "https://alerts.example.com/hooks/proxmox",
+        "method": "post",
+        "body": "eyJldmVudCI6IHt7dGl0bGV9fX0=",
+        "header": [
+          "name=Content-Type,value=YXBwbGljYXRpb24vanNvbg==",
+          "name=Authorization,value=QmVhcmVyIHt7c2VjcmV0LnRva2VufX0="
+        ],
+        "secret": [
+          "name=token,value=bXlzdXBlcnNlY3JldHRva2Vu"
+        ],
+        "comment": "Alertmanager webhook for cluster notifications",
+        "disable": false
+      }
+    }
+  ],
+  "tips": [
+    "All `value` fields in `header` and `secret` entries must be base64-encoded; plain text will be rejected or misinterpreted.",
+    "Webhook names must follow the `pve-configid` format: alphanumeric plus hyphens, no spaces, max 64 chars.",
+    "Use template variables like `{{title}}` or `{{secret.mykey}}` inside the base64-encoded `body` to inject notification content or secrets at delivery time.",
+    "Create the endpoint in `disable: true` state first to validate config before enabling it in production.",
+    "After creation, wire this endpoint to a notification matcher via `post_cluster_notifications_matchers` so it actually receives events."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_webhook",
+    "get_cluster_notifications_endpoints_webhook_name",
+    "put_cluster_notifications_endpoints_webhook_name",
+    "delete_cluster_notifications_endpoints_webhook_name",
+    "post_cluster_notifications_matchers",
+    "get_cluster_notifications_endpoints"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_notifications_matchers",
+  "usageNotes": "Use this to create a named notification matcher that filters which events reach which notification targets (e.g. email, Gotify). The `name` field must follow the `pve-configid` format (alphanumeric plus hyphens, no spaces). Matchers are purely additive — no target receives notifications until a matcher explicitly references it via the `target` array.",
+  "examples": [
+    {
+      "summary": "Create a matcher that routes critical-severity backup-job failures to an email target, active only on business-hours calendar",
+      "path_params": {},
+      "params": {
+        "name": "backup-critical-alerts",
+        "comment": "Route critical backup failures to on-call email during business hours",
+        "match-severity": ["critical"],
+        "match-field": ["regex:type=vzdump"],
+        "match-calendar": ["mon..fri 08:00-18:00"],
+        "mode": "all",
+        "target": ["email-oncall"],
+        "disable": false
+      }
+    }
+  ],
+  "tips": [
+    "The `match-field` values must be prefixed with `exact:` or `regex:` followed by `<field>=<value>` — omitting the prefix causes a validation error.",
+    "Setting `mode` to `any` means the matcher fires if ANY condition matches; the default `all` requires every condition to match simultaneously.",
+    "Use `invert-match: true` to build exclusion rules (e.g., suppress low-severity noise during maintenance windows).",
+    "Matchers are evaluated cluster-wide; changes take effect immediately without a service restart.",
+    "After creation, retrieve the matcher with GET /cluster/notifications/matchers/{name} to confirm the stored configuration."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers",
+    "get_cluster_notifications_matchers_name",
+    "put_cluster_notifications_matchers_name",
+    "delete_cluster_notifications_matchers_name",
+    "get_cluster_notifications_targets",
+    "post_cluster_notifications_targets_sendmail"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_cluster_notifications_targets_name_test",
+  "usageNotes": "Use this to verify a notification target is reachable and correctly configured before relying on it for alerts. The caller must hold at least Mapping.Audit, Mapping.Use, or Mapping.Modify on /mapping/notifications. The endpoint returns null synchronously — a missing error response indicates success, while an HTTP error body describes the delivery failure.",
+  "examples": [
+    {
+      "summary": "Send a test notification to the 'ops-slack' target",
+      "path_params": {
+        "name": "ops-slack"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The target name must match a pve-configid (alphanumeric, hyphens, underscores; no spaces) — use get_cluster_notifications_targets to list valid names.",
+    "A 200 response with null body means the test message was dispatched; verify delivery on the receiving end (email inbox, webhook log, etc.) since PVE does not confirm downstream receipt.",
+    "If the target's back-end service (SMTP relay, Gotify, webhook URL) is temporarily unreachable, this call will return an error — useful for pre-maintenance smoke tests."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_targets",
+    "get_cluster_notifications_targets_name",
+    "post_cluster_notifications_targets_gotify",
+    "post_cluster_notifications_targets_sendmail",
+    "post_cluster_notifications_targets_smtp",
+    "post_cluster_notifications_targets_webhook"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_qemu_custom_cpu_models",
+  "usageNotes": "Use this to define a cluster-wide custom CPU model that VMs can reference by name, allowing you to lock in a specific CPU baseline with additional feature flags independent of host CPU changes. Requires the `Mapping.Modify` privilege on `/mapping/cpu`. The `cputype` name is stored without the `custom-` prefix internally, but VMs reference it as `custom-<name>`; omit the prefix when calling this endpoint and Proxmox will normalize it.",
+  "examples": [
+    {
+      "summary": "Create a hardened Skylake-Server custom CPU model with security mitigations enabled",
+      "path_params": {},
+      "params": {
+        "cputype": "skylake-hardened",
+        "reported-model": "Skylake-Server-IBRS",
+        "flags": "+spec-ctrl;+ssbd;+md-clear;+ibpb",
+        "hidden": false,
+        "phys-bits": "host"
+      }
+    }
+  ],
+  "tips": [
+    "The `cputype` value must conform to pve-configid format (alphanumeric plus hyphens/underscores, max 40 chars); keep names short since VMs will reference them as `custom-<name>`.",
+    "Setting `phys-bits` to `host` improves performance but breaks live migration to hosts with different physical address bit widths — use an explicit numeric value for migrateable VMs.",
+    "Setting `level` to 30 is a well-known workaround for Hyper-V boot failures on Windows guests running on recent Intel hosts.",
+    "The `hidden` flag suppresses KVM identification and can help with guest software that behaves differently in virtualized environments, but only affects x86-64 vCPUs.",
+    "Flags prefixed with `+` enable a feature; `-` disables it. The special alias `nested-virt` maps to `svm` (AMD) or `vmx` (Intel) automatically.",
+    "This endpoint returns null on success — validate creation by calling GET /cluster/qemu/custom-cpu-models afterward."
+  ],
+  "relatedOperations": [
+    "get_cluster_qemu_custom_cpu_models",
+    "get_cluster_qemu_custom_cpu_models_cputype",
+    "put_cluster_qemu_custom_cpu_models_cputype",
+    "delete_cluster_qemu_custom_cpu_models_cputype"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_replication",
+  "usageNotes": "Use this to configure continuous ZFS-based replication of a VM or container to another cluster node, providing a warm standby for failover. The `id` must follow the `<VMID>-<JOBNUM>` pattern (e.g., `100-0`), the target node must be online and reachable within the cluster, and the caller must hold `VM.Replicate` on `/vms/<vmid>`. The operation returns null synchronously — replication runs are triggered by the scheduler and can be monitored via the replication status endpoints.",
+  "examples": [
+    {
+      "summary": "Replicate VM 100 to node pve2 every 15 minutes with a rate cap",
+      "path_params": {},
+      "params": {
+        "id": "100-0",
+        "target": "pve2",
+        "type": "local",
+        "schedule": "*/15",
+        "rate": 50,
+        "comment": "HA warm standby for VM 100"
+      }
+    }
+  ],
+  "tips": [
+    "The `type` field only accepts 'local', meaning replication is within the same Proxmox cluster (not cross-cluster).",
+    "Replication requires shared or ZFS storage; VMs on non-replicated storage types (e.g., directory-backed) will fail at runtime.",
+    "The default schedule '*/15' means every 15 minutes; use systemd calendar syntax for custom intervals (e.g., 'hourly', '00:00', '*/5').",
+    "Avoid setting `remove_job` on creation — it is intended for cleanup of existing jobs and will immediately mark the new job for deletion.",
+    "Use `get_cluster_replication` to verify the job was created and `get_cluster_replication_id` to inspect a specific job's config."
+  ],
+  "relatedOperations": [
+    "get_cluster_replication",
+    "get_cluster_replication_id",
+    "put_cluster_replication_id",
+    "delete_cluster_replication_id"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_sdn_controllers",
+  "usageNotes": "Use this to register a new SDN controller (BGP, EVPN, IS-IS, or Faucet) in the cluster-wide SDN configuration. The caller must hold SDN.Allocate on /sdn/controllers. After creating the controller object, you must call PUT /cluster/sdn to apply the pending configuration to all nodes before any networking change takes effect.",
+  "examples": [
+    {
+      "summary": "Create an EVPN controller with a local AS and two BGP peer addresses",
+      "path_params": {},
+      "params": {
+        "controller": "evpn-dc1",
+        "type": "evpn",
+        "asn": 65001,
+        "peers": "10.0.0.1,10.0.0.2",
+        "bgp-mode": "internal",
+        "loopback": "lo",
+        "nodes": "pve01,pve02,pve03"
+      }
+    }
+  ],
+  "tips": [
+    "The controller name must match the pattern [a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9] (2–64 chars) and is immutable after creation — delete and recreate to rename.",
+    "After POST, the SDN config is only staged; issue PUT /cluster/sdn (apply) to push changes to node network interfaces.",
+    "IS-IS controllers require a correctly formatted isis-net (NSAP address) and at least one interface in isis-ifaces; omitting either causes apply to fail.",
+    "For EVPN, the 'peers' field should list the loopback IPs of all other EVPN nodes so FRR can establish BGP EVPN sessions.",
+    "The lock-token param is only needed when an earlier SDN operation left the config locked; obtain it from the SDN status before retrying."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_controllers",
+    "get_cluster_sdn_controllers_controller",
+    "put_cluster_sdn_controllers_controller",
+    "delete_cluster_sdn_controllers_controller",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_cluster_sdn_dns",
+  "usageNotes": "Use this to register a new SDN DNS integration object (currently only PowerDNS is supported), which allows Proxmox SDN to dynamically create and remove DNS records for VMs and networks. The caller must hold the SDN.Allocate privilege on /sdn/dns, and the SDN configuration must subsequently be applied via PUT /cluster/sdn to take effect. The key field is the PowerDNS API key; if the PowerDNS endpoint uses a self-signed certificate, supply its SHA-256 fingerprint via the fingerprint field.",
+  "examples": [
+    {
+      "summary": "Register a PowerDNS integration for SDN automatic DNS record management",
+      "path_params": {},
+      "params": {
+        "dns": "pdns01",
+        "type": "powerdns",
+        "url": "http://10.0.0.10:8081",
+        "key": "supersecretapikey123",
+        "ttl": 300
+      }
+    }
+  ],
+  "tips": [
+    "After creating the DNS object, run PUT /cluster/sdn (apply) to push the new configuration to all nodes — the object is not active until applied.",
+    "The dns identifier must start with a letter, end with a letter or digit, and contain only alphanumeric characters (no hyphens/underscores).",
+    "reversemaskv6 and reversev6mask are alternative fields for IPv6 reverse-zone prefix length; check your PowerDNS version for which field is expected.",
+    "The fingerprint field uses the colon-delimited SHA-256 format (AA:BB:...) and is only needed when the PowerDNS API URL uses HTTPS with a self-signed or private-CA certificate."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_dns",
+    "get_cluster_sdn_dns_dns",
+    "put_cluster_sdn_dns_dns",
+    "delete_cluster_sdn_dns_dns",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_sdn_fabrics_fabric",
+  "usageNotes": "Use this to define a new SDN fabric — the routing/overlay protocol backbone (OpenFabric, OSPF, WireGuard, or BGP) that interconnects Proxmox cluster nodes. Requires the SDN.Allocate privilege on /sdn/fabrics. After creating a fabric, you must apply the SDN configuration (PUT /cluster/sdn) for changes to take effect on nodes.",
+  "examples": [
+    {
+      "summary": "Create a WireGuard fabric with a persistent keepalive and an IPv4 node prefix",
+      "path_params": {},
+      "params": {
+        "id": "wg-core",
+        "protocol": "wireguard",
+        "redistribute": [],
+        "ip_prefix": "10.10.0.0/24",
+        "persistent_keepalive": 25
+      }
+    }
+  ],
+  "tips": [
+    "The 'id' field must be 2–8 alphanumeric characters (hyphens allowed in the middle); it cannot be changed after creation.",
+    "For OSPF fabrics, 'area' accepts either a dotted-quad IPv4 address (e.g. 0.0.0.0) or a plain 32-bit integer.",
+    "The 'redistribute' array is required but can be an empty array if no route redistribution is needed.",
+    "Use 'digest' to guard against concurrent writes when multiple operators may modify SDN config simultaneously.",
+    "After adding a fabric, call PUT /cluster/sdn to push the configuration to all cluster nodes; nodes will not use the new fabric until that apply step completes."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_fabrics",
+    "get_cluster_sdn_fabrics_fabric",
+    "put_cluster_sdn_fabrics_fabric",
+    "delete_cluster_sdn_fabrics_fabric",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_cluster_sdn_fabrics_node_fabric_id",
+  "usageNotes": "Adds a Proxmox node (or an external peer) to an existing SDN fabric. The fabric must already exist and the caller needs SDN.Allocate on /sdn/fabrics/{fabric_id} plus Sys.Modify on /nodes/{node_id}. Protocol-specific fields apply: 'wireguard' uses allowed_ips, endpoint, public_key, and role; routing protocols (ospf, openfabric, bgp) primarily use interfaces and ip/ip6. After adding nodes, apply the pending SDN configuration via PUT /cluster/sdn to push changes cluster-wide.",
+  "examples": [
+    {
+      "summary": "Add a WireGuard peer node to fabric 'wgfab1'",
+      "path_params": {
+        "fabric_id": "wgfab1"
+      },
+      "params": {
+        "node_id": "pve2",
+        "protocol": "wireguard",
+        "interfaces": ["wg0"],
+        "ip": "10.10.10.2",
+        "allowed_ips": ["10.20.0.0/24"],
+        "endpoint": "203.0.113.55:51820",
+        "role": "internal"
+      }
+    }
+  ],
+  "tips": [
+    "fabric_id must be 2–8 alphanumeric characters with optional interior hyphens; it cannot start or end with a hyphen.",
+    "For WireGuard external nodes, supply public_key — it is required for peers outside the Proxmox cluster.",
+    "Use the digest param (obtained from GET /cluster/sdn/fabrics/{fabric_id}) to guard against concurrent SDN config edits.",
+    "Returns null on success — confirm the node was added by fetching GET /cluster/sdn/fabrics/node/{fabric_id}.",
+    "Changes are staged; run PUT /cluster/sdn afterward to apply and propagate the updated configuration across all nodes."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_fabrics_node_fabric_id",
+    "put_cluster_sdn_fabrics_node_fabric_id",
+    "delete_cluster_sdn_fabrics_node_fabric_id",
+    "get_cluster_sdn_fabrics_fabric_id",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_cluster_sdn_ipams",
+  "usageNotes": "Creates a new SDN IPAM plugin registration in the cluster-wide SDN configuration; requires the SDN.Allocate privilege on /sdn/ipams. After creation, the SDN config must be applied via POST /cluster/sdn to push the change to all nodes. For external IPAM backends (netbox, phpipam), supply the url and token params; for the built-in pve type, no external URL is needed.",
+  "examples": [
+    {
+      "summary": "Register a NetBox instance as the cluster IPAM",
+      "path_params": {},
+      "params": {
+        "ipam": "netbox01",
+        "type": "netbox",
+        "url": "https://netbox.example.com",
+        "token": "Token abc123def456abc123def456abc123def456abcd"
+      }
+    }
+  ],
+  "tips": [
+    "The ipam identifier must start and end with a letter or digit (pattern: [a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]) and be at least 2 characters.",
+    "For the built-in 'pve' type, url and token are not required; Proxmox manages IP allocations internally.",
+    "For phpipam, supply the certificate SHA-256 fingerprint via 'fingerprint' if the server uses a self-signed cert.",
+    "Returns null on success — use GET /cluster/sdn/ipams to confirm the object was created.",
+    "SDN changes are staged; always follow up with POST /cluster/sdn (apply) to activate the new IPAM across the cluster."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_ipams",
+    "get_cluster_sdn_ipams_ipam",
+    "put_cluster_sdn_ipams_ipam",
+    "delete_cluster_sdn_ipams_ipam",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_cluster_sdn_lock",
+  "usageNotes": "Acquires a cluster-wide exclusive lock before making SDN configuration changes; any subsequent apply or edit operation requires this lock to succeed first. The caller must hold the SDN.Allocate privilege on /sdn. By default the lock will be denied if there are already pending (unapplied) SDN changes — pass allow-pending: true only when you intentionally want to layer additional changes on top of an existing pending diff.",
+  "examples": [
+    {
+      "summary": "Acquire SDN lock before editing zone/VNET configuration",
+      "path_params": {},
+      "params": {
+        "allow-pending": false
+      }
+    }
+  ],
+  "tips": [
+    "The returned string is a lock token or confirmation value — retain it for debugging; the lock is cluster-scoped so concurrent SDN edits from other sessions will block until it is released.",
+    "Always pair this call with the corresponding unlock or apply operation to avoid leaving the SDN config locked and blocking other administrators.",
+    "Use allow-pending: true with caution in automation — it means you may apply a config that includes changes from a prior, unreviewed session."
+  ],
+  "relatedOperations": [
+    "delete_cluster_sdn_lock",
+    "put_cluster_sdn",
+    "post_cluster_sdn_reload",
+    "get_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_cluster_sdn_prefix_lists",
+  "usageNotes": "Creates a named SDN prefix list that can be referenced by BGP route-map filters or firewall rules to match sets of IP prefixes. Requires the SDN.Allocate privilege on /sdn/prefix-lists. Changes to SDN configuration are staged until applied with the SDN apply operation; the prefix list is not active in the data plane until that apply is run.",
+  "examples": [
+    {
+      "summary": "Create a prefix list for RFC 1918 private address space",
+      "path_params": {},
+      "params": {
+        "id": "rfc1918-private",
+        "entries": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
+      }
+    }
+  ],
+  "tips": [
+    "The id must conform to the pve-sdn-prefix-list-id format — use lowercase alphanumeric characters and hyphens only.",
+    "Supply the current config digest to guard against concurrent edits overwriting each other.",
+    "After creating the prefix list, run the SDN apply operation (POST /cluster/sdn) to push the change to all nodes.",
+    "The lock-token param is only needed when you hold an explicit SDN config lock; omit it for normal single-operation writes."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_prefix_lists",
+    "get_cluster_sdn_prefix_lists_prefix_list",
+    "put_cluster_sdn_prefix_lists_prefix_list",
+    "delete_cluster_sdn_prefix_lists_prefix_list",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_sdn_prefix_lists_id_entries",
+  "usageNotes": "Adds a permit or deny entry for a CIDR prefix to an existing SDN prefix list, which is used by SDN firewall or routing policies to match traffic. The prefix list must already exist (create it first with the prefix list create endpoint), and the caller needs SDN.Allocate on /sdn/prefix-lists/{id}. Changes take effect cluster-wide only after the SDN configuration is applied (reload); use the lock-token if your workflow requires serialized concurrent edits.",
+  "examples": [
+    {
+      "summary": "Permit the 10.10.0.0/16 subnet with a ge/le range allowing /24 through /28 subnets",
+      "path_params": {
+        "id": "rfc1918-private"
+      },
+      "params": {
+        "action": "permit",
+        "prefix": "10.10.0.0/16",
+        "ge": 24,
+        "le": 28,
+        "seq": 10
+      }
+    }
+  ],
+  "tips": [
+    "seq controls match order within the list (lower = matched first); if omitted, Proxmox auto-assigns the next sequence number.",
+    "ge and le are prefix-length range qualifiers: ge sets the minimum prefix length and le sets the maximum, allowing one entry to match a block of more-specific subnets.",
+    "Returns null on success — no UPID is issued; the write is synchronous but the SDN config still needs a separate apply/reload step to propagate.",
+    "For IPv6 prefixes, ge/le values up to 128 are valid; for IPv4 practical maximum is 32."
+  ],
+  "relatedOperations": [
+    "post_cluster_sdn_prefix_lists",
+    "get_cluster_sdn_prefix_lists_id_entries",
+    "delete_cluster_sdn_prefix_lists_id_entries_id",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_cluster_sdn_rollback",
+  "usageNotes": "Use this to discard all pending (unapplied) SDN changes and revert the SDN configuration back to its last committed state. This is a synchronous operation that returns null on success, not a UPID task. If you hold the global SDN lock (e.g., from a failed apply attempt), pass the lock token via `lock-token` and set `release-lock` to true so the lock is cleared in a single call.",
+  "examples": [
+    {
+      "summary": "Rollback pending SDN changes and release a held lock in one call",
+      "path_params": {},
+      "params": {
+        "lock-token": "sdn-lock-abc123xyz",
+        "release-lock": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently discards all pending SDN configuration changes that have not yet been applied, making them unrecoverable.",
+  "tips": [
+    "The SDN.Allocate privilege on /sdn is required; ensure your API token or user has this permission.",
+    "If no lock is held, both lock-token and release-lock can be omitted — the endpoint will still rollback pending changes.",
+    "After rollback, verify the current committed state with GET /cluster/sdn before making new changes.",
+    "This is commonly used as a recovery step when a prior apply (POST /cluster/sdn) failed and left the configuration in a dirty state."
+  ],
+  "relatedOperations": [
+    "post_cluster_sdn",
+    "get_cluster_sdn",
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_zones"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_cluster_sdn_route_maps_entries",
+  "usageNotes": "Use this to add a numbered entry (sequence) to an existing SDN route map, which controls BGP/EVPN prefix filtering and attribute modification in Proxmox SDN. The parent route map must already exist (create it first via the route-maps endpoint), and the caller requires the SDN.Allocate privilege on /sdn/route-maps. After creating entries, apply the pending SDN configuration with the cluster SDN apply endpoint for changes to take effect.",
+  "examples": [
+    {
+      "summary": "Add a permit entry at order 10 to the 'mgmt-filter' route map, jumping to the next entry on match",
+      "path_params": {},
+      "params": {
+        "route-map-id": "mgmt-filter",
+        "order": 10,
+        "action": "permit",
+        "exit-action": "on-match-next",
+        "match": ["prefix 10.10.0.0/16 le 24"],
+        "set": ["local-preference 150"]
+      }
+    }
+  ],
+  "tips": [
+    "The 'order' field determines evaluation sequence; lower values are evaluated first. Leave gaps (e.g. 10, 20, 30) to allow future insertions without renumbering.",
+    "Use 'call' to invoke a secondary route map as a subroutine before the current entry's action is applied.",
+    "Use 'exit-action' with 'on-match-goto' and a target order index to implement non-sequential route map logic (policy-based jumps).",
+    "The 'digest' parameter should be passed from a prior GET of the route map to prevent overwriting concurrent edits.",
+    "The 'lock-token' is required when the global SDN configuration is locked for staged editing; omit it for direct single-operation writes.",
+    "Changes are pending until you POST to /cluster/sdn to apply the SDN configuration cluster-wide."
+  ],
+  "relatedOperations": [
+    "post_cluster_sdn_route_maps",
+    "get_cluster_sdn_route_maps_entries",
+    "put_cluster_sdn_route_maps_entries_entry",
+    "delete_cluster_sdn_route_maps_entries_entry",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_cluster_sdn_vnets",
+  "usageNotes": "Use this to create a new SDN VNet object within an existing SDN zone. The caller must hold SDN.Allocate on the target zone (/sdn/zones/{zone}). After creation, the new VNet does not take effect on cluster nodes until you apply the pending SDN configuration via PUT /cluster/sdn; VMs will not see the network until that apply step completes.",
+  "examples": [
+    {
+      "summary": "Create a VXLAN-backed VNet named 'prodnet' in the 'evpnzone' zone with a VXLAN VNI of 10001",
+      "path_params": {},
+      "params": {
+        "vnet": "prodnet",
+        "zone": "evpnzone",
+        "tag": 10001,
+        "alias": "Production Network",
+        "vlanaware": false
+      }
+    }
+  ],
+  "tips": [
+    "The 'vnet' identifier must be 2–8 alphanumeric characters, start with a letter, and end with a letter or digit — plan names carefully since renaming requires delete and recreate.",
+    "Set 'vlanaware' to true only if VMs on this VNet need to trunk multiple VLANs across the bridge (e.g., for nested virtualisation or router-on-a-stick setups).",
+    "Enable 'isolate-ports' to prevent VM-to-VM traffic on the same bridge without going through a router, useful for zero-trust or tenant-isolation scenarios.",
+    "Changes are staged — always follow up with PUT /cluster/sdn to push the pending configuration to all nodes.",
+    "The lock-token parameter is only needed if you are coordinating concurrent SDN writes and have obtained a lock; most single-operator workflows can omit it."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_vnets_vnet",
+    "put_cluster_sdn_vnets_vnet",
+    "delete_cluster_sdn_vnets_vnet",
+    "put_cluster_sdn",
+    "get_cluster_sdn_zones"
+  ]
+}