vCloud API programming guide for service providers

This release of vCloud API Programming Guide for Service Providers contains information on version 29.0 of vCloud API.

VMware provides many different APIs and SDKs for applications and for various purposes. This guide contains information about vCloud API for developers interested in building RESTful clients from VMware vCloud Director.

History of the guide editions.


The version number of vCloud API is incremented each time any of its types or operations change. vCloud API Programming Guide for Service Providers is revised with each release of VMware vCloud Director. Versions of vCloud API that were not present in VMware vCloud Director release are described in Air Compute Service vCloud Programming Guide. An API version can be deprecated whenever a newer API version supports an equivalent set of features. Using an outdated API is not recommended. API version support may be removed in a release after the deprecation. 

Revision History

Revision Date


Release Vehicle


25 SEP 2017

API Version 29.0

vCloud Director 9.0


21 FEB 2017

API Version 27.0

vCloud Director 8.20


26 MAY 2016

API Version 20.0

vCloud Director 8.10



API Version 19.0

vCloud Air Compute Service



API Version 18.0

vCloud Air Compute Service


25 JAN 2016

API Version 17.0

vCloud Air Compute Service



API Version 16.0

vCloud Air Compute Service


15 DEC 2015

API Version 14.0

vCloud Air Compute Service


21 SEP 2015

API Version 13.0

vCloud Air Compute Service


22 AUG 2015

API Version 12.0

vCloud Air Compute Service


10 JUL 2015

API Version 11.0

vCloud Air Compute Service


10 SEP 2015

API Version 9.0

vCloud Director 8.0, vCloud Air Compute Service


15 APR 2015

API Version 7.0.

vCloud Air Compute Service


16 MAR 2015

API Version 6.0

vCloud Air Compute Service


13 JAN 2015

API Version 5.11

vCloud Air Compute Service


24 OCT 2014

API Version 5.10

vCloud Air Compute Service


19 SEP 2014

API Version 5.9

vCloud Air Compute Service


05 SEP 2014

API Version 5.8

vCloud Air Compute Service


01 AUG 2014

API Version 5.7.

vCloud Air Compute Service


07 OCT 2014

API Version 5.6

vCloud Director 5.6


19 SEP 2013

API Version 5.5

vCloud Director 5.5


10 SEP 2012

API Version 5.1

vCloud Director 5.1

Deprecated. Unsupported after vCloud Director 9.0.

01 SEP 2011

API Version 1.5

vCloud Director 1.5

Deprecated. Unsupported after vCloud Director 9.0.

30 AUG 2010

API Version 1.0

vCloud Director 1.0

not supported

14 APR 2010

API Version 0.9


not supported




The target audience

This guide is intended for software developers who create VMware Ready Cloud Services, including VMware vCloud Director interactive clients. This guide discusses the porting state (REST) and RESTful conventions, the Open Virtualization Format specification, and VMware virtual machine technology. You should be familiar with these and other widespread technologies such as XML, HTTP, and the Windows or Linux operating system.

Related publications

Link to vCloud API Schema Reference includes reference material for all items, types, requests, and operations in vCloud API. It also contains schema definition files. A link to the diagram is available at

About VMware vCloud API

The VMware vCloud API provides support for developers who build VMware vCloud Director interactive clients using the RESTful application development style.


VCloud API clients communicate with servers over HTTP by exchanging representations of vCloud objects. These representations take the form of XML elements. You use HTTP GET requests to retrieve current representation of an object, HTTP POST and PUT requests to create or modify an object, and HTTP DELETE to delete an object.

Hello vCloud: A simplified RESTful workflow

VCloud API Clients and vCloud Director servers communicate over HTTPS, exchanging XML representations of vCloud API objects.

This simplified RESTful workflow example includes requests that discover and deploy a specific vApp, in this case an FTP server with a connection to the public internet.

These examples assume that you have access to a directory that includes a specific vApp template and an organization that supports public Internet connections. The workflow and examples are flexible and can accommodate various vApp templates and cloud capabilities.



If you want to run Hello vCloud samples, please make sure the following conditions are met.

You have the credentials for a user with the fixed vApp author rights, or equivalent set of rights.


Your organization has at least one VDC that has at least one network. For information on creating VDCs and networks, see Managing an Organization.


Your organization contains directory where at least one vApp template is available. For information about adding vApp template to the catalog, see Provisioning an Organization.




Logging In

To begin using the API, you request the system to create a Session object. In this request, you supply your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses. The response includes an authorization token, which you must include in subsequent requests.


Find a Catalog and a VDC

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs and a VDC in your organization to use for the deployment.


Retrieve the Contents of a Catalog

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images referenced by the catalog.


Retrieve a Catalog Item

