---
title: "VMware Cloud Director API"
description: "Examples of working with VMware Cloud Director API methods"
---

VMware Cloud Director API allows you to interact with VMware Cloud Director via a REST client.

You can view a description of all VMware Cloud Director API methods in the [VMware documentation](https://developer.broadcom.com/xapis/vmware-cloud-director-api/latest/).

## Authorization \{#authorization}

To authorize and start using the API:

1. [Request the API version](#request-api-version).
2. [Get a token](#get-token).

### 1. Request the API version \{#request-api-version}

1. Get a list of API versions:

   ```bash
   curl 'https://<url>/api/versions'
   ```

   Specify `<url>` — the address depending on the [region](/infrastructure/locations/#region):

   * Moscow: `vcd-msk.selectel.ru`;
   * St. Petersburg: `vcd.selectel.ru`.

   For current API versions, the `deprecated` parameter value will be `false`, and for outdated ones — `true`.

2. Select any current API version. The request examples use version 36.3.

### 2. Get a token \{#get-token}

1. Using any tool to convert strings from text format to MIME Base64, convert the following string to MIME Base64 format:

   ```
   <username>@<tenant>:<password>
   ```

   Specify:

   * `<username>` — the virtual data center username. For more details, see the guide [Managing virtual data center users](/public-cloud/manage-public-cloud/manage-users/);
   * `<tenant>` — the tenant; you can find it in the Cloud Director login URL, for example: `https://<url>/tenant/<tenant>`;
   * `<password>` —​ the virtual data center user password.

2. Request a token:

   ```bash
   curl -i -XPOST \
   -H 'Accept: application/*;version=<version>' \
   -H 'Authorization: Basic <encoded_string>' \
   'https://<url>/cloudapi/1.0.0/sessions/'
   ```

   Specify:

   * `<version>` — the API version;
   * `<encoded_string>` — the string obtained in step 1;
   * `<url>` — the address depending on the [region](/infrastructure/locations/#region):

     * Moscow: `vcd-msk.selectel.ru`;
     * St. Petersburg: `vcd.selectel.ru`.

3. Save:

   * the token from the `X-VMWARE-VCLOUD-ACCESS-TOKEN` field. When the session with the key expires, you will need to get a new token;
   * the organization ID from the `org:id` field. This field contains data in the `urn:vcloud:org:<org_id>` format, where `<org_id>` is the organization identifier.

## Request examples \{#request-examples}

Full description of the VMware Cloud Director API can be found in the [VMware documentation](https://developer.broadcom.com/xapis/vmware-cloud-director-api/latest/).

### Request organization objects \{#request-organization-objects}

Returns all available organization objects (virtual data centers, catalogs, tasks, quotas, groups, metadata, and organization networks), as well as a link for organization administration.

Request example:

```bash
curl \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/api/org/<org_id>'
```

Specify:

* `<version>` — the API version;
* `<token>` — [the token](#authorization);
* `<url>` — the address depending on the [region](/infrastructure/locations/#region):

  * Moscow: `vcd-msk.selectel.ru`;
  * St. Petersburg: `vcd.selectel.ru`;
* `<org_id>` — the organization identifier you saved when [getting the token](#get-token).

### Request virtual data center objects \{#request-vdc-objects}

Returns a list of virtual data center objects.

Request example:

```bash
curl \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/api/query?type=orgVdc'
```

Specify:

* `<version>` — the API version;
* `<token>` — [the token](#authorization);
* `<url>` — the address depending on the [region](/infrastructure/locations/#region):

  * Moscow: `vcd-msk.selectel.ru`;
  * St. Petersburg: `vcd.selectel.ru`.

### Request a list of virtual machines \{#request-list-of-vms}

Returns a list of virtual machines.

Request example:

```bash
curl \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/api/query?type=vm&fields=name,containerName&filter=isVAppTemplate==false'
```

Specify `<url>` — the address depending on the [region](/infrastructure/locations/#region):

* Moscow: `vcd-msk.selectel.ru`;
* St. Petersburg: `vcd.selectel.ru`.

Request parameters:

* `type=vm` — requests objects of the virtual machine type;
* `fields=name,containerName` — for each virtual machine, shows only the `name` and `containerName` attributes (and the default `href` attributes);
* `filter=isVAppTemplate==false` — returns only deployed virtual machines without vApp templates.

### Turn on a virtual machine \{#turn-on-vm}

Turns on the specified virtual machine.

Request example:

```bash
curl -XPOST \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/api/vApp/vm-<vm_id>/power/action/powerOn'
```

Specify:

* `<version>` — the API version;
* `<token>` — [the token](#authorization);
* `<url>` — the address depending on the [region](/infrastructure/locations/#region):

  * Moscow: `vcd-msk.selectel.ru`;
  * St. Petersburg: `vcd.selectel.ru`;
* `<vm_id>` — the virtual machine identifier; you can find it when [requesting a list of virtual machines](#request-list-of-vms) in the `href` field.

### Turn off a virtual machine \{#turn-off-vm}

Turns off the specified virtual machine.

Request example:

```bash
curl -XPOST \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/api/vApp/vm-<vm_id>/power/action/powerOff'
```

Specify:

* `<version>` — the API version;
* `<token>` — [the token](#authorization);
* `<url>` — the address depending on the [region](/infrastructure/locations/#region):

  * Moscow: `vcd-msk.selectel.ru`;
  * St. Petersburg: `vcd.selectel.ru`;
* `<vm_id>` — the virtual machine identifier; you can find it when [requesting a list of virtual machines](#request-list-of-vms) in the `href` field.

### Sign out of the session \{#exit-session}

Deletes the current session.

Request example:

```bash
curl -i -XDELETE \
-H 'Accept: application/*;version=<version>' \
-H 'Authorization: Bearer <token>' \
'https://<url>/cloudapi/1.0.0/sessions/'
```

Specify:

* `<version>` — the API version;
* `<token>` — [the token](#authorization);
* `<url>` — the address depending on the [region](/infrastructure/locations/#region):

  * Moscow: `vcd-msk.selectel.ru`;
  * St. Petersburg: `vcd.selectel.ru`.