Developer screen showing REST API automation code

VMware Cloud Director API Reference

Endpoints, parameters and working examples for automating Cloud Director.

Covers the cloudapi and legacy /api namespaces at version 39.0
Authentication, tenants, VDCs, vApps, catalogs, networking and tasks
curl requests with realistic JSON responses you can copy
Error codes and the asynchronous task model explained

About this reference

VMware Cloud Director exposes two REST namespaces. Newer objects live under the modern cloudapi namespace with paged JSON collections, while a number of provider and vApp operations remain on the original /api namespace. Real automation uses both.

Every example below is written against API version 39.0 and uses a bearer token. Hostnames, URNs and payload values are illustrative - substitute your own.

Modern base URLhttps://vcd.example.com/cloudapi/1.0.0

Legacy base URLhttps://vcd.example.com/api

Common headers

Parameter	In	Type	Description
Authorizationrequired	header	string	Bearer token returned by the sessions endpoint, sent as Bearer <token>.
Acceptrequired	header	string	application/json;version=39.0 - the API version is negotiated through the Accept header.
Content-Type	header	string	application/json on any request that carries a body.

Authentication & sessions

Every Cloud Director call is authenticated with a bearer token obtained from a session. Provider (system) sessions and tenant sessions use the same endpoint - the scope is decided by the user name you send.

POST/sessions

Create a provider or tenant session

Exchanges basic credentials for a bearer token. Use administrator@system for provider scope, or user@org-name for tenant scope. The token is returned in the X-VMWARE-VCLOUD-ACCESS-TOKEN response header, not the body.

Parameters

Parameter	In	Type	Description
Authorizationrequired	header	string	Basic <base64(user@org:password)>.
Acceptrequired	header	string	application/json;version=39.0.

Example request

curl -i -X POST \
  -H 'Accept: application/json;version=39.0' \
  -u 'administrator@system:********' \
  https://vcd.example.com/cloudapi/1.0.0/sessions

Example response

HTTP/1.1 200 OK
X-VMWARE-VCLOUD-ACCESS-TOKEN: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "id": "urn:vcloud:session:6f4c2f9a-2e6e-4a2d-9d8b-1b6cf0f4a911",
  "user": { "name": "administrator", "id": "urn:vcloud:user:0f0c..." },
  "org":  { "name": "System", "id": "urn:vcloud:org:a93c..." },
  "operatingOrg": { "name": "System" },
  "roles": ["System Administrator"]
}

Note: Store the access token, not the credentials. Tokens expire with the configured session idle timeout - refresh rather than re-authenticating on every call.

POST/tokens

Create a long-lived API token

Creates a refresh token for service accounts and automation. Preferred over storing a password in a pipeline: the token can be revoked independently of the user.

Parameters

Parameter	In	Type	Description
namerequired	body	string	Human-readable token name.
typerequired	body	string	REFRESH for an API token.

Example request

curl -X POST \
  -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/json;version=39.0' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "billing-exporter", "type": "REFRESH" }' \
  https://vcd.example.com/oauth/provider/token

Example response

{
  "id": "urn:vcloud:token:3c19f5b0-08f5-4e6d-9d55-30ba6b6a1c11",
  "name": "billing-exporter",
  "type": "REFRESH",
  "refresh_token": "9f2b1c...redacted"
}

DELETE/sessions/{sessionId}

Log out and invalidate a session

Ends the current session. Always call this at the end of a scripted run.

Parameters

Parameter	In	Type	Description
sessionIdrequired	path	urn	Session URN returned by POST /sessions.

Example response

HTTP/1.1 204 No Content

Organizations (tenants)

Organizations are the tenant boundary. Provider-scoped tokens see every organization; a tenant token only ever sees its own.

GET/orgs

List organizations

Returns a paged list of organizations visible to the authenticated user.

Parameters

Parameter	In	Type	Description
page	query	integer	1-based page number. Defaults to 1.
pageSize	query	integer	Results per page, maximum 128.
filter	query	FIQL	FIQL filter, for example name==northwind-cloud or isEnabled==true.
sortAsc	query	string	Field to sort ascending, for example name.

Example request

curl -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/json;version=39.0' \
  'https://vcd.example.com/cloudapi/1.0.0/orgs?pageSize=25&filter=isEnabled==true'

Example response

{
  "resultTotal": 3,
  "pageCount": 1,
  "page": 1,
  "pageSize": 25,
  "values": [
    {
      "id": "urn:vcloud:org:6c1f2f77-08a9-4f39-b2c4-6f8a1f1d3a10",
      "name": "northwind-cloud",
      "displayName": "Northwind Cloud",
      "isEnabled": true,
      "orgVdcCount": 2,
      "catalogCount": 3
    }
  ]
}

