VMware Hosts API

openapi: 3.1.0
info:
  title: VMware vSphere Automation REST Clusters Hosts 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
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
security:
- sessionAuth: []
- basicAuth: []
tags:
- name: Hosts
  description: ESXi host management including connection state, maintenance mode, and host configuration
paths:
  /vcenter/host:
    get:
      operationId: listHosts
      summary: Vmware List Esxi Hosts
      description: Returns a list of ESXi hosts in the vCenter inventory matching the specified filter criteria. Results can be filtered by name, connection state, cluster, datacenter, and folder.
      tags:
      - Hosts
      parameters:
      - name: filter.hosts
        in: query
        description: Identifiers of hosts to filter by
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: []
      - name: filter.names
        in: query
        description: Names of hosts to filter by
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: []
      - name: filter.folders
        in: query
        description: Folders that must contain the hosts
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: []
      - name: filter.datacenters
        in: query
        description: Datacenters that must contain the hosts
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: []
      - name: filter.clusters
        in: query
        description: Clusters that must contain the hosts
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        example: []
      - name: filter.connection_states
        in: query
        description: Connection states to filter by
        schema:
          type: array
          items:
            type: string
            enum:
            - CONNECTED
            - DISCONNECTED
            - NOT_RESPONDING
        style: form
        explode: true
        example: []
      responses:
        '200':
          description: List of hosts matching the filter
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HostSummary'
              examples:
                Listhosts200Example:
                  summary: Default listHosts 200 response
                  x-microcks-default: true
                  value:
                  - host: example_value
                    name: Example Title
                    connection_state: CONNECTED
                    power_state: POWERED_ON
        '400':
          description: Invalid filter parameters
        '401':
          description: Not authenticated
        '403':
          description: Insufficient privileges
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vcenter/host/{host}:
    get:
      operationId: getHost
      summary: Vmware Get Esxi Host Details
      description: Returns detailed information about the specified ESXi host including connection state, hardware, and resource utilization.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      responses:
        '200':
          description: Host details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostInfo'
              examples:
                Gethost200Example:
                  summary: Default getHost 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    connection_state: CONNECTED
                    power_state: POWERED_ON
        '401':
          description: Not authenticated
        '404':
          description: Host not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vcenter/host/{host}/connect:
    post:
      operationId: connectHost
      summary: Vmware Connect an Esxi Host
      description: Connects to the specified ESXi host, making it available for virtual machine operations.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      responses:
        '204':
          description: Host connected successfully
        '401':
          description: Not authenticated
        '404':
          description: Host not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vcenter/host/{host}/disconnect:
    post:
      operationId: disconnectHost
      summary: Vmware Disconnect an Esxi Host
      description: Disconnects the specified ESXi host from vCenter Server. Running VMs are not affected but can no longer be managed through vCenter.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/hostId'
      responses:
        '204':
          description: Host disconnected successfully
        '401':
          description: Not authenticated
        '404':
          description: Host not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    HostInfo:
      type: object
      description: Detailed ESXi host information
      properties:
        name:
          type: string
          description: Host name
          example: Example Title
        connection_state:
          type: string
          enum:
          - CONNECTED
          - DISCONNECTED
          - NOT_RESPONDING
          example: CONNECTED
        power_state:
          type: string
          enum:
          - POWERED_ON
          - POWERED_OFF
          - STANDBY
          example: POWERED_ON
    HostSummary:
      type: object
      description: Summary of an ESXi host in the vCenter inventory
      required:
      - host
      - name
      properties:
        host:
          type: string
          description: Unique identifier of the host (e.g., host-10)
          example: example_value
        name:
          type: string
          description: Display name or hostname of the ESXi host
          example: Example Title
        connection_state:
          type: string
          description: Connection state of the host
          enum:
          - CONNECTED
          - DISCONNECTED
          - NOT_RESPONDING
          example: CONNECTED
        power_state:
          type: string
          description: Power state of the host
          enum:
          - POWERED_ON
          - POWERED_OFF
          - STANDBY
          example: POWERED_ON
  parameters:
    hostId:
      name: host
      in: path
      required: true
      description: Identifier of the ESXi host (e.g., host-10)
      schema:
        type: string
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: vmware-api-session-id
      description: Session token obtained from POST /session. Include this header in all subsequent API requests.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using vCenter Server credentials. Used primarily for creating sessions.
externalDocs:
  description: vSphere Automation API Reference on Broadcom Developer Portal
  url: https://developer.broadcom.com/xapis/vsphere-automation-api/latest/