xen-orchestra
xen-orchestra
Xen Orchestra REST API (XO 6.4+) -- complete coverage: VMs, hosts, pools, storage (SR/VDI/VBD), networks (VIF/PIF/PBD), VM/VDI snapshots, VM templates, hardware (PCI/PGPU/SM), tasks, backups (jobs/logs/repositories/restore), schedules, messages, alarms, events (SSE), RBAC v2 (users/groups/acl-roles/acl-privileges), proxies, servers, dashboards, auth tokens, health check
Source: Xen Orchestra REST API
Coverage
100% (229 of ~229 endpoints)
Focus: Complete REST API coverage for XO 6.4+: all object types (VMs, VM templates, VM snapshots, hosts, pools, SRs, VDIs, VDI snapshots, VBDs, networks, VIFs, PIFs, PBDs, PCIs, PGPUs, SMs), all lifecycle actions (CRUD, power, snapshot/clone/migrate, export/import, hotplug), full sub-resource access (alarms, messages, tasks, tags, stats per object), RBAC v2 (users, groups, acl-roles, acl-privileges), backups (archives, jobs, logs, restore-logs, repositories, schedules), real-time events via SSE, host/pool maintenance ops (rolling reboot/update, management reconfigure, audit logs, missing patches), XOA appliance (dashboard, ping, gui-routes). 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 + import_vdi_to_existing + import_vdi_to_existing_raw).
Missing: Generic PATCH /vms/{id} and PATCH /vdis/{id} -- the typed REST API does not yet expose XAPI property writes (use tags or JSON-RPC for renames). SDN-controller plugin endpoints (network/VIF traffic rules under /plugins/sdn-controller/*) -- only available when xo-server-sdn-controller plugin is installed; deprecated routes (POST /users/authentication_tokens, GET /backup/jobs/vm/*, GET /restore/logs/*) intentionally excluded -- removal scheduled for 2026-09-12 / 2026-10-13
Setup
- 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.
Install
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-hereTools (229)
GET ping Health check. Unauthenticated. Returns {result: 'pong', timestamp}. Use this to verify the XO instance is reachable before trying authenticated calls. GET get_dashboard Aggregated 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. GET get_gui_routes Returns the URLs of the legacy XO5 (xo5) and modern XO6 (xo6) web UIs. Useful for clients that need to deep-link into the GUI. GET list_users List all users. Returns URLs by default; use fields for objects. Requires user:read privilege. GET get_user Get 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. POST create_user Create a new user. Returns {id} of the created user. Requires user:create privilege. PATCH update_user Update user properties. Cannot change own permission. Synchronized users (LDAP/SAML/OIDC) cannot have name/password changed. DELETE delete_user Delete a user. Irreversible. Requires user:delete privilege. GET list_user_groups List groups the user is a member of (filtered by group:read privilege). Use id='me' for self. GET list_user_tasks List tasks owned by the user (filtered by task:read privilege). Use id='me' for self. GET list_user_acl_privileges List 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. GET list_auth_tokens List all authentication tokens for a user. Use id='me' for self. POST create_auth_token Create a new authentication token. You can only create tokens for yourself (use id='me'). Returns {token} including the secret (store it securely; cannot be retrieved later). GET list_groups List all groups (filtered by group:read privilege). GET get_group Get details of a single group. POST create_group Create a new group. Returns {id} of the created group. PATCH update_group Update group properties (currently only name). DELETE delete_group Delete a group. Irreversible. Removes all role attachments to this group. PUT add_user_to_group Add a user to a group. DELETE remove_user_from_group Remove a user from a group. GET list_group_users List users that are members of the group. GET list_group_tasks List tasks associated with members of the group. GET list_acl_roles List all RBAC v2 roles. A role groups privileges and can be attached to users/groups. GET get_acl_role Get details of a single role. POST create_acl_role Create a new RBAC role. Returns {id}. Add privileges via POST /acl-privileges (with roleId), then attach to users/groups. PATCH update_acl_role Update a role's name and/or description (set description to null to clear). DELETE delete_acl_role Delete a role. Irreversible. All attachments to users/groups are removed; privileges referencing this role are also dropped. POST copy_acl_role Duplicate a role (and its privileges) under a new name. Useful for deriving custom roles from built-in ones. GET list_acl_role_privileges List all acl-privileges attached to this role. PUT attach_acl_role_to_group Attach an RBAC role to a group. All members of the group inherit the role's privileges. DELETE detach_acl_role_from_group Detach an RBAC role from a group. PUT attach_acl_role_to_user Attach an RBAC role directly to a user (in addition to roles inherited via groups). DELETE detach_acl_role_from_user Detach an RBAC role from a user. GET list_acl_privileges List all RBAC v2 privileges (each privilege = role + resource + action, optionally scoped by object). GET get_acl_privilege Get details of a single privilege. POST create_acl_privilege Grant a new privilege (action on a resource type, optionally scoped to a specific object) to a role. Returns {id}. Body fields depend on the resource type -- see Swagger /rest/v0/docs for the privilege schema. PATCH update_acl_privilege Update a privilege's resource/action/objectId (roleId is immutable). DELETE delete_acl_privilege Revoke a privilege. Irreversible. GET list_vms List all VMs. Returns URLs by default; use fields for objects. GET get_vm Get full details of a VM DELETE delete_vm Destroy a VM and its VDIs. Irreversible. POST start_vm Start a halted VM. Optionally pin to a specific host via body.hostId. POST clean_shutdown_vm Gracefully shut down a VM (ACPI shutdown) POST hard_shutdown_vm Force shutdown a VM immediately (equivalent to pulling the plug) POST clean_reboot_vm Gracefully reboot a VM (ACPI reboot) POST hard_reboot_vm Force reboot a VM immediately POST pause_vm Pause a running VM (freezes CPU, keeps memory) POST unpause_vm Unpause a paused VM POST suspend_vm Suspend a VM to disk (saves memory state, frees RAM) POST resume_vm Resume a suspended VM from disk POST snapshot_vm Create a snapshot of a VM. Returns task reference; use ?sync to get the snapshot id directly. POST clone_vm Clone 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). POST migrate_vm Live-migrate a VM to another host. Supports cross-SR storage migration via srId. GET export_vm_xva Export a VM as XVA (XCP-ng native format). Streamed binary download. GET export_vm_ova Export a VM as OVA (Open Virtualization Format, portable across hypervisors). POST import_vm_xva Import a VM from XVA upload into a pool. Body is the raw XVA stream. GET get_vm_stats Get RRD statistics for a VM (CPU, memory, network, disk). VM must be running. PUT add_vm_data_source Enable a specific RRD data source on a VM (e.g. cpu0, vif_0_rx). VM must be running. DELETE delete_vm_data_source Disable / forget a specific RRD data source on a VM. PUT add_vm_tag Add a tag to a VM DELETE remove_vm_tag Remove a tag from a VM GET list_vm_vdis List all VDIs attached to a VM GET list_vm_alarms List XAPI alarms (performance/health thresholds) for the VM. GET list_vm_messages List XAPI messages/alerts emitted for the VM. GET list_vm_tasks List tasks scoped to this VM (running/completed/failed). GET list_vm_backup_jobs List backup-jobs that include this VM. GET get_vm_dashboard Get dashboard/statistics for a VM (aggregate metrics). GET list_vm_snapshots List all VM snapshots GET get_vm_snapshot Get details of a VM snapshot DELETE delete_vm_snapshot Delete a VM snapshot. Irreversible. GET export_vm_snapshot Export a VM snapshot as XVA or OVA. Format is the file extension ('xva' or 'ova'). GET list_vm_snapshot_vdis List VDIs belonging to a VM snapshot. GET list_vm_snapshot_alarms List XAPI alarms scoped to a VM snapshot. GET list_vm_snapshot_messages List XAPI messages scoped to a VM snapshot. GET list_vm_snapshot_tasks List tasks scoped to a VM snapshot. PUT add_vm_snapshot_tag Add a tag to a VM snapshot. DELETE remove_vm_snapshot_tag Remove a tag from a VM snapshot. GET list_vm_templates List all VM templates. Templates are stamps from which create_vm produces new VMs. GET get_vm_template Get details of a VM template. DELETE delete_vm_template Delete a VM template. Irreversible. Built-in templates may be protected. GET export_vm_template Export a VM template as XVA or OVA. GET list_vm_template_vdis List VDIs belonging to a VM template. GET list_vm_template_alarms List XAPI alarms scoped to a VM template. GET list_vm_template_messages List XAPI messages scoped to a VM template. GET list_vm_template_tasks List tasks scoped to a VM template. PUT add_vm_template_tag Add a tag to a VM template. DELETE remove_vm_template_tag Remove a tag from a VM template. GET list_hosts List all XCP-ng/XenServer hosts GET get_host Get details of a host GET get_host_stats Get RRD statistics for a host (CPU, memory, NIC, disk). Host must be enabled. GET get_host_audit_log Download the host's audit log as plain text. Useful for compliance and forensics. GET get_host_logs Download the host's full logs as a gzipped tarball. Useful for support tickets and debugging. GET list_host_alarms List XAPI alarms (performance/health thresholds) for the host. GET get_host_smt Get the SMT (Simultaneous Multi-Threading / Hyper-Threading) status of the host. GET list_host_missing_patches List all patches/updates that are available but not yet installed on the host. GET list_host_messages List XAPI messages/alerts emitted for the host. GET list_host_tasks List tasks scoped to this host (running/completed/failed). PUT add_host_tag Add a tag to a host. DELETE remove_host_tag Remove a tag from a host. POST management_reconfigure_host Move the management interface (control plane) to a different PIF. May briefly disconnect XO from the host. POST disable_host Disable a host (prepare for maintenance). Optionally evacuate VMs in the same call (body.evacuate=true, optional force/vmIdsToForceMigrate). POST enable_host Re-enable a disabled host GET list_pools List all pools GET get_pool Get details of a pool GET get_pool_stats Get aggregated RRD statistics for the entire pool. GET get_pool_dashboard Get dashboard for a single pool (counts of VMs/hosts/SRs, usage). GET list_pool_alarms List XAPI alarms for the pool and its objects. GET list_pool_missing_patches Aggregate of missing patches across all hosts in the pool. GET list_pool_messages List XAPI messages for the pool. GET list_pool_tasks List tasks scoped to the pool. PUT add_pool_tag Add a tag to a pool. DELETE remove_pool_tag Remove a tag from a pool. POST create_vm Create a new VM from a template POST emergency_shutdown_pool Emergency shutdown of all VMs and hosts in a pool POST rolling_reboot_pool Sequentially reboot hosts with automatic VM migration. Zero downtime. POST rolling_update_pool Apply updates to hosts sequentially with live migration POST create_pool_network Create a basic network on a pool (attached to a single PIF). For aggregation use create_bonded_network; for isolated use create_internal_network. POST create_bonded_network Create a bonded (link-aggregated) network across multiple PIFs in the pool. POST create_internal_network Create an internal-only network (host-local, no physical PIF, useful for VM-to-VM private traffic) POST management_reconfigure_pool Reconfigure the management interface across all hosts in the pool. Coordinated equivalent of management_reconfigure_host. GET list_srs List all storage repositories GET get_sr Get details of an SR GET list_sr_alarms List XAPI alarms for the SR (e.g. low free space). GET list_sr_messages List XAPI messages for the SR. GET list_sr_tasks List tasks scoped to the SR. PUT add_sr_tag Add a tag to an SR. DELETE remove_sr_tag Remove a tag from an SR. POST scan_sr Scan an SR to refresh its VDI list (detects manual changes on the underlying storage). POST forget_sr Forget an SR (detach without destroying data on the underlying storage). POST reclaim_space_sr Reclaim unused space on a thin-provisioned SR. GET list_vdis List all virtual disk images GET get_vdi Get details of a VDI POST create_vdi Create a new VDI DELETE delete_vdi Delete a VDI. Irreversible. GET list_vdi_alarms List XAPI alarms for the VDI. GET list_vdi_messages List XAPI messages for the VDI. GET list_vdi_tasks List tasks scoped to the VDI. PUT add_vdi_tag Add a tag to a VDI. DELETE remove_vdi_tag Remove a tag from a VDI. POST migrate_vdi Migrate a VDI to a different SR (live storage migration) GET export_vdi_vhd Export a VDI as VHD GET export_vdi_raw Export a VDI as raw disk image POST import_vdi_to_sr Import a VDI from VHD/raw upload into an SR PUT import_vdi_to_existing Replace existing VDI contents (VHD format). Size must match exactly. PUT import_vdi_to_existing_raw Replace existing VDI contents (raw format). Size must match exactly. GET list_vdi_snapshots List all VDI snapshots. GET get_vdi_snapshot Get details of a VDI snapshot. DELETE delete_vdi_snapshot Delete a VDI snapshot. Irreversible. GET export_vdi_snapshot Export a VDI snapshot as VHD or raw. Format is the file extension ('vhd' or 'raw'). GET list_vdi_snapshot_alarms List XAPI alarms scoped to a VDI snapshot. GET list_vdi_snapshot_messages List XAPI messages scoped to a VDI snapshot. GET list_vdi_snapshot_tasks List tasks scoped to a VDI snapshot. PUT add_vdi_snapshot_tag Add a tag to a VDI snapshot. DELETE remove_vdi_snapshot_tag Remove a tag from a VDI snapshot. GET list_vbds List all VBDs (VDI-to-VM attachments). GET get_vbd Get details of a VBD. POST create_vbd Create a VBD to attach a VDI to a VM DELETE delete_vbd Delete a VBD (detach disk) GET list_vbd_alarms List XAPI alarms for the VBD. GET list_vbd_messages List XAPI messages for the VBD. GET list_vbd_tasks List tasks scoped to the VBD. POST connect_vbd Hotplug a VBD to a running VM POST disconnect_vbd Hot-unplug a VBD from a running VM GET list_networks List all networks GET get_network Get details of a network DELETE delete_network Delete a network GET list_network_alarms List XAPI alarms for the network. GET list_network_messages List XAPI messages for the network. GET list_network_tasks List tasks scoped to the network. PUT add_network_tag Add a tag to a network. DELETE remove_network_tag Remove a tag from a network. GET list_vifs List all virtual network interfaces. GET get_vif Get details of a VIF. POST create_vif Create a virtual network interface on a VM. The VM and network must belong to the same pool. DELETE delete_vif Delete a virtual network interface POST connect_vif Hotplug a VIF to a running VM (XO 6.4+). POST disconnect_vif Hot-unplug a VIF from a running VM (XO 6.4+). GET list_vif_alarms List XAPI alarms for the VIF. GET list_vif_messages List XAPI messages for the VIF. GET list_vif_tasks List tasks scoped to the VIF. GET list_pifs List all physical network interfaces GET get_pif Get details of a PIF GET list_pif_alarms List XAPI alarms for the PIF (e.g. link down). GET list_pif_messages List XAPI messages for the PIF. GET list_pif_tasks List tasks scoped to the PIF. GET list_pbds List all PBDs (SR-to-host connections) GET get_pbd Get details of a PBD POST plug_pbd Plug a PBD to connect an SR to a host POST unplug_pbd Unplug a PBD to disconnect an SR from a host GET list_pcis List all PCI devices (for passthrough) GET get_pci Get details of a PCI device GET list_pgpus List all physical GPUs GET get_pgpu Get details of a physical GPU GET list_sms List all storage manager plugins/drivers GET get_sm Get details of a storage manager plugin GET list_tasks List all tasks. Use ndjson+watch for real-time streaming. GET get_task Get a task. Use wait=result to block until completion. DELETE delete_task Delete a completed or failed task DELETE delete_tasks Bulk delete: removes ALL tasks the current user has 'task:delete' privilege on. Irreversible. POST abort_task Abort a running task GET list_messages List XAPI messages/alerts (e.g. HA alerts, license warnings) GET get_message Get details of a XAPI message GET list_alarms List all XAPI alarms (CPU, memory, disk, latency thresholds). GET get_alarm Get details of a single XAPI alarm. GET open_events_stream Open an SSE (Server-Sent Events) connection. Returns a subscriber id which is used to add/remove subscriptions. Events emitted: ping (keepalive), add (object created), update (object changed), remove (object deleted). POST add_event_subscription Add an object-type subscription to an open SSE connection. Returns the subscription id (= collection name). DELETE remove_event_subscription Remove a subscription from an open SSE connection. GET list_backups List all backup archives GET get_backup Get details of a backup archive. GET list_backup_jobs List all configured backup jobs (VM, metadata, mirror) GET get_backup_job Get details of a backup job. GET list_backup_logs List backup execution logs GET get_backup_log Get details of a single backup log entry. GET list_restore_logs List restore execution logs GET get_restore_log Get details of a single restore log entry. GET list_backup_repositories List all backup repositories (NFS, S3, SMB, local targets where backups are stored). GET get_backup_repository Get details of a backup repository (capacity, type, status). GET list_schedules List all schedules (cron triggers attached to backup-jobs). GET get_schedule Get details of a schedule (cron expression, jobId, enabled). POST run_schedule Manually trigger the backup-job behind this schedule (outside its cron). Returns task reference. GET list_proxies List all XO Proxy instances GET get_proxy Get details of an XO Proxy GET list_servers List all XCP-ng/XenServer connections registered in XO. GET get_server Get details of a registered server (status, label, host, username). POST add_server Register a new XCP-ng/XenServer pool master in XO. Returns {id}. Use connect_server afterwards to establish the XAPI connection. DELETE delete_server Remove a XCP-ng/XenServer connection from XO POST connect_server Establish the XAPI connection to a registered server. POST disconnect_server Drop the XAPI connection to a registered server (without removing it from XO). GET list_server_tasks List tasks scoped to this server connection.