GET/orgs/{orgId}

Get one organization

Full detail for a single tenant, including quotas and lease settings.

Parameters

Parameter	In	Type	Description
orgIdrequired	path	urn	Organization URN, for example urn:vcloud:org:6c1f2f77-....

Example request

curl -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/json;version=39.0' \
  https://vcd.example.com/cloudapi/1.0.0/orgs/urn:vcloud:org:6c1f2f77-08a9-4f39-b2c4-6f8a1f1d3a10

Example response

{
  "id": "urn:vcloud:org:6c1f2f77-08a9-4f39-b2c4-6f8a1f1d3a10",
  "name": "northwind-cloud",
  "displayName": "Northwind Cloud",
  "description": "Production tenant - UK South",
  "isEnabled": true,
  "canManageOrgs": false,
  "catalogCount": 3,
  "vappCount": 18,
  "runningVMCount": 41
}

POST/admin/org

Create an organization

Tenant creation still lives on the legacy /api namespace. Returns 202 with a task; poll the task until it reaches success.

Parameters

Parameter	In	Type	Description
namerequired	body	string	URL-safe tenant short name.
displayNamerequired	body	string	Tenant display name.
settings	body	object	Lease, quota, password policy and LDAP settings.

Example request

curl -X POST \
  -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/json;version=39.0' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "kestrel-labs",
        "displayName": "Kestrel Labs",
        "isEnabled": true,
        "settings": { "orgLeaseSettings": { "deploymentLeaseSeconds": 604800 } }
      }' \
  https://vcd.example.com/api/admin/org

Example response

HTTP/1.1 202 Accepted

{
  "id": "urn:vcloud:task:1f2a34b6-77c0-4de2-9ad1-2d6d4a0f9c31",
  "operation": "Creating Organization kestrel-labs",
  "status": "running"
}

Note: Every write in Cloud Director is asynchronous. Treat 202 + task as the normal success path.

Organization VDCs

An organization VDC is the tenant's slice of provider compute, storage and networking. Most capacity and metering questions are answered here.

GET/vdcs

List organization VDCs

Returns the VDCs the token can see, with allocation model and compute limits.

Parameters

Parameter	In	Type	Description
filter	query	FIQL	For example org.id==urn:vcloud:org:6c1f2f77-....
pageSize	query	integer	Results per page, maximum 128.

Example request

curl -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/json;version=39.0' \
  'https://vcd.example.com/cloudapi/1.0.0/vdcs?filter=org.id==urn:vcloud:org:6c1f2f77-08a9-4f39-b2c4-6f8a1f1d3a10'

Example response

{
  "resultTotal": 2,
  "values": [
    {
      "id": "urn:vcloud:vdc:9b41e0ff-3f5a-4a52-b0c5-64f0a9d2c817",
      "name": "northwind-prod-vdc",
      "allocationModel": "AllocationVApp",
      "computeCapacity": {
        "cpu": { "units": "MHz", "allocated": 120000, "used": 74400 },
        "memory": { "units": "MB", "allocated": 393216, "used": 251904 }
      },
      "isEnabled": true
    }
  ]
}

GET/vdcs/{vdcId}/storageProfiles

List storage policies for a VDC

Storage policy limits and usage - the numbers most providers bill from.

Parameters

Parameter	In	Type	Description
vdcIdrequired	path	urn	Organization VDC URN.

Example response

{
  "values": [
    {
      "id": "urn:vcloud:vdcstorageProfile:5f0f...",
      "name": "gold-nvme",
      "limitMb": 40960,
      "usedStorageMb": 27311,
      "default": true
    }
  ]
}

vApps and VMs

vApps group VMs with their networks and start-up order. Power operations are asynchronous and always return a task.

GET/query?type=adminVApp

Query vApps

The legacy query service is still the fastest way to enumerate vApps across a large estate. Supports paging, filtering and field selection.

Parameters

Parameter	In	Type	Description
typerequired	query	string	vApp or adminVApp.
filter	query	string	For example vdcName==northwind-prod-vdc;status==POWERED_ON.
fields	query	string	Comma-separated fields to return.
format	query	string	records (default) or idrecords.

Example request