You can examine the list of items in a catalog to find items of interest based on the values of their name and type attributes. You must retrieve a catalog item to get a Description and a usable reference to the underlying object.


Retrieve Deployment Information From the VDC

To deploy your template as a vApp, you must specify an organization VDC to deploy it in and an organization VDC network to connect it to.


Deploy the vApp

To create a vApp from a vApp template, you must bind the template's abstract resource requirements, such as network connections, storage resources, memory, and CPU capacity, to appropriate resources in the target VDC. This binding operation is called instantiation.


Get Information About a vApp

When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this URL with a GET request to retrieve information that you can use to connect to the vApp, modify its configuration, and operate it.


Displaying the Virtual Machine Console

After a vApp is powered on, you can retrieve a screen ticket from any of its virtual machines. You use that ticket with the VMware HTML Console SDK to access the virtual machine console from a browser.


Undeploy, Power Off, and Delete the vApp

After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the vApp object.


Log Out

To log out and terminate a vCloud API session, delete the Session you created when you logged in.

Exploring the clouds

You can use HTTP GET requests to browse containers like organizations, directories and VDCs in the cloud.


The responses to these queries include metadata about the container itself and links to the objects it contains. These links are represented in Link elements, which have href attributes that the client can use in requests to get more information about the objects. This process is sometimes called sequential discovery because the content of a single response provides links to the sources where you can look for more information. The hierarchical structure of vCloud API container objects lends itself to graphical representation as a folder hierarchy or tree view of vCloud API objects and allows customers to use the same set of objects and operations to implement a breadth or depth-to-view approach.

The list of entry points from which you can start browsing is contained in Session element, which is returned in response to a successful login. The contents of this list are based on your rights and privileges.



Create a vCloud API session

Retrieve a List of Organizations Accessible to You

Retrieve an Administrative View of a Cloud

Retrieve a List of vSphere Platform Operations and Objects for a Cloud

Related terms:

XML Representations in the vCloud API


Organization initialization

The vCloud API provides several ways to make vApp templates, vApps, media images, and independent disks available to users in the vCloud Director organization.

The vCloud API allows you to upload and download OVF packages and ISO media images. Operations are characterized as downloads when content is transferred from the vCloud API client system to the target directory in the vCloud client organization and as downloads when the vCloud API client requests a transfer of content from vCloud Director. A POST request initiates a download, and a GET request initiates a download. VCloud Director Transfer Service facilitates uploads and downloads and provides temporary storage for files. Downloaded vApp templates and media images become available as directory items in the target directory.

In addition to uploading, you can use the following operations to provide the organization with vApps, vApps and media images:


The vCloud API cloneVApp operation creates a copy of vApp in a specified VDC. You can specify whether to delete the source vApp after the operation completes. Deleting the source vApp after cloning it moves or renames it.


vCloud API captureVApp operation creates vApp template from vApp and places the template in a specified catalog.


System administrator can import a virtual machine from vCenter server that is registered to the cloud. You can import the virtual machine as vApp or as vApp template. You can add an imported template to a catalog or download it as OVF package.


In the default configuration, the system automatically discovers vCenter VMs contained by in any resource pool that backs an organization VDC. A system administrator can also can configure an organization VDC to adopt existing vCenter resource pools and the VMs they contain. The system administrator can make these discovered VMs available for adoption by organization members.


Organizations that have the appropriate permissions can create catalogs with external subscriptions. These contents of these catalogs are downloaded from a catalog hosted on another instance of vCloud Director, or any Web site that implements the VMware Content Subscription Protocol. See: Create a Catalog With an External Subscription.

You can also create independent disks that are contained in VDC organization and can be connected to any virtual machine in that VDC.


Upload an OVF Package to Create a vApp Template

Download a vApp or vApp Template as OVF

Upload a Media Image

Download a Media Image

Capturing and Importing vApps

Discovering and Adopting vApps

Managing Catalog Items

Creating and Using Independent Disks

View or Change the Owner of an Object


Controlling Access to vApps and Catalogs

Deploying and using vApps and virtual machines

<p class="MsoNormal" st

  • 68 Users Found This Useful
Was this answer helpful?

Related Articles

vCloud Director API for NSX. Programmers’ Guide

About vCloud Director API для NSX vCloud Director API для NSX. vCloud Director API for NSX is a...

How to access VMware Cloud Director via the vCloud API

Overview To perform some tasks in a CLOUD4Y environment, you may need to access VMware Cloud...

Changing EDGE settings with the vCloud API

Introduction This tutorial shows how to receive, modify and send XML blocks, which represent the...

Changing Advanced Edge settings via API using PowerShell 7

In this article, we will take a look on some Advanced Edge Gateway actions available to the...