@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pdm/enrichment/get_subscriptions_keys.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_subscriptions_keys",
+  "usageNotes": "Use this to audit the full subscription key pool managed by PDM — listing every key the caller has access to, along with its binding (remote/node), status, and level. Requires the `System.Audit` privilege; bound entries for remotes where the caller lacks `PRIV_RESOURCE_AUDIT` are silently hidden, so a partial result does not imply an incomplete pool. Check `pending-clear: true` entries to identify keys queued for unbinding that need an Apply or Discard Pending action.",
+  "examples": [
+    {
+      "summary": "List all subscription keys visible to the current token",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A missing `remote`/`node` on an entry means the key is unbound and available for assignment.",
+    "Keys with `status: expired` or `status: suspended` are still listed — filter client-side if you only want actionable keys.",
+    "The `check-time` field is an epoch timestamp; use it to detect stale data if a key has not been refreshed recently.",
+    "Entries with `pending-clear: true` have a queued unbind that has not been applied yet — either apply or discard the pending operation before reassigning the key.",
+    "API tokens are allowed (`allowtoken: true`), so a read-only audit token scoped to System.Audit is sufficient for this call."
+  ],
+  "relatedOperations": [
+    "add_subscriptions_keys",
+    "delete_subscriptions_key",
+    "get_subscriptions_keys_keyed"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_subscriptions_keys_key.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_subscriptions_keys_key",
+  "usageNotes": "Use this to inspect a single subscription key's status, binding, and level before deciding whether to reassign or clear it. Requires System.Audit on the PDM node — operators who lack audit rights on the key's bound remote will receive a 404 (indistinguishable from a missing key, by design). Check the `pending-clear` field before taking any reassignment action; a truthy value means a clear is already queued and has not yet been applied.",
+  "examples": [
+    {
+      "summary": "Fetch details for an active PVE Standard subscription key",
+      "path_params": {
+        "key": "pve2s-a1b2c3d4e5"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The key pattern accepts pve[0-9]+ or pbs prefixes followed by a tier code (c/b/s/p) and 10 hex chars — validate locally before calling to avoid unnecessary 404s.",
+    "`check-time` reflects the last import or refresh epoch, not the subscription expiry; use `next-due-date` for renewal tracking.",
+    "A 404 response means either the key does not exist in the pool or your token lacks audit rights on the bound remote — the API intentionally does not distinguish between the two.",
+    "If `source` is 'adopted', the key was pulled in automatically from a managed remote rather than entered manually; treat its binding as managed by that remote."
+  ],
+  "relatedOperations": [
+    "get_subscriptions_keys",
+    "post_subscriptions_keys",
+    "delete_subscriptions_keys_key",
+    "put_subscriptions_keys_key_refresh"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_subscriptions_node_status.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_subscriptions_node_status",
+  "usageNotes": "Use this endpoint to get a fleet-wide view of subscription health across all PVE and PBS remotes managed by PDM; results are filtered to remotes the caller has PRIV_RESOURCE_AUDIT on, so output scope varies by user. Results are cached for 5 minutes by default — pass max-age=0 to force a live query from each remote node, which is slower but necessary when validating a key assignment that was just changed. The pending-clear field signals that a pool key removal is queued but has not yet propagated to the node.",
+  "examples": [
+    {
+      "summary": "Force a fresh subscription check across all auditable remotes",
+      "path_params": {},
+      "params": {
+        "max-age": 0
+      }
+    }
+  ],
+  "tips": [
+    "A node with status=active but assigned-key differing from current-key means a key rotation is in progress or stale — re-query with max-age=0 to confirm.",
+    "The sockets field is only populated for PVE remotes; expect it absent for PBS nodes.",
+    "pending-clear is omitted from the wire when false — treat its absence as false, not unknown.",
+    "level=Unknown typically means the remote was reachable but could not confirm subscription details; check connectivity to that remote's subscription server."
+  ],
+  "relatedOperations": [
+    "get_subscriptions_list",
+    "get_subscriptions_node_info",
+    "post_subscriptions_assign_key"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_version.json

@@ -0,0 +1,16 @@
+{
+  "operationId": "get_version",
+  "usageNotes": "Use this endpoint to confirm the running Proxmox Datacenter Manager version before scripting against version-specific behavior or after an upgrade. No parameters are required, and any authenticated user (including API tokens) can call it. Returns immediately with no async task.",
+  "examples": [
+    {
+      "summary": "Retrieve PDM version info",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns three fields: version (e.g. '0.5.1'), release (package release tag), and repoid (git commit hash) — use repoid to pinpoint the exact build when filing bug reports.",
+    "This endpoint is the lightest possible health/connectivity check: if it succeeds, the PDM API is reachable and credentials are valid."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_access_domains_realm_sync",
+  "usageNotes": "Triggers an LDAP/AD or other external directory sync for a configured realm, pulling users into PDM. Returns a UPID — poll the task log to confirm completion before assuming users are available. Use `dry-run: true` first to preview what would be created, deleted, or updated without making any changes; this is especially important when `remove-vanished` includes `entry` or `acl`, as those options permanently remove users and their ACLs from PDM if they disappear from the source.",
+  "examples": [
+    {
+      "summary": "Sync the corporate LDAP realm, enabling new users immediately and removing stale entries and ACLs",
+      "path_params": {
+        "realm": "corp-ldap"
+      },
+      "params": {
+        "enable-new": true,
+        "remove-vanished": "entry;acl",
+        "dry-run": false
+      }
+    }
+  ],
+  "tips": [
+    "Run with `dry-run: true` before your first production sync — the response UPID still represents a real task log you can inspect to see what would change.",
+    "`remove-vanished: \"properties\"` strips custom attributes from existing users that are no longer present in the directory source; use carefully if you manage any PDM-local properties outside the directory.",
+    "The sync is asynchronous; poll `get_nodes_node_tasks_upid_status` (PVE) or the PDM task endpoint with the returned UPID to detect failures.",
+    "Requires the realm to already be configured under `/access/domains/{realm}` before syncing."
+  ],
+  "relatedOperations": [
+    "get_access_domains",
+    "post_access_domains",
+    "put_access_domains_realm",
+    "delete_access_domains_realm"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_access_openid_auth_url",
+  "usageNotes": "Use this as the first step in an OpenID Connect login flow: POST the realm name and your application's redirect-url to receive the provider's authorization URL, then redirect the browser to that URL. No authentication is required — this endpoint is world-accessible by design. The redirect-url must exactly match a URI registered with the OpenID provider, or the provider will reject the subsequent callback.",
+  "examples": [
+    {
+      "summary": "Initiate OpenID login for the 'corp-sso' realm, redirecting back to a local dashboard",
+      "path_params": {},
+      "params": {
+        "realm": "corp-sso",
+        "redirect-url": "https://dashboard.example.com/auth/callback"
+      }
+    }
+  ],
+  "tips": [
+    "The returned string is a full URL — redirect the user's browser to it; do not call it server-side.",
+    "The realm must already be configured in PDM as an OpenID Connect realm before this call will succeed.",
+    "Mismatched redirect-url values (not registered with the identity provider) will cause a provider-side error after the redirect, not a PDM API error.",
+    "Because no token or cookie is required, this endpoint is safe to call from a browser or unauthenticated proxy."
+  ],
+  "relatedOperations": [
+    "post_access_openid_login"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_access_openid_login",
+  "usageNotes": "Call this endpoint to complete the OpenID Connect authorization code flow and obtain a PDM session ticket. The caller must supply the authorization code, state, and redirect URL exactly as returned by the identity provider and used in the initial authorization request — any mismatch will result in rejection. The response sets an HttpOnly session cookie; subsequent API calls should present the CSRFPreventionToken header alongside the cookie to satisfy CSRF protection.",
+  "examples": [
+    {
+      "summary": "Exchange an OpenID authorization code for a PDM session ticket",
+      "path_params": {},
+      "params": {
+        "code": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.abc123",
+        "redirect-url": "https://pdm.nightsquawk.tech:8443",
+        "state": "a7f3c2d1e8b04f5a9c6d2e3f1a0b7c8d"
+      }
+    }
+  ],
+  "tips": [
+    "The redirect-url must exactly match the value registered with the OpenID provider; even a trailing-slash difference will cause the token exchange to fail.",
+    "On success, the real ticket is delivered as an HttpOnly cookie (not in the JSON body); the response body's ticket-info field contains an unsigned version useful only for client-side display.",
+    "Store the CSRFPreventionToken from the response and send it as the CSRFPreventionToken header on all subsequent write requests.",
+    "This endpoint requires no prior authentication (permissions: world), making it safe to call before any session exists."
+  ],
+  "relatedOperations": [
+    "get_access_openid_login",
+    "post_access_ticket",
+    "delete_access_ticket"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_access_tfa_userid",
+  "usageNotes": "Use this to enroll a new TFA (two-factor authentication) entry for a user — supported types are totp, webauthn, u2f, recovery, and yubico. An admin needs Access.Modify on /access/users, or the caller must be the target user themselves. For TOTP, supply a valid totp URI and the current OTP value in the 'value' field so PDM can verify the key before saving; for WebAuthn/U2F, the registration is a two-step flow — call first without a challenge to receive one, then call again with the challenge response in 'value'.",
+  "examples": [
+    {
+      "summary": "Add a TOTP authenticator app entry for a user",
+      "path_params": {
+        "userid": "kevin@pve"
+      },
+      "params": {
+        "type": "totp",
+        "totp": "otpauth://totp/PDM:kevin@pve?secret=JBSWY3DPEHPK3PXP&issuer=PDM",
+        "value": "482910",
+        "description": "Authenticator app (phone)"
+      }
+    }
+  ],
+  "tips": [
+    "When type is 'recovery', the response includes a one-time-use integer code list — store these immediately; they cannot be retrieved again.",
+    "For WebAuthn/U2F, the first POST (no 'challenge' or 'value') returns a challenge string in the response; submit that as 'challenge' plus the device's signed response as 'value' in the second POST to complete enrollment.",
+    "The 'password' field may be required by PDM's TFA policy when a non-admin modifies their own account — supply the user's current login password if the API returns a permission or confirmation error.",
+    "A user can hold multiple TFA entries of different types; use the 'description' field to label each device so they are distinguishable in the UI and via list endpoints."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "delete_access_tfa_userid_id",
+    "get_access_tfa",
+    "post_access_tfa_userid_id"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_access_ticket",
+  "usageNotes": "Use this endpoint to authenticate a user and obtain a session ticket for subsequent API calls. The response includes a ticket (used as a Bearer token or cookie) and a CSRFPreventionToken required for all POST/PUT/DELETE requests. If the user has TFA configured, the initial response returns a TFA challenge string that must be answered in a second request using the 'tfa-challenge' parameter.",
+  "examples": [
+    {
+      "summary": "Authenticate a local PDM user and retrieve a session ticket",
+      "path_params": {},
+      "params": {
+        "username": "admin@pam",
+        "password": "s3cur3P@ssword"
+      }
+    }
+  ],
+  "tips": [
+    "The returned ticket must be sent as 'Authorization: PDMAPIToken=...' or as a cookie on subsequent requests; the CSRFPreventionToken must be included as 'CSRFPreventionToken' header for non-GET requests.",
+    "Tickets are time-limited (typically 2 hours); re-authenticate before expiry if running long-lived automations.",
+    "The optional 'path' and 'privs' parameters allow ticket verification plus privilege checking in a single call — useful for SSO flows that need to confirm access before redirecting.",
+    "When authenticating via an API token (USER@REALM!TOKENID=SECRET), this endpoint is not needed — API tokens are passed directly in the Authorization header.",
+    "Username format must match the pattern user@realm (e.g., admin@pam, kevin@pve)."
+  ],
+  "relatedOperations": [
+    "delete_access_ticket",
+    "get_access_ticket",
+    "post_access_tfa_response"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_access_users",
+  "usageNotes": "Use this to provision a new PDM user account. The userid must include a realm suffix in the form user@realm (e.g. alice@pve or svc-monitoring@pam), and the caller must hold Access.Modify on /access/users. Password is only meaningful for pve-realm users — realm-authenticated users (LDAP, AD, OpenID) authenticate externally and should omit it. The endpoint returns null on success; errors surface as HTTP 4xx.",
+  "examples": [
+    {
+      "summary": "Create a read-only monitoring service account in the pve realm",
+      "path_params": {},
+      "params": {
+        "userid": "svc-monitoring@pve",
+        "firstname": "Monitoring",
+        "lastname": "Service",
+        "email": "alerts@example.com",
+        "password": "S3cur3P@ssw0rd",
+        "enable": true,
+        "expire": 0,
+        "comment": "Read-only service account for Prometheus/Grafana scraping"
+      }
+    }
+  ],
+  "tips": [
+    "After creating the user, use put_access_acl to assign role bindings — a new user has no privileges until an ACL is applied.",
+    "For SSO/OpenID users, omit the password field entirely; their credentials are managed by the external provider.",
+    "Set expire to a Unix timestamp to auto-disable temporary accounts (e.g. contractors); expire=0 means no expiry.",
+    "Realm must already exist in PDM — verify with get_access_domains before creating users in custom realms."
+  ],
+  "relatedOperations": [
+    "put_access_acl",
+    "get_access_roles",
+    "get_access_domains",
+    "post_access_tfa_userid"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_access_users_userid_token_token_name.json

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_access_users_userid_token_token_name",
+  "usageNotes": "Use this to create a new API token for a PDM user, either for automation accounts or to generate scoped tokens for your own account. The response includes the plaintext token secret exactly once — it cannot be retrieved again, so capture it immediately. Users can create tokens for themselves without elevated privileges; creating tokens for other users requires Access.Modify on /access/users.",
+  "examples": [
+    {
+      "summary": "Create a read-only automation token for the local admin user, expiring in ~1 year",
+      "path_params": {
+        "userid": "admin@pve",
+        "token-name": "mcp-readonly"
+      },
+      "params": {
+        "comment": "MCP server read-only automation token",
+        "enable": true,
+        "expire": 1782000000
+      }
+    }
+  ],
+  "tips": [
+    "The full authentication ID (Authid) is formatted as userid!token-name (e.g. admin@pve!mcp-readonly) — this is what you pass in the Authorization header.",
+    "Token names must match /^[A-Za-z0-9_][A-Za-z0-9._-]*$/ — no spaces or special chars.",
+    "Set expire to a future Unix timestamp to enforce rotation; leave at 0 (default) for no expiration.",
+    "Use the digest param when updating tokens concurrently to prevent race conditions — not needed for a fresh create.",
+    "Tokens inherit the privileges of their parent user; they cannot exceed user-level permissions."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_token_token_name",
+    "put_access_users_userid_token_token_name",
+    "delete_access_users_userid_token_token_name",
+    "get_access_users_userid_token",
+    "post_access_users"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_auto_install_answer.json

@@ -0,0 +1,49 @@
+{
+  "operationId": "post_auto_install_answer",
+  "usageNotes": "Called by the Proxmox automated installer (proxmox-auto-install-assistant) when a new machine boots from an auto-install ISO and fetches its answer file via HTTP — it is not typically called directly by administrators. The installer POSTs system-discovery data (DMI hardware info, ISO metadata, detected network interfaces, and product config) and receives back a fully-resolved answer-file object that governs disk setup, network, credentials, and post-install hooks for that specific machine. Authentication uses specialized bearer tokens (not standard API tokens), and the endpoint is world-accessible by design so the booting machine can reach it without pre-enrolled credentials.",
+  "examples": [
+    {
+      "summary": "PVE node fetches its answer file during unattended installation",
+      "path_params": {},
+      "params": {
+        "$schema": {
+          "version": "1"
+        },
+        "dmi": {
+          "system": {
+            "manufacturer": "Supermicro",
+            "product-name": "SYS-5019S-M",
+            "serial-number": "A123456789"
+          }
+        },
+        "iso": {
+          "release": "8.2",
+          "product": "pve"
+        },
+        "network_interfaces": [
+          {
+            "name": "eth0",
+            "mac": "ac:1f:6b:2d:44:e1",
+            "link": true
+          }
+        ],
+        "product": {
+          "fullname": "Proxmox VE",
+          "abbreviation": "pve"
+        }
+      }
+    }
+  ],
+  "tips": [
+    "This endpoint is consumed by the installer at boot time, not by admin tooling — use it to verify what answer file a specific machine would receive before deploying.",
+    "The bearer token scheme is separate from normal PDM API tokens; configure it in the PDM auto-install settings before pointing ISOs at the PDM answer server.",
+    "The response's 'global.fqdn' field can be set to 'from-dhcp' so each machine self-registers its hostname rather than receiving a hardcoded one.",
+    "Use 'disk-setup.filter' with udev properties (e.g. ID_BUS=ata, ID_SERIAL) to target specific disks without listing them by name, which is safer across heterogeneous hardware.",
+    "Set 'post-installation-webhook' to call back your provisioning system after install completes so you can trigger Ansible/Salt runs or update your CMDB automatically."
+  ],
+  "relatedOperations": [
+    "get_auto_install_answer",
+    "post_auto_install_answer_match",
+    "get_nodes"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_auto_install_installations_uuid_post_hook.json

@@ -0,0 +1,41 @@
+{
+  "operationId": "post_auto_install_installations_uuid_post_hook",
+  "usageNotes": "This endpoint is called by the Proxmox auto-installer itself at the end of a successful installation — not by operators directly. It reports system fingerprint data (CPU, disks, NICs, DMI, kernel, SSH host keys) back to PDM so the installation record can be marked complete. Authentication uses the per-installation token issued with the answer file, not a standard API token; the token field in the body must match exactly.",
+  "examples": [
+    {
+      "summary": "Post-installation callback after a Proxmox VE node finishes installing",
+      "path_params": {
+        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {
+        "$schema": { "version": "1.0" },
+        "boot-info": { "mode": "efi", "secureboot": false },
+        "cpu-info": { "sockets": 1, "cores": 8, "threads": 16, "model": "Intel(R) Core(TM) i9-9900K" },
+        "debian-version": "12.5",
+        "disks": [{ "device": "/dev/sda", "size": 512000000000 }],
+        "dmi": { "system": { "manufacturer": "Supermicro", "product": "X11SCL-F" } },
+        "filesystem": "ext4",
+        "fqdn": "pve-node1.nightsquawk.local",
+        "iso": { "release": "8.2-1" },
+        "kernel-version": { "sysname": "Linux", "release": "6.8.12-1-pve" },
+        "machine-id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
+        "network-interfaces": [{ "name": "eth0", "mac": "aa:bb:cc:dd:ee:ff" }],
+        "product": { "fullname": "Proxmox VE", "version": "8.2" },
+        "reboot-mode": "reboot",
+        "ssh-public-host-keys": { "ecdsa": "ecdsa-sha2-nistp256 AAAA..." },
+        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"
+      }
+    }
+  ],
+  "tips": [
+    "This is an installer-internal callback; manually crafting this request is only needed when debugging a stalled installation or replaying a hook in testing.",
+    "The token is short-lived and tied to a specific installation UUID — reuse across UUIDs will be rejected.",
+    "Returns null on success; any non-2xx response from PDM will cause the installer to flag the installation as incomplete.",
+    "reboot-mode defaults to 'reboot'; set 'power-off' in the answer file if you need the node to stay off after install (e.g., for imaging workflows)."
+  ],
+  "relatedOperations": [
+    "post_auto_install_installations_uuid_answer",
+    "get_auto_install_installations_uuid",
+    "get_auto_install_installations"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_auto_install_prepared.json

@@ -0,0 +1,53 @@
+{
+  "operationId": "post_auto_install_prepared",
+  "usageNotes": "Use this to register a new prepared answer file in Proxmox Datacenter Manager's auto-install system, which allows bare-metal nodes to be installed unattended when they PXE-boot. Requires the System.Modify privilege on the system/auto-installation path. If you omit 'target-filter', the configuration acts as a catch-all default for any installation request not matched by a narrower config — only one such default can exist at a time, so setting 'is-default: true' will silently override any prior default.",
+  "examples": [
+    {
+      "summary": "Create a prepared answer for a static-IP PVE node using ZFS mirrored disks",
+      "path_params": {},
+      "params": {
+        "id": "pve-node-zfs-static",
+        "country": "us",
+        "timezone": "America/Los_Angeles",
+        "keyboard": "en-us",
+        "mailto": "admin@example.com",
+        "fqdn": "pve01.internal.example.com",
+        "use-dhcp-fqdn": false,
+        "use-dhcp-network": false,
+        "cidr": "10.10.1.11/24",
+        "gateway": "10.10.1.1",
+        "dns": "10.10.1.1",
+        "disk-mode": "filter",
+        "disk-filter": { "ID_MODEL": "SAMSUNG*" },
+        "disk-filter-match": "any",
+        "filesystem": {
+          "filesystem": "zfs",
+          "ashift": 12,
+          "copies": 1
+        },
+        "netif-name-pinning-enabled": true,
+        "reboot-mode": "reboot",
+        "reboot-on-error": false,
+        "root-ssh-keys": ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@jumphost"],
+        "subscription-key": "pve8c-0a1b2c3d4e",
+        "is-default": false,
+        "target-filter": { "/product": "Proxmox VE" }
+      }
+    }
+  ],
+  "tips": [
+    "Only one prepared config may have 'is-default: true'; creating a second will overwrite the flag on the existing default.",
+    "Fields that support MiniJinja templating (fqdn, mailto, cidr, gateway, dns) are rendered at install time — use 'template-counters' to drive auto-incrementing host numbers across a fleet.",
+    "Use 'authorized-tokens' to restrict which PDM API tokens can fetch this answer file, reducing the blast radius if a token is compromised.",
+    "When 'disk-mode' is 'filter', 'disk-filter' and 'disk-filter-match' drive selection; when it is 'list', populate 'disk-list' with block device names like 'sda' or 'nvme0n1' — mixing both modes is not supported.",
+    "If 'post-hook-base-url' is an HTTPS endpoint you control, pair it with 'post-hook-cert-fp' (sha256 fingerprint) to pin the TLS certificate and prevent MITM during post-install callback."
+  ],
+  "relatedOperations": [
+    "get_auto_install_prepared",
+    "get_auto_install_prepared_id",
+    "put_auto_install_prepared_id",
+    "delete_auto_install_prepared_id",
+    "get_auto_install_token",
+    "post_auto_install_token"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_auto_install_tokens.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_auto_install_tokens",
+  "usageNotes": "Use this endpoint to generate a new auto-install token that PDM's automated installer can use to authenticate against the datacenter manager. Requires the System.Modify privilege on the system/auto-installation path. The secret returned in the response is shown only once — store it immediately, as it cannot be retrieved again.",
+  "examples": [
+    {
+      "summary": "Create a short-lived auto-install token for a staging deployment",
+      "path_params": {},
+      "params": {
+        "id": "staging-deploy-01",
+        "comment": "Staging auto-install token for June 2026 rollout",
+        "enabled": true,
+        "expire-at": 1753747200
+      }
+    }
+  ],
+  "tips": [
+    "The `secret` field in the response is the raw token secret and is only returned at creation time — there is no retrieval endpoint; save it to a secrets manager immediately.",
+    "Set `expire-at` to a Unix timestamp (seconds since epoch) for time-bounded deployments; use 0 or omit the field for a non-expiring token.",
+    "Token `id` must start with an alphanumeric character or underscore and may contain dots, hyphens, and underscores; it must be 3–64 characters.",
+    "Tokens created here are scoped to auto-installation workflows and are distinct from user API tokens managed under /access/users."
+  ],
+  "relatedOperations": [
+    "get_auto_install",
+    "delete_auto_install_installations_uuid"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_config_access_ad.json

@@ -0,0 +1,39 @@
+{
+  "operationId": "post_config_access_ad",
+  "usageNotes": "Use this to register a new Active Directory realm in Proxmox Datacenter Manager so PDM-managed nodes can authenticate users against your AD/LDAP server. Requires the `Realm.Allocate` privilege on the `access/domains` ACL path — API tokens are accepted. The realm name must be unique across all realms and cannot be changed after creation; set `bind-dn` and `password` if the AD server requires authenticated binds.",
+  "examples": [
+    {
+      "summary": "Create a corporate AD realm with LDAPS, authenticated bind, and attribute sync",
+      "path_params": {},
+      "params": {
+        "realm": "corp-ad",
+        "server1": "dc1.corp.example.com",
+        "server2": "dc2.corp.example.com",
+        "base-dn": "DC=corp,DC=example,DC=com",
+        "bind-dn": "CN=pdm-svc,OU=Service Accounts,DC=corp,DC=example,DC=com",
+        "password": "S3cr3tBindP@ss",
+        "mode": "ldaps",
+        "port": 636,
+        "verify": true,
+        "sync-attributes": "email=mail,firstname=givenName,lastname=sn",
+        "sync-defaults-options": "enable-new=1,remove-vanished=entry;properties",
+        "user-classes": "user,person",
+        "comment": "Corporate Active Directory realm",
+        "default": false
+      }
+    }
+  ],
+  "tips": [
+    "The `realm` value becomes part of every synced user's login name (user@realm) and cannot be renamed — choose it carefully before first use.",
+    "Use `mode: ldaps` with `port: 636` and `verify: true` for production; the default `ldap` on port 389 sends credentials in plaintext.",
+    "If your AD enforces authenticated queries, `bind-dn` and `password` are effectively required even though the spec marks them optional.",
+    "After creating the realm, trigger a user sync via the corresponding sync endpoint to populate PDM users from the AD directory.",
+    "Setting `default: true` makes this realm pre-selected on the PDM login page — only one realm should have this flag."
+  ],
+  "relatedOperations": [
+    "get_config_access_ad",
+    "put_config_access_ad_realm",
+    "delete_config_access_ad_realm",
+    "post_config_access_ad_realm_sync"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_config_access_ldap.json

@@ -0,0 +1,43 @@
+{
+  "operationId": "post_config_access_ldap",
+  "usageNotes": "Use this to register a new LDAP authentication realm in Proxmox Datacenter Manager, enabling centralized directory-based login for PDM users. The calling token or user must hold the Realm.Allocate privilege on the access/domains path. After creation, run a user sync (post_access_domains_realm_sync) to populate users from the directory before they can log in.",
+  "examples": [
+    {
+      "summary": "Create an Active Directory-backed LDAP realm with STARTTLS and attribute mapping",
+      "path_params": {},
+      "params": {
+        "realm": "corp-ad",
+        "server1": "dc01.corp.example.com",
+        "server2": "dc02.corp.example.com",
+        "base-dn": "DC=corp,DC=example,DC=com",
+        "bind-dn": "CN=pdm-bind,OU=Service Accounts,DC=corp,DC=example,DC=com",
+        "password": "BindP@ssw0rd!",
+        "user-attr": "sAMAccountName",
+        "mode": "ldap+starttls",
+        "port": 389,
+        "verify": true,
+        "user-classes": "user,person",
+        "sync-attributes": "email=mail,firstname=givenName,lastname=sn",
+        "sync-defaults-options": "enable-new=1,remove-vanished=entry;properties",
+        "filter": "(!(userAccountControl:1.2.840.113556.1.4.803:=2))",
+        "comment": "Corporate Active Directory realm",
+        "default": false
+      }
+    }
+  ],
+  "tips": [
+    "The realm name must be 2–32 characters and match /^(?:[A-Za-z0-9_][A-Za-z0-9.\\-_]*)$/ — choose a short, stable identifier since renaming requires delete+recreate.",
+    "For Active Directory, set user-attr to 'sAMAccountName'; for standard OpenLDAP, use 'uid'.",
+    "Use mode 'ldaps' (port 636) or 'ldap+starttls' (port 389) in production — plain 'ldap' transmits bind credentials in cleartext.",
+    "Set verify=true with a capath pointing to your internal CA cert when using STARTTLS or LDAPS against an internal PKI.",
+    "The filter param accepts standard LDAP filter syntax; use it to exclude disabled accounts or restrict to a specific OU.",
+    "After creation, the realm won't have any PDM users yet — trigger a sync immediately via post_access_domains_realm_sync."
+  ],
+  "relatedOperations": [
+    "get_config_access",
+    "post_access_domains_realm_sync",
+    "get_access_domains",
+    "put_config_access_ldap_realm",
+    "delete_config_access_ldap_realm"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_config_access_openid.json

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_config_access_openid",
+  "usageNotes": "Use this to register a new OpenID Connect realm in Proxmox Datacenter Manager so users can authenticate via an external identity provider (e.g., Keycloak, Azure AD, Authentik). Requires the `Realm.Allocate` privilege on `/access/domains`. The `realm` name must be unique across all authentication realms; if `autocreate` is false (default), users must be pre-provisioned in PDM before they can log in via the new realm.",
+  "examples": [
+    {
+      "summary": "Register an Authentik-backed OIDC realm for SSO",
+      "path_params": {},
+      "params": {
+        "realm": "authentik",
+        "client-id": "proxmox-pdm",
+        "client-key": "supersecretclientkey",
+        "issuer-url": "https://sso.example.com/application/o/proxmox-pdm/",
+        "username-claim": "preferred_username",
+        "scopes": "openid email profile",
+        "autocreate": true,
+        "default": false,
+        "comment": "Authentik SSO for NightSquawk staff"
+      }
+    }
+  ],
+  "tips": [
+    "The `username-claim` field determines how PDM maps OIDC token claims to local user accounts — ensure the IdP cannot let users self-modify this claim, as it is the uniqueness key.",
+    "Scopes default to 'email profile'; add 'openid' explicitly if your IdP requires it in the scope list.",
+    "Set `default: true` only after verifying the realm works correctly; an unreachable default IdP locks out web-UI users who rely on automatic realm pre-selection.",
+    "After creation, verify the realm appears with `get_config_access` or `get_config_access_openid_{realm}` before directing users to log in."
+  ],
+  "relatedOperations": [
+    "get_config_access_openid",
+    "put_config_access_openid",
+    "delete_config_access_openid",
+    "get_config_access"
+  ]
+}

package/dist/catalog-pdm/enrichment/post_config_acme_account.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_config_acme_account",
+  "usageNotes": "Use this to register a new ACME account with a certificate authority (e.g. Let's Encrypt) so PDM can automate TLS certificate issuance. The operation is asynchronous — it returns a UPID that must be polled for completion. If the CA requires External Account Binding (EAB), supply both eab_kid and eab_hmac_key together; omitting either will cause registration to fail.",
+  "examples": [
+    {
+      "summary": "Register a Let's Encrypt production account named 'letsencrypt'",
+      "path_params": {},
+      "params": {
+        "name": "letsencrypt",
+        "contact": "hello@nightsquawk.tech",
+        "directory": "https://acme-v02.api.letsencrypt.org/directory",
+        "tos_url": "https://letsencrypt.org/documents/LE-SA-v1.4-April-3-2024.pdf"
+      }
+    }
+  ],
+  "tips": [
+    "Omit 'name' to register the account as the default (name defaults to 'default').",
+    "Use the Let's Encrypt staging directory (https://acme-staging-v02.api.letsencrypt.org/directory) for testing to avoid rate limits.",
+    "Setting 'tos_url' is how PDM records your acceptance of the CA's Terms of Service — required by most CAs.",
+    "Poll the returned UPID via the task log endpoints to confirm successful registration before attempting certificate orders."
+  ],
+  "relatedOperations": [
+    "get_config_acme_account",
+    "get_config_acme_account_name",
+    "put_config_acme_account_name",
+    "delete_config_acme_account_name",
+    "post_config_acme_certificate"
+  ]
+}