openapi: 3.1.0
info:
title: VMware vSphere Automation REST API
description: >-
RESTful API for managing VMware vSphere virtualization platform resources
including virtual machines, hosts, datastores, clusters, networks, and
related infrastructure. The vSphere Automation API provides modern REST
endpoints for vCenter Server operations using JSON payloads and session-based
or OAuth authentication. This API supersedes the legacy SOAP-based vSphere
Web Services API for most automation use cases.
version: '8.0'
contact:
name: Broadcom Developer Support
url: https://developer.broadcom.com/
license:
name: Proprietary
url: https://www.broadcom.com/company/legal/terms-of-use
termsOfService: https://www.broadcom.com/company/legal/terms-of-use
externalDocs:
description: vSphere Automation API Reference on Broadcom Developer Portal
url: https://developer.broadcom.com/xapis/vsphere-automation-api/latest/
servers:
- url: https://{vcenter}/api
description: vCenter Server REST API endpoint
variables:
vcenter:
default: vcenter.example.com
description: Hostname or IP address of your vCenter Server instance
tags:
- name: Clusters
description: >-
Cluster management for compute resource grouping, DRS, and HA
configuration
- name: Content Library
description: >-
Content library management for templates, ISOs, and OVF packages
shared across vCenter instances
- name: Datacenters
description: Datacenter management for organizing vSphere inventory
- name: Datastores
description: >-
Datastore management including browsing, capacity monitoring, and
storage configuration
- name: Folders
description: Inventory folder management for organizing vSphere objects
- name: Hosts
description: >-
ESXi host management including connection state, maintenance mode,
and host configuration
- name: Networks
description: >-
Virtual network management including standard and distributed port
groups and network connectivity
- name: Resource Pools
description: Resource pool management for allocating compute resources
- name: Session
description: Authentication session management for the vSphere REST API
- name: Storage Policies
description: >-
VM storage policy management for defining storage requirements and
compliance
- name: Tagging
description: >-
Tag and category management for organizing and classifying vSphere
inventory objects
- name: VM Guest
description: >-
Guest operating system operations including identity, networking,
local filesystem, and process management via VMware Tools
- name: VM Hardware
description: >-
Virtual machine hardware configuration including CPU, memory, disks,
network adapters, CD-ROMs, and other virtual devices
- name: VM Power
description: >-
Virtual machine power state operations including power on, power off,
suspend, reset, and guest shutdown
- name: VMs
description: >-
Virtual machine lifecycle management including creation, power operations,
cloning, migration, and configuration
security:
- sessionAuth: []
- basicAuth: []
paths:
/session:
post:
operationId: createSession
summary: Vmware Create a New Authentication Session
description: >-
Creates a new session by authenticating with vCenter Server credentials.
Returns a session identifier that must be included in the
vmware-api-session-id header for subsequent requests.
tags:
- Session
security:
- basicAuth: []
responses:
'201':
description: Session created successfully
content:
application/json:
schema:
type: string
description: Session identifier token
examples:
Createsession201Example:
summary: Default createSession 201 response
x-microcks-default: true
value: example_value
'401':
description: Authentication failed - invalid credentials
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSession
summary: Vmware Terminate the Current Session
description: >-
Terminates the current authenticated session and invalidates the
session token.
tags:
- Session
responses:
'204':
description: Session terminated successfully
'401':
description: Not authenticated
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
operationId: getSessionInfo
summary: Vmware Get Current Session Information
description: >-
Returns information about the currently authenticated session
including the authenticated user.
tags:
- Session
responses:
'200':
description: Session information returned
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInfo'
examples:
Getsessioninfo200Example:
summary: Default getSessionInfo 200 response
x-microcks-default: true
value:
user: example_value
created_time: '2026-01-15T10:30:00Z'
last_accessed_time: '2026-01-15T10:30:00Z'
'401':
description: Not authenticated
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm:
get:
operationId: listVMs
summary: Vmware List Virtual Machines
description: >-
Returns a list of virtual machines in the vCenter inventory matching
the specified filter criteria. Results can be filtered by name,
power state, host, cluster, datacenter, folder, and resource pool.
tags:
- VMs
parameters:
- name: filter.vms
in: query
description: Identifiers of VMs to filter by
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.names
in: query
description: Names of VMs to filter by (exact match)
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.folders
in: query
description: Folders that must contain the VMs
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.datacenters
in: query
description: Datacenters that must contain the VMs
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.hosts
in: query
description: Hosts that must contain the VMs
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.clusters
in: query
description: Clusters that must contain the VMs
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.resource_pools
in: query
description: Resource pools that must contain the VMs
schema:
type: array
items:
type: string
style: form
explode: true
example: []
- name: filter.power_states
in: query
description: Power states to filter by
schema:
type: array
items:
type: string
enum:
- POWERED_ON
- POWERED_OFF
- SUSPENDED
style: form
explode: true
example: []
responses:
'200':
description: List of virtual machines matching the filter
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VMSummary'
examples:
Listvms200Example:
summary: Default listVMs 200 response
x-microcks-default: true
value:
- vm: example_value
name: Example Title
power_state: POWERED_ON
cpu_count: 10
memory_size_MiB: 10
'400':
description: Invalid filter parameters
'401':
description: Not authenticated
'403':
description: Insufficient privileges
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createVM
summary: Vmware Create a New Virtual Machine
description: >-
Creates a new virtual machine with the specified configuration.
The VM is created in the powered-off state and must be explicitly
powered on after creation.
tags:
- VMs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VMCreateSpec'
examples:
CreatevmRequestExample:
summary: Default createVM request
x-microcks-default: true
value:
name: Example Title
guest_OS: RHEL_9_64
placement:
folder: example_value
host: example_value
cluster: example_value
resource_pool: example_value
datastore: example_value
hardware_version: VMX_21
cpu:
count: 10
cores_per_socket: 10
hot_add_enabled: true
hot_remove_enabled: true
memory:
size_MiB: 10
hot_add_enabled: true
disks:
- type: IDE
new_vmdk: {}
backing: {}
nics:
- type: E1000
mac_type: MANUAL
mac_address: example_value
backing: {}
start_connected: true
allow_guest_control: true
wake_on_lan_enabled: true
boot:
type: BIOS
efi_legacy_boot: true
delay: 10
enter_setup_mode: true
responses:
'201':
description: Virtual machine created successfully
content:
application/json:
schema:
type: string
description: Identifier of the newly created VM (e.g., vm-123)
examples:
Createvm201Example:
summary: Default createVM 201 response
x-microcks-default: true
value: example_value
'400':
description: Invalid VM specification
'401':
description: Not authenticated
'403':
description: Insufficient privileges
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}:
get:
operationId: getVM
summary: Vmware Get Virtual Machine Details
description: >-
Returns detailed information about the specified virtual machine
including hardware configuration, power state, guest OS, and
storage information.
tags:
- VMs
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Virtual machine details
content:
application/json:
schema:
$ref: '#/components/schemas/VMInfo'
examples:
Getvm200Example:
summary: Default getVM 200 response
x-microcks-default: true
value:
name: Example Title
identity:
name: Example Title
instance_uuid: '500123'
bios_uuid: '500123'
power_state: POWERED_ON
guest_OS: example_value
hardware:
version: example_value
upgrade_policy: NEVER
upgrade_version: example_value
boot:
type: BIOS
delay: 10
enter_setup_mode: true
cpu:
count: 10
cores_per_socket: 10
hot_add_enabled: true
hot_remove_enabled: true
memory:
size_MiB: 10
hot_add_enabled: true
hot_add_increment_size_MiB: 10
hot_add_limit_MiB: 10
disks: example_value
nics: example_value
cdroms: example_value
parallel_ports: example_value
serial_ports: example_value
floppy_drives: example_value
'401':
description: Not authenticated
'403':
description: Insufficient privileges
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteVM
summary: Vmware Delete a Virtual Machine
description: >-
Permanently deletes the specified virtual machine and all
associated virtual disks. The VM must be in a powered-off state.
tags:
- VMs
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'204':
description: Virtual machine deleted successfully
'400':
description: VM is not in a powered-off state
'401':
description: Not authenticated
'403':
description: Insufficient privileges
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/power:
get:
operationId: getVMPowerState
summary: Vmware Get Vm Power State
description: Returns the current power state of the specified virtual machine.
tags:
- VM Power
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Current power state
content:
application/json:
schema:
$ref: '#/components/schemas/PowerInfo'
examples:
Getvmpowerstate200Example:
summary: Default getVMPowerState 200 response
x-microcks-default: true
value:
state: POWERED_ON
clean_power_off: true
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/power?action=start:
post:
operationId: powerOnVM
summary: Vmware Power on a Virtual Machine
description: >-
Powers on the specified virtual machine. The VM must be in a
powered-off or suspended state.
tags:
- VM Power
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'204':
description: Power on initiated successfully
'400':
description: VM is already powered on
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/power?action=stop:
post:
operationId: powerOffVM
summary: Vmware Power Off a Virtual Machine
description: >-
Powers off the specified virtual machine immediately. This is
equivalent to pulling the power cord and does not perform a
graceful guest OS shutdown. Use the guest shutdown operation
for a clean shutdown.
tags:
- VM Power
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'204':
description: Power off initiated successfully
'400':
description: VM is already powered off
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/power?action=suspend:
post:
operationId: suspendVM
summary: Vmware Suspend a Virtual Machine
description: >-
Suspends the specified virtual machine, saving its current state
to disk. The VM can be resumed later from the suspended state.
tags:
- VM Power
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'204':
description: Suspend initiated successfully
'400':
description: VM is not in a powered-on state
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/power?action=reset:
post:
operationId: resetVM
summary: Vmware Reset a Virtual Machine
description: >-
Resets the specified virtual machine. This is equivalent to
pressing the reset button and does not perform a graceful
guest OS reboot.
tags:
- VM Power
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'204':
description: Reset initiated successfully
'400':
description: VM is not in a powered-on state
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/hardware:
get:
operationId: getVMHardware
summary: Vmware Get Vm Hardware Configuration
description: >-
Returns the full virtual hardware configuration of the specified
virtual machine including CPU, memory, and all virtual devices.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Hardware configuration returned
content:
application/json:
schema:
$ref: '#/components/schemas/HardwareInfo'
examples:
Getvmhardware200Example:
summary: Default getVMHardware 200 response
x-microcks-default: true
value:
version: example_value
upgrade_policy: NEVER
upgrade_version: example_value
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateVMHardware
summary: Vmware Update Vm Hardware Configuration
description: >-
Updates the virtual hardware configuration. Some changes require
the VM to be powered off.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HardwareUpdateSpec'
examples:
UpdatevmhardwareRequestExample:
summary: Default updateVMHardware request
x-microcks-default: true
value:
upgrade_policy: NEVER
upgrade_version: example_value
responses:
'204':
description: Hardware updated successfully
'400':
description: Invalid hardware specification
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/hardware/cpu:
get:
operationId: getVMCpu
summary: Vmware Get Vm Cpu Configuration
description: Returns the CPU configuration of the specified virtual machine.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: CPU configuration returned
content:
application/json:
schema:
$ref: '#/components/schemas/CpuInfo'
examples:
Getvmcpu200Example:
summary: Default getVMCpu 200 response
x-microcks-default: true
value:
count: 10
cores_per_socket: 10
hot_add_enabled: true
hot_remove_enabled: true
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateVMCpu
summary: Vmware Update Vm Cpu Configuration
description: >-
Updates the CPU configuration. Hot-add of CPUs is supported if the
VM and guest OS support it and the VM is powered on.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CpuUpdateSpec'
examples:
UpdatevmcpuRequestExample:
summary: Default updateVMCpu request
x-microcks-default: true
value:
count: 10
cores_per_socket: 10
hot_add_enabled: true
hot_remove_enabled: true
responses:
'204':
description: CPU configuration updated
'400':
description: Invalid CPU specification
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/hardware/memory:
get:
operationId: getVMMemory
summary: Vmware Get Vm Memory Configuration
description: Returns the memory configuration of the specified virtual machine.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Memory configuration returned
content:
application/json:
schema:
$ref: '#/components/schemas/MemoryInfo'
examples:
Getvmmemory200Example:
summary: Default getVMMemory 200 response
x-microcks-default: true
value:
size_MiB: 10
hot_add_enabled: true
hot_add_increment_size_MiB: 10
hot_add_limit_MiB: 10
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateVMMemory
summary: Vmware Update Vm Memory Configuration
description: >-
Updates the memory configuration. Hot-add of memory is supported
if the VM and guest OS support it and the VM is powered on.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MemoryUpdateSpec'
examples:
UpdatevmmemoryRequestExample:
summary: Default updateVMMemory request
x-microcks-default: true
value:
size_MiB: 10
hot_add_enabled: true
responses:
'204':
description: Memory configuration updated
'400':
description: Invalid memory specification
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/hardware/disk:
get:
operationId: listVMDisks
summary: Vmware List Vm Virtual Disks
description: Returns a list of virtual disks attached to the specified VM.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: List of virtual disks
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DiskSummary'
examples:
Listvmdisks200Example:
summary: Default listVMDisks 200 response
x-microcks-default: true
value:
- disk: example_value
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createVMDisk
summary: Vmware Add a Virtual Disk to a Vm
description: >-
Creates and attaches a new virtual disk to the specified VM.
Supports creating new VMDK files or attaching existing ones.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DiskCreateSpec'
examples:
CreatevmdiskRequestExample:
summary: Default createVMDisk request
x-microcks-default: true
value:
type: IDE
new_vmdk:
name: Example Title
capacity: 10
storage_policy:
policy: example_value
backing:
type: VMDK_FILE
vmdk_file: example_value
responses:
'201':
description: Disk created and attached successfully
content:
application/json:
schema:
type: string
description: Identifier of the new virtual disk
examples:
Createvmdisk201Example:
summary: Default createVMDisk 201 response
x-microcks-default: true
value: example_value
'400':
description: Invalid disk specification
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/hardware/ethernet:
get:
operationId: listVMEthernet
summary: Vmware List Vm Network Adapters
description: >-
Returns a list of virtual Ethernet adapters attached to the
specified virtual machine.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: List of network adapters
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EthernetSummary'
examples:
Listvmethernet200Example:
summary: Default listVMEthernet 200 response
x-microcks-default: true
value:
- nic: example_value
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createVMEthernet
summary: Vmware Add a Network Adapter to a Vm
description: >-
Creates and attaches a new virtual Ethernet adapter to the
specified virtual machine.
tags:
- VM Hardware
parameters:
- $ref: '#/components/parameters/vmId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EthernetCreateSpec'
examples:
CreatevmethernetRequestExample:
summary: Default createVMEthernet request
x-microcks-default: true
value:
type: E1000
mac_type: MANUAL
mac_address: example_value
backing:
type: STANDARD_PORTGROUP
network: example_value
start_connected: true
allow_guest_control: true
wake_on_lan_enabled: true
responses:
'201':
description: Network adapter created successfully
content:
application/json:
schema:
type: string
description: Identifier of the new network adapter
examples:
Createvmethernet201Example:
summary: Default createVMEthernet 201 response
x-microcks-default: true
value: example_value
'400':
description: Invalid adapter specification
'401':
description: Not authenticated
'404':
description: Virtual machine not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/guest/identity:
get:
operationId: getVMGuestIdentity
summary: Vmware Get Guest Os Identity
description: >-
Returns guest operating system identity information reported by
VMware Tools running inside the VM, including OS name, version,
hostname, and IP addresses.
tags:
- VM Guest
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Guest identity information
content:
application/json:
schema:
$ref: '#/components/schemas/GuestIdentityInfo'
examples:
Getvmguestidentity200Example:
summary: Default getVMGuestIdentity 200 response
x-microcks-default: true
value:
name: Example Title
family: LINUX
full_name:
default_message: example_value
id: abc123
host_name: example_value
ip_address: example_value
'401':
description: Not authenticated
'404':
description: Virtual machine not found
'503':
description: VMware Tools not running in the guest
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vcenter/vm/{vm}/guest/networking:
get:
operationId: getVMGuestNetworking
summary: Vmware Get Guest Networking Information
description: >-
Returns guest networking information reported by VMware Tools
including network interfaces, IP addresses, DNS configuration,
and routing tables.
tags:
- VM Guest
parameters:
- $ref: '#/components/parameters/vmId'
responses:
'200':
description: Guest networking information
content:
application/json:
schema:
$ref: '#/comp
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vmware/refs/heads/main/openapi/vmware-vsphere-api-openapi.yml