Xen Orchestra MCP Server — 291 tools
The Xen Orchestra DADL turns Xen Orchestra's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 291 tools — vm, vdi, host, acl, backup, vif, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.
Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Xen Orchestra feature area, required credential scopes.
Source: Xen Orchestra REST API
Which Xen Orchestra endpoints are covered?
99% (291 of ~294 endpoints)
Focus: Complete REST API coverage for XO 6.4+: all object types (VMs, VM controllers, VM templates, VM snapshots, hosts, pools, SRs, VDIs, VDI snapshots, VBDs, networks, VIFs, PIFs, PBDs, PCIs, PGPUs, SMs), all lifecycle actions (CRUD, partial update of VMs, VIFs and VDIs, power, snapshot/clone/migrate/revert, export/import, hotplug), full host power/lifecycle control (start, clean/smart reboot, clean/emergency shutdown, restart toolstack, disable/enable incl. reboot-persistent maintenance mode, detach, forget, pool join, PIF rescan, SR probing of NFS/iSCSI/HBA/ZFS targets), full sub-resource access (alarms, messages, tasks, tags, stats per object), RBAC v2 (users, groups, acl-roles, acl-privileges, plus reading role-to-user/group assignments), backups (archives incl. live mount of backup disks, jobs, logs, restore-logs, writable repositories incl. health check, throughput benchmark and space reclaim, schedules), real-time events via SSE, host/pool maintenance ops (rolling reboot/update incl. pinned-VM handling, interrupted-update recovery and finalize, management reconfigure, audit logs, missing patches), network traffic rules (SDN controller plugin: add/delete/update), IPMI sensor inventory (ipmi-sensors plugin), audit records (audit plugin), XO plugin management (list, load/unload, autoload, self-test, configuration reset), XOA appliance (dashboard, ping, gui-routes, MCP status). Some routes with format path params are exposed as multiple typed tools (e.g. /vms/{id}.{format} -> export_vm_xva + export_vm_ova, /vdis/{id}.{format} -> export_vdi_vhd + export_vdi_raw + export_vdi_qcow2 + export_vdi_vmdk + import_vdi_to_existing + import_vdi_to_existing_raw).
Missing: Authentication-token routes (GET/POST /users/{id}/authentication_tokens) are deliberately NOT exposed: their responses contain plaintext bearer tokens -- the GET list even includes the token used to make the request (see XO PR #10233) -- which must never enter an LLM context. Create/revoke tokens via xo-cli --createToken or the XO web UI instead; do NOT re-add these routes. Backup RESTORE is not exposed over REST -- backup archives, jobs and logs can be read, but restoring a restore-point onto a target SR must be done in the XO GUI or via the JSON-RPC API; since XO 6.9 a backup disk can at least be live-mounted read-only on a host (mount_backup_live_disk) to read its content without a restore; the read/write live restore of XO 6.10 (bootable, with a cache SR) is UI/JSON-RPC only. PUT /plugins/{id}/configuration (XO 6.10) is not exposed: its request body is the free-form, plugin-specific configuration object itself, which DADL cannot declare as named body params -- configure plugins in the XO UI (get_plugin, load_plugin, test_plugin and delete_plugin_configuration are exposed). SDN-controller traffic-rule routes (/plugins/sdn-controller/*) are included but only function when the xo-server-sdn-controller plugin is installed; the IPMI inventory route (/plugins/ipmi-sensors/*) likewise requires the xo-server-ipmi-sensors plugin (>= 2.1.1, XO 6.8+) and returns 503 on hosts without a reachable IPMI device; the audit-record routes (/plugins/audit/*) require the xo-server-audit plugin. Deprecated routes (POST /users/authentication_tokens, GET /backup/jobs/vm/*, GET /restore/logs/*) intentionally excluded -- announced for removal on 2026-09-12 / 2026-10-13 and still present in 6.10; do not rely on them. Version floor: routes marked 'XO 6.7+' return 404 on 6.6.x (create_sr, update_vdi, list_acl_role_users, list_acl_role_groups, list_group_acl_roles), 'XO 6.8+' on 6.7.x (scan_pifs_host, get_host_ipmi_sensors) 'XO 6.9+' on 6.8.x (get_pool_rolling_update_recovery, finalize_rolling_update_pool, reclaim_space_backup_repository, mount_backup_live_disk, unmount_backup_live_disk, list_audit_records, get_audit_record; export_vdi_qcow2 answers 422 there) and 'XO 6.10+' on 6.9.x (the eight probe_*_host tools, list_plugins, get_plugin, update_plugin, delete_plugin_configuration, load_plugin, unload_plugin, test_plugin; export_vdi_vmdk answers 422 there). Body fields newer than the target build are REJECTED with HTTP 400 by XO's typed routes -- bypassBackupCheck and acceptCurrentStateAsBaseline (6.9) on 6.7/6.8, privileges (create_acl_role), bypassCpuCheck (migrate_vm) and insecureNbd (create_*network) (6.10) on 6.9 and older -- so omit them on older XO; only the pre-6.7 rolling_reboot/rolling_update routes had no body at all and silently ignore shutdownPinnedVms
How do you configure the Xen Orchestra DADL?
- Deploy Xen Orchestra from sources or use XOA (Xen Orchestra Appliance)
- Log in to the XO web UI as an admin user
- Navigate to Settings -> Users to confirm admin access
- Generate an auth token via CLI: xo-cli --createToken xo.example.com <user> <password>
- Or via API: POST /rest/v0/users/me/authentication_tokens with Basic auth
- Copy the returned token value -- use it as the authenticationToken cookie
- Optional (XO 6.4+): create dedicated non-admin users via POST /users and assign acl-roles via PUT /acl-roles/{id}/users/{userId}
Environment variable: CREDENTIAL_XEN_ORCHESTRA_TOKEN
The url in backends.yaml must point to your XO instance including /rest/v0. Generate a token via xo-cli --createToken or POST /rest/v0/users/me/authentication_tokens with Basic auth. Live Swagger UI at /rest/v0/docs lists all endpoints with required RBAC privileges. For RBAC v2 setup see https://docs.xen-orchestra.com/xo6/acl-v2.
How do you install the Xen Orchestra MCP server with ToolMesh?
Add to your backends.yaml:
- name: xen-orchestra
transport: rest
dadl: xen-orchestra.dadl
url: "https://xo.example.com/rest/v0"
Set the credential:
CREDENTIAL_XEN_ORCHESTRA_TOKEN=your-token-hereWhat 291 tools does the Xen Orchestra DADL expose?
GETpingHealth check. Unauthenticated. Returns {result: 'pong', timestamp}. Use this to verify the XO instance is reachable before trying authenticated calls.GETget_dashboardAggregated dashboard for the XOA appliance: pool/host/VM counts, storage usage, recent backup-jobs (last 7 days), disconnected servers, disabled hosts. Use ndjson=true for streaming output. Replaces the legacy plural /dashboards endpoint.GETget_gui_routesReturns the URLs of the legacy XO5 (xo5) and modern XO6 (xo6) web UIs. Useful for clients that need to deep-link into the GUI.GETget_mcp_statusReport whether XO's built-in MCP server is enabled. Unauthenticated. Returns 200 when enabled, 503 when disabled. Requires a recent XO build (REST route added after 6.5.0); returns 404 on older instances.GETlist_usersList all users. Returns URLs by default; use fields for objects. Requires user:read privilege.GETget_userGet details of a single user. Use id='me' for the current authenticated user. Self-fetch is always allowed; reading another user requires user:read privilege.POSTcreate_userCreate a new user. Returns {id} of the created user. Requires user:create privilege.PATCHupdate_userUpdate user properties. Cannot change own permission. Synchronized users (LDAP/SAML/OIDC) cannot have name/password changed.DELETEdelete_userDelete a user. Irreversible. Requires user:delete privilege.GETlist_user_groupsList groups the user is a member of (filtered by group:read privilege). Use id='me' for self.GETlist_user_tasksList tasks owned by the user (filtered by task:read privilege). Use id='me' for self.GETlist_user_acl_privilegesList effective RBAC v2 acl-privileges for the user (XO 6.4+). Useful for inspecting what a user can actually do. Self-call (/users/me/acl-privileges) is always permitted.GETlist_groupsList all groups (filtered by group:read privilege).GETget_groupGet details of a single group.POSTcreate_groupCreate a new group. Returns {id} of the created group.PATCHupdate_groupUpdate group properties (currently only name).DELETEdelete_groupDelete a group. Irreversible. Removes all role attachments to this group.PUTadd_user_to_groupAdd a user to a group.DELETEremove_user_from_groupRemove a user from a group.GETlist_group_usersList users that are members of the group.GETlist_group_tasksList tasks associated with members of the group.GETlist_group_acl_rolesList the RBAC roles granted to this group -- i.e. what every member of the group inherits. Requires XO 6.7+ (returns 404 on older builds). Inverse view of list_acl_role_groups.GETlist_acl_rolesList all RBAC v2 roles. A role groups privileges and can be attached to users/groups.GETget_acl_roleGet details of a single role.POSTcreate_acl_roleCreate a new RBAC role. Returns {id}. Since XO 6.10 the privileges can be passed in the same call (privileges array; needs the acl-privilege:create privilege as well); otherwise add them afterwards via create_acl_privilege with roleId. Then attach the role to users/groups. Older builds reject the privileges field with HTTP 400.PATCHupdate_acl_roleUpdate a role's name and/or description (set description to null to clear).DELETEdelete_acl_roleDelete a role. Irreversible. All attachments to users/groups are removed; privileges referencing this role are also dropped.POSTcopy_acl_roleDuplicate a role (and its privileges) under a new name. Useful for deriving custom roles from built-in ones.GETlist_acl_role_privilegesList all acl-privileges attached to this role.GETlist_acl_role_usersList the users this RBAC role is directly attached to. Requires XO 6.7+ (returns 404 on older builds). Note this shows direct assignments only -- users who hold the role through a group appear in list_acl_role_groups instead.GETlist_acl_role_groupsList the groups this RBAC role is attached to. Every member of those groups inherits the role. Requires XO 6.7+ (returns 404 on older builds).PUTattach_acl_role_to_groupAttach an RBAC role to a group. All members of the group inherit the role's privileges.DELETEdetach_acl_role_from_groupDetach an RBAC role from a group.PUTattach_acl_role_to_userAttach an RBAC role directly to a user (in addition to roles inherited via groups).DELETEdetach_acl_role_from_userDetach an RBAC role from a user.GETlist_acl_privilegesList all RBAC v2 privileges (each privilege = role + resource + action, optionally scoped by object).GETget_acl_privilegeGet details of a single privilege.POSTcreate_acl_privilegeGrant a new privilege (action on a resource type, optionally narrowed to matching objects by a selector) to a role. Returns {id}. effect is required ('allow' or 'deny' -- a deny wins over any allow). Valid actions depend on the resource type (e.g. vm: read, start, shutdown:clean, update:tags; pool: create:vm) -- see Swagger /rest/v0/docs. There is no objectId field: scope to one object with selector 'id:<uuid>'. Since XO 6.10 privileges can also be passed directly to create_acl_role.PATCHupdate_acl_privilegeUpdate a privilege's resource, action, effect and/or selector (roleId is immutable). Only the fields you send change.DELETEdelete_acl_privilegeRevoke a privilege. Irreversible.GETlist_vmsList all VMs. Returns URLs by default; use fields for objects.GETget_vmGet full details of a VMPATCHupdate_vmPartially update a VM's properties (rename, resize CPU/RAM, boot firmware, tags, etc.). Only the fields you pass are changed. Some fields require the VM to be halted. Requires XO 6.5+ (PATCH /vms route returns 404 on older builds).DELETEdelete_vmDestroy a VM and its VDIs. Irreversible.POSTstart_vmStart a halted VM. Optionally pin to a specific host via body.hostId.POSTclean_shutdown_vmGracefully shut down a VM (ACPI shutdown)POSThard_shutdown_vmForce shutdown a VM immediately (equivalent to pulling the plug)POSTclean_reboot_vmGracefully reboot a VM (ACPI reboot)POSThard_reboot_vmForce reboot a VM immediatelyPOSTpause_vmPause a running VM (freezes CPU, keeps memory)POSTunpause_vmUnpause a paused VMPOSTsuspend_vmSuspend a VM to disk (saves memory state, frees RAM)POSTresume_vmResume a suspended VM from diskPOSTsnapshot_vmCreate a snapshot of a VM. Returns task reference; use ?sync to get the snapshot id directly.POSTrevert_vm_to_snapshotRevert a VM to one of its snapshots. Optionally take a fresh snapshot of the current state first (snapshotBefore) so the revert is undoable. Requires XO 6.5+ (route returns 404 on older builds).POSTclone_vmClone a VM. Three modes: fast clone on same SR (fast=true, omit srId), full copy on same SR (fast=false), or copy to another SR/pool (provide srId, optional compress=gzip|zstd for cross-pool).POSTmigrate_vmLive-migrate a VM to another host. Supports cross-SR storage migration and per-disk / per-VIF placement for cross-pool moves. Networks and SRs must belong to the destination host's pool. A move refused with VM_INCOMPATIBLE_WITH_THIS_HOST (CPU feature mismatch) can be forced with bypassCpuCheck=true (XO 6.10+) -- the VM may then crash after the migration.GETexport_vm_xvaExport a VM as XVA (XCP-ng native format). Streamed binary download.GETexport_vm_ovaExport a VM as OVA (Open Virtualization Format, portable across hypervisors).POSTimport_vm_xvaImport a VM from XVA upload into a pool. Body is the raw XVA stream.GETget_vm_statsGet RRD statistics for a VM (CPU, memory, network, disk). VM must be running.PUTadd_vm_data_sourceEnable a specific RRD data source on a VM (e.g. cpu0, vif_0_rx). VM must be running.DELETEdelete_vm_data_sourceDisable / forget a specific RRD data source on a VM.PUTadd_vm_tagAdd a tag to a VMDELETEremove_vm_tagRemove a tag from a VMGETlist_vm_vdisList all VDIs attached to a VMGETlist_vm_alarmsList XAPI alarms (performance/health thresholds) for the VM.GETlist_vm_messagesList XAPI messages/alerts emitted for the VM.GETlist_vm_tasksList tasks scoped to this VM (running/completed/failed).GETlist_vm_backup_jobsList backup-jobs that include this VM.GETget_vm_dashboardGet dashboard/statistics for a VM (aggregate metrics).GETlist_vm_snapshotsList all VM snapshotsGETget_vm_snapshotGet details of a VM snapshotDELETEdelete_vm_snapshotDelete a VM snapshot. Irreversible.GETexport_vm_snapshotExport a VM snapshot as XVA or OVA. Format is the file extension ('xva' or 'ova').GETlist_vm_snapshot_vdisList VDIs belonging to a VM snapshot.GETlist_vm_snapshot_alarmsList XAPI alarms scoped to a VM snapshot.GETlist_vm_snapshot_messagesList XAPI messages scoped to a VM snapshot.GETlist_vm_snapshot_tasksList tasks scoped to a VM snapshot.PUTadd_vm_snapshot_tagAdd a tag to a VM snapshot.DELETEremove_vm_snapshot_tagRemove a tag from a VM snapshot.GETlist_vm_templatesList all VM templates. Templates are stamps from which create_vm produces new VMs.GETget_vm_templateGet details of a VM template.DELETEdelete_vm_templateDelete a VM template. Irreversible. Built-in templates may be protected.GETexport_vm_templateExport a VM template as XVA or OVA.GETlist_vm_template_vdisList VDIs belonging to a VM template.GETlist_vm_template_alarmsList XAPI alarms scoped to a VM template.GETlist_vm_template_messagesList XAPI messages scoped to a VM template.GETlist_vm_template_tasksList tasks scoped to a VM template.PUTadd_vm_template_tagAdd a tag to a VM template.DELETEremove_vm_template_tagRemove a tag from a VM template.GETlist_vm_controllersList VM controllers (the dom0 control-domain VM of each host). Returns URLs by default; use fields for objects.GETget_vm_controllerGet full details of a VM controller (dom0 control domain).GETlist_vm_controller_alarmsList XAPI alarms for a VM controller.GETlist_vm_controller_vdisList VDIs attached to a VM controller.GETlist_vm_controller_messagesList XAPI messages for a VM controller.GETlist_vm_controller_tasksList tasks scoped to a VM controller.PUTadd_vm_controller_tagAdd a tag to a VM controller.DELETEremove_vm_controller_tagRemove a tag from a VM controller.GETlist_hostsList all XCP-ng/XenServer hostsGETget_hostGet details of a hostGETget_host_statsGet RRD statistics for a host (CPU, memory, NIC, disk). Host must be enabled.GETget_host_audit_logDownload the host's audit log as plain text. Useful for compliance and forensics.GETget_host_logsDownload the host's full logs as a gzipped tarball. Useful for support tickets and debugging.GETlist_host_alarmsList XAPI alarms (performance/health thresholds) for the host.GETget_host_smtGet the SMT (Simultaneous Multi-Threading / Hyper-Threading) status of the host.GETlist_host_missing_patchesList all patches/updates that are available but not yet installed on the host.GETlist_host_messagesList XAPI messages/alerts emitted for the host.GETlist_host_tasksList tasks scoped to this host (running/completed/failed).PUTadd_host_tagAdd a tag to a host.DELETEremove_host_tagRemove a tag from a host.POSTmanagement_reconfigure_hostMove the management interface (control plane) to a different PIF. May briefly disconnect XO from the host.POSTdisable_hostDisable a host = enter maintenance mode (no new VMs are placed on it). Optionally evacuate VMs in the same call (evacuate=true, optional force/vmIdsToForceMigrate). Since XO 6.7 the disable is PERSISTENT by default: the host stays disabled across toolstack restarts and reboots until enable_host. Send autoEnable=true for a transient disable that XAPI lifts at the next toolstack restart. XO 6.6 always disabled transiently and rejects autoEnable with HTTP 400. The persistent form requires XAPI >= 25.31.0 on the host; on older hosts the call fails unless autoEnable=true.POSTenable_hostRe-enable a disabled host (leave maintenance mode)POSTstart_hostPower on a halted host via its out-of-band controller (wake-on-LAN / IPMI, as configured in XAPI). Requires XO 6.6+.POSTclean_shutdown_hostGracefully shut down a host. Refuses while VMs are still running unless they are evacuated first -- disable_host with evacuate=true is the normal preceding step. Requires XO 6.6+.POSTclean_reboot_hostGracefully reboot a host. Same evacuation rules as clean_shutdown_host. Requires XO 6.6+.POSTsmart_reboot_hostSuspend the resident VMs, reboot the host, then resume the VMs in place -- no live migration needed. Preferred over clean_reboot_host when the pool has no spare capacity. Requires XO 6.6+.POSTrestart_toolstack_hostRestart the XAPI toolstack on a host. Running VMs keep running; the host is briefly unmanageable. Standard first remedy for a wedged XAPI. Requires XO 6.6+.POSTemergency_shutdown_hostSuspend all resident VMs and shut the host down immediately, without evacuation. For UPS-low / thermal events. Requires XO 6.6+.POSTdetach_hostEject a host from its pool and make it standalone again. The host must be running and its VMs relocated. Inverse of add_host_to_pool. Requires XO 6.6+.POSTforget_hostRemove a dead host's record from the pool database without contacting it. Only for hosts that are permanently gone -- if the host later comes back it will conflict with the pool. Requires XO 6.6+.POSTscan_pifs_hostRescan a host's physical NICs (XAPI PIF.scan) and create PIF objects for newly detected interfaces. The host must be RUNNING (409 otherwise). Idempotent on unchanged hardware. Requires XO 6.8+ (404 on older builds).POSTprobe_nfs_hostXO 6.10+ (404 on older builds). Ask the host to list the exports of an NFS server: returns [{path, acl}]. Use it to pick device_config.serverpath for create_sr (type nfs). Read-only on the storage side, but the host opens a connection to the given server. sync=true returns the list directly, otherwise poll the returned task.POSTprobe_nfs_exists_hostXO 6.10+ (404 on older builds). Check whether an NFS export already holds an SR known to XAPI: returns an array of SR UUIDs found there (empty = no SR yet, safe to create_sr; non-empty = reattach that SR instead of creating a new one). A serverPath the host cannot mount (e.g. not exported) is NOT answered with [] but with HTTP 500 SR_BACKEND_FAILURE_73 (NFS mount error) -- take the path from probe_nfs_host. sync=true returns the result directly.POSTprobe_iscsi_iqns_hostXO 6.10+ (404 on older builds). Discover the target IQNs offered by an iSCSI portal: returns [{iqn, ip}] (empty when the host cannot connect). First step of an iSCSI SR setup, followed by probe_iscsi_luns_host. XO masks chapPassword in the task record.POSTprobe_iscsi_luns_hostXO 6.10+ (404 on older builds). List the LUNs of one iSCSI target: returns [{id, vendor, serial, size, scsiId}]. The scsiId is device_config.SCSIid for create_sr (type lvmoiscsi) and the input of probe_iscsi_exists_host. XO masks chapPassword in the task record.POSTprobe_iscsi_exists_hostXO 6.10+ (404 on older builds). Check whether an iSCSI LUN already holds an SR known to XAPI: returns an array of SR UUIDs (empty = no SR on this LUN yet). Run it before create_sr so an existing SR is reattached instead of overwritten.POSTprobe_hba_hostXO 6.10+ (404 on older builds). List the LUNs visible through the host's HBAs (Fibre Channel / SAS): returns [{hba, id, lun, path, scsiId, serial, size, vendor}]. The scsiId is device_config.SCSIid for create_sr (type lvmohba).POSTprobe_hba_exists_hostXO 6.10+ (404 on older builds). Check whether an HBA LUN already holds an SR known to XAPI: returns an array of SR UUIDs (empty = no SR on this LUN yet).POSTprobe_zfs_hostXO 6.10+ (404 on older builds). List the ZFS pools of the host: returns an object {<poolname>: {<pool parameters>}} (empty when there is none). Use it to see which ZFS pools exist before creating a zfs SR with create_sr.GETlist_poolsList all poolsGETget_poolGet details of a poolGETget_pool_statsGet aggregated RRD statistics for the entire pool.GETget_pool_dashboardGet dashboard for a single pool (counts of VMs/hosts/SRs, usage).GETlist_pool_alarmsList XAPI alarms for the pool and its objects.GETlist_pool_missing_patchesAggregate of missing patches across all hosts in the pool.GETget_pool_rolling_update_recoveryXO 6.9+ (404 on older builds). Recovery status of an incomplete rolling pool update: run status (preparing|running|interrupted|resuming|failed|cleaning|succeeded), per-host step statuses, lastError, taskId and haltedPinnedVms (VM UUID -> UUID of the host it must be started on); or {status: 'blocked', blockedReason} when the record is unreadable. HTTP 404 means nothing to recover: the last rolling update completed, or the pool master is not XCP-ng / XenServer 8.4+ (no record is kept for older pools). Check it before rolling_update_pool (refused while a record exists) and before finalize_rolling_update_pool.GETlist_pool_messagesList XAPI messages for the pool.GETlist_pool_tasksList tasks scoped to the pool.PUTadd_pool_tagAdd a tag to a pool.DELETEremove_pool_tagRemove a tag from a pool.POSTcreate_vmCreate a new VM from a template. Body field names are mixed-case exactly as listed (autoPoweron, hvmBootFirmware, high_availability, cloud_config) -- XO rejects unknown fields. vCPU count and memory can be set here; cold-change fields (cpusStaticMax, memoryStaticMax) afterwards via update_vm.POSTemergency_shutdown_poolEmergency shutdown of all VMs and hosts in a poolPOSTrolling_reboot_poolSequentially reboot hosts with automatic VM migration; zero downtime for migratable VMs. Returns a task (poll with get_task). XO 6.9+: refused with HTTP 409 'incorrect state' while a backup job runs on the pool unless bypassBackupCheck=true, and VMs are moved back to their original host more reliably.POSTrolling_update_poolApply pending updates to hosts sequentially with live migration. Returns a task (poll with get_task). XO 6.9+: refused with HTTP 409 'incorrect state' while a backup job runs on the pool (bypassBackupCheck=true overrides), while a previous rolling update is still running, and -- on XCP-ng / XenServer 8.4+ pools -- while an interrupted run has not been closed with finalize_rolling_update_pool, or when the master is already up to date but other hosts are not (send acceptCurrentStateAsBaseline=true to continue from that state). XO 6.7/6.8 already refused a second concurrent run.POSTfinalize_rolling_update_poolXO 6.9+ (404 on older builds). Close the recovery record of an interrupted rolling pool update once the pool has been reviewed -- until then a new rolling_update_pool on this pool is refused. Refused with HTTP 409 'incorrect state' listing what the update changed and did not restore (HA, auto power-on, WLB, load balancer, backup schedules, disabled hosts, displaced or halted VMs) while any such item remains; displaced VMs alone are only listed. force=true closes it anyway: the items are abandoned and listed in the task, nothing is restored or changed in the pool. 404 when the pool has no recovery record (check get_pool_rolling_update_recovery first). Only XCP-ng / XenServer 8.4+ pools keep such records. Returns a task.POSTadd_host_to_poolMake a standalone host join this pool. The host must already be registered as a server in XO and be homogeneous with the pool master (CPU features, XCP-ng version) unless force is set. Requires XO 6.6+. Inverse of detach_host.POSTcreate_pool_networkCreate a basic network on a pool (attached to a single PIF). For aggregation use create_bonded_network; for isolated use create_internal_network.POSTcreate_bonded_networkCreate a bonded (link-aggregated) network across multiple PIFs in the pool.POSTcreate_internal_networkCreate an internal-only network (host-local, no physical PIF, useful for VM-to-VM private traffic). Body field names are name/description -- NOT name_label/name_description.POSTmanagement_reconfigure_poolReconfigure the management interface across all hosts in the pool. Coordinated equivalent of management_reconfigure_host -- but note this one takes a NETWORK id, while the host-level route takes a PIF id.GETlist_srsList all storage repositoriesGETget_srGet details of an SRPOSTcreate_srCreate a storage repository on a host. Requires XO 6.7+ (returns 404 on older builds). SR_type selects the driver -- shared/network types: nfs, smb, lvmoiscsi, lvmohba, lvmofcoe, hba, cephfs, glusterfs, moosefs, iso; local types: lvm, ext, file. device_config holds the driver-specific keys, e.g. nfs -> {server, serverpath}, smb -> {server, username, password}, lvmoiscsi -> {target, targetIQN, SCSIid}, lvm/ext -> {device}. Returns {id}.DELETEdelete_srDestroy an SR and all data on its underlying storage. Irreversible -- the SR must be detached/unplugged first. To keep the data, use forget_sr instead. Requires XO 6.5+ (DELETE /srs route returns 404 on older builds).GETlist_sr_alarmsList XAPI alarms for the SR (e.g. low free space).GETlist_sr_messagesList XAPI messages for the SR.GETlist_sr_tasksList tasks scoped to the SR.PUTadd_sr_tagAdd a tag to an SR.DELETEremove_sr_tagRemove a tag from an SR.POSTscan_srScan an SR to refresh its VDI list (detects manual changes on the underlying storage).POSTforget_srForget an SR (detach without destroying data on the underlying storage).POSTreclaim_space_srReclaim unused space on a thin-provisioned SR.GETlist_vdisList all virtual disk imagesGETget_vdiGet details of a VDIPOSTcreate_vdiCreate an empty VDI on an SR. Returns {id} (the new VDI UUID). The body uses XAPI names: srId and virtual_size (bytes) -- NOT sr/size (those are rejected with 422). Attach it to a VM with create_vbd.PATCHupdate_vdiPartially update a VDI: rename (name_label / name_description) or grow the disk (size). Only the fields you pass are changed. Added in XO 6.7 -- returns 404 on older builds. Size can only be increased, never shrunk.DELETEdelete_vdiDelete a VDI. Irreversible.GETlist_vdi_alarmsList XAPI alarms for the VDI.GETlist_vdi_messagesList XAPI messages for the VDI.GETlist_vdi_tasksList tasks scoped to the VDI.PUTadd_vdi_tagAdd a tag to a VDI.DELETEremove_vdi_tagRemove a tag from a VDI.POSTmigrate_vdiMigrate a VDI to a different SR (live storage migration)GETexport_vdi_vhdExport a VDI as VHD, whatever format the disk is stored in. Binary download. Since XO 6.9 the export reads the disk over NBD automatically when available and always sends content-length; the route has no NBD tuning query params. A disk larger than the VHD format limit (about 2 TiB) answers 422 -- export it as raw, qcow2 or vmdk instead.GETexport_vdi_rawExport a VDI as a raw disk image, whatever format the disk is stored in. Binary download; since XO 6.9 content-length is always sent. The route has no NBD tuning query params.GETexport_vdi_qcow2XO 6.9+ (older builds answer 422 'Invalid format'). Export a VDI as qcow2, whatever format the disk is stored in; reads over NBD when available and sends content-length. Binary download. Importing back is vhd/raw only (import_vdi_to_existing, import_vdi_to_sr).GETexport_vdi_vmdkXO 6.10+ (older builds answer 422 'Invalid format'). Export a VDI as VMDK (for VMware / other hypervisors), whatever format the disk is stored in. XO builds a sparse VMDK itself from the allocated disk blocks only (an empty 4 MiB disk gives ~15 KB), each grain padded so content-length is known up front -- the file is NOT shrunk to its compressed size. Binary download. Import back is vhd/raw only.POSTimport_vdi_to_srImport a VDI from VHD/raw upload into an SRPUTimport_vdi_to_existingReplace existing VDI contents (VHD format). Size must match exactly.PUTimport_vdi_to_existing_rawReplace existing VDI contents (raw format). Size must match exactly.GETlist_vdi_snapshotsList all VDI snapshots.GETget_vdi_snapshotGet details of a VDI snapshot.DELETEdelete_vdi_snapshotDelete a VDI snapshot. Irreversible.GETexport_vdi_snapshotExport a VDI snapshot as VHD, raw, (XO 6.9+) qcow2 or (XO 6.10+) vmdk. Format is the file extension; a format the build does not know answers 422 'Invalid format'. Binary download.GETlist_vdi_snapshot_alarmsList XAPI alarms scoped to a VDI snapshot.GETlist_vdi_snapshot_messagesList XAPI messages scoped to a VDI snapshot.GETlist_vdi_snapshot_tasksList tasks scoped to a VDI snapshot.PUTadd_vdi_snapshot_tagAdd a tag to a VDI snapshot.DELETEremove_vdi_snapshot_tagRemove a tag from a VDI snapshot.GETlist_vbdsList all VBDs (VDI-to-VM attachments).GETget_vbdGet details of a VBD.POSTcreate_vbdCreate a VBD to attach a VDI to a VM (both in the same pool). Field names are upper case: VM and VDI -- lower-case vm/vdi are rejected with 422. Returns {id}; plug it into a running VM with connect_vbd.DELETEdelete_vbdDelete a VBD (detach disk)GETlist_vbd_alarmsList XAPI alarms for the VBD.GETlist_vbd_messagesList XAPI messages for the VBD.GETlist_vbd_tasksList tasks scoped to the VBD.POSTconnect_vbdHotplug a VBD to a running VMPOSTdisconnect_vbdHot-unplug a VBD from a running VMGETlist_networksList all networksGETget_networkGet details of a networkDELETEdelete_networkDelete a networkGETlist_network_alarmsList XAPI alarms for the network.GETlist_network_messagesList XAPI messages for the network.GETlist_network_tasksList tasks scoped to the network.PUTadd_network_tagAdd a tag to a network.DELETEremove_network_tagRemove a tag from a network.GETlist_vifsList all virtual network interfaces.GETget_vifGet details of a VIF.POSTcreate_vifCreate a virtual network interface on a VM. The VM and network must belong to the same pool. Body fields use XAPI names (MTU, locking_mode, ipv4_allowed, other_config); XO rejects unknown fields with 422 -- there is no txChecksumming on create (use other_config 'ethtool-tx' or update_vif). Returns {id}.PATCHupdate_vifPartially update a VIF's properties (locking mode, allowed IPs, rate limit, TX checksumming). Only the fields you pass are changed. Added in XO 6.6 -- returns 404 on older builds. Does not move the VIF to another network; recreate it for that.DELETEdelete_vifDelete a virtual network interfacePOSTconnect_vifHotplug a VIF to a running VM (XO 6.4+).POSTdisconnect_vifHot-unplug a VIF from a running VM (XO 6.4+).GETlist_vif_alarmsList XAPI alarms for the VIF.GETlist_vif_messagesList XAPI messages for the VIF.GETlist_vif_tasksList tasks scoped to the VIF.GETlist_pluginsXO 6.10+ (404 on older builds). List the xo-server plugins. Returns hrefs unless fields is set, e.g. fields='id,name,version,loaded,autoload,configured,unloadable,testable' (avoid configurationSchema/testSchema in lists -- they are large JSON schemas). Secrets in configuration are obfuscated by XO. loaded is omitted (not false) for plugins that are not loaded; use filter='loaded?' for loaded plugins only.GETget_pluginXO 6.10+ (404 on older builds or unknown plugin). One plugin with its state (loaded, autoload, configured, unloadable, testable), version, current configuration (passwords, tokens and secrets obfuscated by XO), configurationSchema and -- for testable plugins -- testSchema describing the data test_plugin expects.PATCHupdate_pluginXO 6.10+. Set whether the plugin is loaded automatically when XO starts (autoload). Does not load or unload it now -- use load_plugin / unload_plugin for that. Returns 204.DELETEdelete_plugin_configurationXO 6.10+. Erase the stored configuration of a plugin (it becomes unconfigured and cannot be loaded until configured again in the XO UI). The plugin must be unloaded first -- 409 'incorrect state' while it is loaded. Irreversible: read get_plugin first if the settings must be kept.POSTload_pluginXO 6.10+. Load (start) a plugin. 409 'incorrect state' when it is already loaded, still loading or not configured. sync=true waits and returns 204, otherwise a task URL is returned.POSTunload_pluginXO 6.10+. Unload (stop) a plugin -- its feature is gone until it is loaded again (e.g. unloading 'sdn-controller' removes the traffic-rule routes, unloading an auth plugin stops that login method). 403 when the plugin is not unloadable, 409 when it is not loaded. sync=true waits and returns 204.POSTtest_pluginXO 6.10+. Run the plugin's self-test with its current configuration, e.g. send a test e-mail or chat message, or check a LDAP/NetBox connection. The plugin must be loaded (409 otherwise) and testable (403 otherwise). data is checked twice: against the known test inputs of all plugins (422 'Value does not match any allowed schema', also for an empty object {}) and against this plugin's testSchema (400 for unknown properties) -- omit data for plugins without a testSchema. sync=true waits and returns 204 on success or the plugin's error.POSTadd_network_traffic_ruleAdd a traffic (OpenFlow) rule to a private SDN network. Requires the SDN Controller plugin. (404 otherwise). XO 6.10+: an optional priority orders the rules -- of all network and VIF rules matching a packet, the highest priority applies; with the XAPI plugin only.POSTdelete_network_traffic_ruleRemove a traffic rule from a private SDN network. The rule is identified by allow + direction + ipRange + protocol + port (+ priority since XO 6.10) exactly as it was added. Since XO 6.9 a non-matching rule returns HTTP 404 (older builds returned 204 without deleting anything and ignored allow). Requires the SDN Controller plugin (404 otherwise).POSTupdate_network_traffic_ruleUpdate an existing traffic rule on a private SDN network. oldRule must contain the FULL existing rule (allow/direction/ipRange/protocol, plus port and -- XO 6.10+ -- priority if set) to identify it; newRule is a PARTIAL update -- only the fields you send change, and a field sent as null is REMOVED from the rule (XO 6.8+; before 6.8 e.g. the old port was silently kept). Added in XO 6.6. Requires the SDN Controller plugin (404 otherwise).POSTadd_vif_traffic_ruleAdd a traffic (OpenFlow) rule to a VIF connected to a private SDN network. Requires the SDN Controller plugin. (404 otherwise). XO 6.10+: an optional priority orders the rules -- of all network and VIF rules matching a packet, the highest priority applies; with the XAPI plugin only.POSTdelete_vif_traffic_ruleRemove a traffic rule from a VIF connected to a private SDN network. The rule is identified by allow + direction + ipRange + protocol + port (+ priority since XO 6.10) exactly as it was added. Since XO 6.9 a non-matching rule returns HTTP 404 (older builds returned 204 without deleting anything and ignored allow). Requires the SDN Controller plugin (404 otherwise).POSTupdate_vif_traffic_ruleUpdate an existing traffic rule on a VIF connected to a private SDN network. oldRule must contain the FULL existing rule (allow/direction/ipRange/protocol, plus port and -- XO 6.10+ -- priority if set) to identify it; newRule is a PARTIAL update -- only the fields you send change, and a field sent as null is REMOVED from the rule (XO 6.8+; before 6.8 e.g. the old port was silently kept). Added in XO 6.6. Requires the SDN Controller plugin (404 otherwise).GETget_host_ipmi_sensorsRaw IPMI sensor inventory of a host: {productName, systemManufacturer, sensors: [{name, value, event, dataType}]}. dataType is one of totalPower/inletTemp/outletTemp/cpuTemp/fanSpeed/fanStatus/psuPower/psuStatus/bmcStatus/ip/unknown -- 'unknown' sensors are included here (unlike the categorized XO5 view). Requires XO 6.8+ with the xo-server-ipmi-sensors plugin loaded (404 otherwise); returns 503 if the host has no reachable IPMI device -- treat 503 as a definitive answer, not a transient error.GETlist_audit_recordsList XO audit records (who called which API method with which params, from which IP), newest first. Requires the xo-server-audit plugin (404 otherwise; route documented in Swagger since XO 6.9). Without fields the result is a list of record hrefs; fields='*' returns full records {id, previousId, event, time (ms epoch), subject:{userId,userName,userIp}, data:{method,params}}. Page with limit plus from (id of the record to continue from). filter uses XO filter syntax, e.g. 'event:apiCall'. The host-level XAPI audit log is get_host_audit_log.GETget_audit_recordGet one XO audit record by id: {id, previousId, event, time, subject:{userId,userName,userIp}, data:{method,params}}. Requires the xo-server-audit plugin (404 otherwise, and 404 for unknown ids). Route documented in Swagger since XO 6.9.GETlist_pifsList all physical network interfacesGETget_pifGet details of a PIFGETlist_pif_alarmsList XAPI alarms for the PIF (e.g. link down).GETlist_pif_messagesList XAPI messages for the PIF.GETlist_pif_tasksList tasks scoped to the PIF.GETlist_pbdsList all PBDs (SR-to-host connections)GETget_pbdGet details of a PBDPOSTplug_pbdPlug a PBD to connect an SR to a hostPOSTunplug_pbdUnplug a PBD to disconnect an SR from a hostGETlist_pcisList all PCI devices (for passthrough)GETget_pciGet details of a PCI deviceGETlist_pgpusList all physical GPUsGETget_pgpuGet details of a physical GPUGETlist_smsList all storage manager plugins/driversGETget_smGet details of a storage manager pluginGETlist_tasksList all tasks. Use ndjson+watch for real-time streaming.GETget_taskGet a task. Set wait=true to block until the task finishes (long-poll), then return its final state.DELETEdelete_taskDelete a completed or failed taskDELETEdelete_tasksBulk delete: removes ALL tasks the current user has 'task:delete' privilege on. Irreversible.POSTabort_taskAbort a running taskGETlist_messagesList XAPI messages/alerts (e.g. HA alerts, license warnings)GETget_messageGet details of a XAPI messageGETlist_alarmsList all XAPI alarms (CPU, memory, disk, latency thresholds).GETget_alarmGet details of a single XAPI alarm.GETopen_events_streamOpen an SSE (Server-Sent Events) connection. The first event is 'init' and carries the connection id, i.e. the subscriber id for add_event_subscription / remove_event_subscription; afterwards ping (keepalive), add (object created), update (object changed), remove (object deleted). Since XO 6.9 subscriptions can also cover non-XAPI collections (users, groups, ACL roles/privileges, proxies, servers, backup repositories/jobs, schedules); XO 6.10 adds plugins, backup archives (backups appearing, merged or removed on a repository), backup logs and authentication tokens (each user only sees events about their own tokens and backup logs).POSTadd_event_subscriptionAdd an object-type subscription to an open SSE connection. Returns the subscription id (= collection name).DELETEremove_event_subscriptionRemove a subscription from an open SSE connection.GETlist_backupsList backup archives (restore points) stored on backup repositories. backup-repository is effectively REQUIRED: '*' lists every repository, or pass one repository id (from list_backup_repositories) -- without it XO answers an empty list (all versions). Archive ids contain slashes (e.g. '<repoId>//xo-vm-backups/<vmUuid>/<timestamp>.json') -- pass them to get_backup / mount_backup_live_disk exactly as returned; use fields=id,backupRepository,vm,timestamp,mode,disks for structured restore points. Filter example: filter='disks:length:>0'.GETget_backupGet details of a backup archive.POSTmount_backup_live_diskXO 6.9+ (404 on older builds), administrators only. Serve one disk of a backup archive as a read-only iSCSI LUN and attach it to a host as a new SR, so its content can be read (e.g. attach the VDI to a VM with create_vbd) WITHOUT restoring: nothing is copied, blocks are read from the backup repository on demand. diskId is one of the archive's disks[].id (see get_backup), hostId the host that receives the SR. With ?sync the result is {id, srUuid, vdiUuid, iqn, address, port} (HTTP 201) -- keep id: it is the liveDiskId for unmount_backup_live_disk. Without sync a task is returned. The mount is released automatically when the SR or the VM holding the disk is deleted; otherwise unmount it. XO's address must be reachable from the host (auto-detected, or set iscsi.advertisedAddress in the xo-server config).POSTunmount_backup_live_diskXO 6.9+ (404 on older builds), administrators only. Detach a disk mounted by mount_backup_live_disk: the SR is unplugged and forgotten and the iSCSI target is stopped. liveDiskId is the id returned by the mount; 404 if it does not belong to this archive. 204 on success (with ?sync), otherwise a task.GETlist_backup_jobsList all configured backup jobs (VM, metadata, mirror)GETget_backup_jobGet details of a backup job.GETlist_backup_logsList backup execution logsGETget_backup_logGet details of a single backup log entry.GETlist_restore_logsList restore execution logsGETget_restore_logGet details of a single restore log entry.GETlist_backup_repositoriesList all backup repositories (NFS, S3, SMB, local targets where backups are stored). Returns hrefs unless fields is set, e.g. fields='id,name,enabled,size,used,available'. Since XO 6.10 size/used/available (bytes) are stored on the repository object -- they are null or missing for a disabled repository and until XO has read the target's free space (at startup, after a backup changed it).GETget_backup_repositoryGet details of a backup repository: id, name, url (credentials masked by XO), enabled, options, benchmarks, error, and since XO 6.10 size/used/available in bytes (null/missing while disabled or not yet measured).POSTcreate_backup_repositoryRegister a new backup repository ('remote') where backups are written. Added in XO 6.6 (was read-only before). Returns {id}. The url encodes the backend type (nfs://, smb://, s3://, file://). Body is name, url, options (a string), proxy -- there is no enabled field on create (422); a new repository is enabled, use update_backup_repository to disable it.PATCHupdate_backup_repositoryUpdate a backup repository's properties (name, url, options, enabled). PATCH semantics -- only the fields you send change. Added in XO 6.6. Set enabled=false to stop new backups writing here without removing it.POSTforget_backup_repositoryRemove a backup repository registration from XO. Added in XO 6.6. Does NOT delete the backup data on the underlying storage. Fails if backup-jobs still reference it. Note: there is no DELETE /backup-repositories/{id} route -- this action IS the removal.GETget_backup_repository_healthCheck whether XO can reach and mount a backup repository. Returns {"success": true} when healthy; an unreachable or misconfigured repository reports the failure instead. Use this to validate a repository before pointing a backup job at it, or as a routine health check. Added in XO 6.6.POSTbenchmark_backup_repositoryMeasure read/write throughput of a backup repository by writing and reading back test data. Use it to investigate slow backups or to compare candidate targets. Runs for a while and writes to the repository -- prefer async (omit sync) and poll the returned task. Added in XO 6.6.POSTreclaim_space_backup_repositoryXO 6.9+ (404 on older builds; note the HYPHEN in reclaim-space, unlike the SR route). Reclaim space on a backup repository by running XO's per-VM cleanup: merge=true merges orphaned incremental chains, remove=true deletes backup disks that have no metadata left (both default true -- irreversible for that orphaned data; intact restore points are not touched). vmUuid limits the run to one VM (404 if that VM has no backups on this repository); without it every VM on the repository is cleaned. Refused with HTTP 409 while a backup job referencing the repository is running; 502 = repository unreachable. Proxied repositories are supported (10 min timeout). Long-running: omit sync and poll the returned task, whose result lists per-VM merge/size figures.GETlist_schedulesList all schedules (cron triggers attached to backup-jobs).GETget_scheduleGet details of a schedule (cron expression, jobId, enabled).POSTrun_scheduleManually trigger the backup-job behind this schedule (outside its cron). Returns task reference.GETlist_proxiesList all XO Proxy instancesGETget_proxyGet details of an XO ProxyGETlist_serversList all XCP-ng/XenServer connections registered in XO.GETget_serverGet details of a registered server (status, label, host, username).POSTadd_serverRegister a new XCP-ng/XenServer pool master in XO. Returns {id}. Use connect_server afterwards to establish the XAPI connection.DELETEdelete_serverRemove a XCP-ng/XenServer connection from XOPOSTconnect_serverEstablish the XAPI connection to a registered server.POSTdisconnect_serverDrop the XAPI connection to a registered server (without removing it from XO).GETlist_server_tasksList tasks scoped to this server connection.