curl -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/*+json;version=39.0' \
  'https://vcd.example.com/api/query?type=adminVApp&filter=status==POWERED_ON&pageSize=50'

Example response

{
  "total": 18,
  "record": [
    {
      "name": "nw-web-tier",
      "href": "https://vcd.example.com/api/vApp/vapp-2c9a...",
      "status": "POWERED_ON",
      "vdcName": "northwind-prod-vdc",
      "numberOfVMs": 3
    }
  ]
}

GET/vApp/{vappId}

Get a vApp

Full vApp detail: VM children, networks, lease and start-up section.

Parameters

Parameter	In	Type	Description
vappIdrequired	path	string	For example vapp-2c9a....

Example response

{
  "id": "urn:vcloud:vapp:2c9a7c1e-6a04-4d02-9c1a-58e2f0a4b7d3",
  "name": "nw-web-tier",
  "status": 4,
  "children": {
    "vm": [
      { "name": "nw-web-01", "status": 4, "numberOfCpus": 4, "memoryMB": 8192 },
      { "name": "nw-web-02", "status": 4, "numberOfCpus": 4, "memoryMB": 8192 }
    ]
  }
}

Note: Numeric status: 3 suspended, 4 powered on, 8 powered off, 9 inconsistent.

POST/vApp/{vappId}/power/action/powerOn

Power on a vApp

Starts every VM in the vApp using the configured start-up order.

Parameters

Parameter	In	Type	Description
vappIdrequired	path	string	vApp identifier.

Example request

curl -X POST \
  -H 'Authorization: Bearer $VCD_TOKEN' \
  -H 'Accept: application/*+json;version=39.0' \
  https://vcd.example.com/api/vApp/vapp-2c9a7c1e-6a04-4d02-9c1a-58e2f0a4b7d3/power/action/powerOn

Example response

HTTP/1.1 202 Accepted

{
  "id": "urn:vcloud:task:8e2a1f30-9b31-4b0e-8a6b-9a0f7c2d5511",
  "operation": "Starting Virtual Application nw-web-tier",
  "status": "running",
  "progress": 0
}

Note: Powering on an already-running vApp returns 400 with BUSY_ENTITY. Check state first, or treat that error as a no-op to keep automation idempotent.

POST/vApp/{vappId}/power/action/powerOff

Power off a vApp

Hard power off. Use /action/undeploy with shutdown for a guest-clean stop that also releases resources.

Parameters

Parameter	In	Type	Description
vappIdrequired	path	string	vApp identifier.

Example response

HTTP/1.1 202 Accepted

{
  "id": "urn:vcloud:task:4b7d...",
  "operation": "Stopping Virtual Application nw-web-tier",
  "status": "running"
}

POST/vApp/{vappId}/action/recomposeVApp

Add or remove VMs in a vApp

Recompose adds VMs from a template or removes existing children in one asynchronous operation.

Parameters

Parameter	In	Type	Description
SourcedItem	body	array	VMs to add, referenced by template href.
DeleteItem	body	array	VM hrefs to remove.

Example response

HTTP/1.1 202 Accepted

{ "id": "urn:vcloud:task:c101...", "operation": "Recomposing vApp nw-web-tier", "status": "running" }

Catalogs and templates

Catalogs hold vApp templates and media, and are the mechanism for publishing content to tenants.

GET/catalogs

List catalogs

Catalogs visible to the token, including published and subscribed catalogs.

Parameters

Parameter	In	Type	Description
filter	query	FIQL	For example isPublished==true.
pageSize	query	integer	Results per page.

Example response

{
  "resultTotal": 3,
  "values": [
    {
      "id": "urn:vcloud:catalog:11c4...",
      "name": "provider-templates",
      "isPublished": true,
      "isSubscribed": false,
      "numberOfVAppTemplates": 14
    }
  ]
}

POST/admin/catalog/{catalogId}/action/sync

Sync a subscribed catalog

Forces an out-of-band sync of a subscribed catalog rather than waiting for the schedule.

Parameters

Parameter	In	Type	Description
catalogIdrequired	path	string	Catalog identifier.

Example response

HTTP/1.1 202 Accepted

{ "id": "urn:vcloud:task:77aa...", "operation": "Synchronizing catalog", "status": "running" }

Networking and Edge Gateways

From 10.3 onwards, tenant networking is driven through the cloudapi namespace backed by NSX. IP Spaces replace static IP pool sprawl in newer releases.

GET/edgeGateways

List Edge Gateways

Edge Gateways with their backing NSX-T tier-0 and allocated IP counts.

Parameters

Parameter	In	Type	Description
filter	query	FIQL	For example orgVdc.id==urn:vcloud:vdc:9b41....

Example response

{
  "resultTotal": 1,
  "values": [
    {
      "id": "urn:vcloud:gateway:ee31...",
      "name": "northwind-edge",
      "gatewayBacking": { "backingType": "NSXT_BACKED" },
      "edgeGatewayUplinks": [{ "uplinkName": "t0-provider-uk-south", "dedicated": false }]
    }
  ]
}

GET/edgeGateways/{gatewayId}/firewall/rules

Get Edge firewall rules

Ordered firewall rule set for a gateway. PUT the whole list back to change it.

Parameters

Parameter	In	Type	Description
gatewayIdrequired	path	urn	Edge Gateway URN.

Example response

{
  "userDefinedRules": [
    {
      "id": "urn:vcloud:firewallRule:aa10...",
      "name": "allow-https-in",
      "direction": "IN_OUT",
      "ipProtocol": "IPV4",
      "enabled": true,
      "actionValue": "ALLOW"
    }
  ]
}

Note: Firewall updates are a full-list replace, not a patch. Read, modify, then PUT the complete array.

GET/ipSpaces

List IP Spaces

Provider IP Spaces with their allocation ranges and current utilisation.

Parameters

Parameter	In	Type	Description
pageSize	query	integer	Results per page.

Example response

{
  "resultTotal": 2,
  "values": [
    {
      "id": "urn:vcloud:ipSpace:3c88...",
      "name": "public-uk-south",
      "type": "PUBLIC",
      "ipSpaceRanges": { "ipRanges": [{ "startIpAddress": "203.0.113.10", "endIpAddress": "203.0.113.200" }] }
    }
  ]
}

Tasks and error handling

Cloud Director writes are asynchronous. Reliable automation polls tasks and handles the standard error envelope rather than assuming success on 2xx.

GET/tasks/{taskId}

Poll a task

Returns task progress and outcome. Poll with backoff until status is success, error or aborted.

Parameters

Parameter	In	Type	Description
taskIdrequired	path	urn	Task URN.

Example response

{
  "id": "urn:vcloud:task:8e2a1f30-9b31-4b0e-8a6b-9a0f7c2d5511",
  "operation": "Starting Virtual Application nw-web-tier",
  "status": "success",
  "progress": 100,
  "startTime": "2026-09-04T09:12:44.118Z",
  "endTime": "2026-09-04T09:13:29.402Z"
}

GET/orgs/{orgId} (error example)

Standard error envelope

All Cloud Director errors share the same shape. Log minorErrorCode and the X-VMWARE-VCLOUD-REQUEST-ID header - support cases are far quicker with both.

Example response

HTTP/1.1 403 Forbidden
X-VMWARE-VCLOUD-REQUEST-ID: 6d1f4a12-...

{
  "minorErrorCode": "ACCESS_TO_RESOURCE_IS_FORBIDDEN",
  "message": "This operation is denied.",
  "stackTrace": null
}

Common error codes

Minor error code	HTTP	What it means
UNAUTHORIZED	401	Missing, expired or malformed bearer token. Re-authenticate.
ACCESS_TO_RESOURCE_IS_FORBIDDEN	403	The token is valid but the role or tenant scope does not allow the operation.
RESOURCE_NOT_FOUND	404	Wrong URN, or the object is outside the token's scope.
BUSY_ENTITY	400	Another task holds the object, or the requested state change is already in effect.
VALIDATION_ERROR	400	Body failed schema validation - usually a missing required field or a bad href.
CONFLICT	409	Name collision, or an ETag mismatch on a concurrent update. Re-read and retry.
INTERNAL_SERVER_ERROR	500	Cell-side failure. Capture the request id and check the cell logs before retrying.

Need Cloud Director automation built or reviewed?

We build API integrations between Cloud Director and billing, service desk and monitoring platforms - and keep them working across upgrades.

Book a FREE 30 Minute Call

VMware Cloud Director API Reference

About this reference

Common headers

Contents

Authentication & sessions

Create a provider or tenant session

Parameters

Create a long-lived API token

Parameters

Log out and invalidate a session

Parameters

Organizations (tenants)

List organizations

Parameters

Get one organization

Parameters

Create an organization

Parameters

Organization VDCs

List organization VDCs

Parameters

List storage policies for a VDC

Parameters

vApps and VMs

Query vApps

Parameters

Get a vApp

Parameters

Power on a vApp

Parameters

Power off a vApp

Parameters

Add or remove VMs in a vApp

Parameters

Catalogs and templates

List catalogs

Parameters

Sync a subscribed catalog

Parameters

Networking and Edge Gateways

List Edge Gateways

Parameters

Get Edge firewall rules

Parameters

List IP Spaces

Parameters

Tasks and error handling

Poll a task

Parameters

Standard error envelope

Common error codes

Related reading

Need Cloud Director automation built or reviewed?