Droplet API
Request schemas and lifecycle endpoints for virtual machines.
The Droplet API creates, reads, updates, and removes virtual machines in a project. All endpoint paths are relative to the API base URL.
Create a droplet
/organizations/{organization_id}/projects/{project_id}/dropletsCreates a droplet and starts provisioning. The caller must also have permission to use the referenced image, network, and storage policy.
namestringrequiredregion_idstringrequiredimage_idstringrequiredvcpusintegerrequiredmemory_mibintegerrequiredroot_volumeobjectrequiredsize_gib and storage_policy_id. Size must satisfy the image minimum.interfacesarrayrequirednetwork_id and an optional available address in that network.ssh_key_idsstring[]optional[]user_datastringoptionalEmptylabelsobjectoptional{}deletion_protectionbooleanoptionalfalsespotbooleanoptionalfalsestartbooleanoptionaltrueUnknown fields and invalid references return 422. A quota or policy rejection
before admission creates no droplet. Execution failures after admission are
reported on the operation and can leave retained resources for inspection.
An accepted creation returns the droplet and its operation:
{
"data": { "id": "drp_web01", "state": "provisioning" },
"operation": { "id": "op_create01", "state": "queued" },
"request_id": "req_deploy01"
}The following request requires a ready image, private network, and replicated
storage policy in the same region. The API token needs droplets:write and the
corresponding project role.
To create the droplet with an inline JSON request, send:
curl --fail-with-body --request POST \
--header "Authorization: Bearer ${INFRA_API_TOKEN}" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: payments-web-01-create-v1' \
--data '{
"name": "web-01",
"region_id": "reg_euwest",
"image_id": "img_ubuntu",
"vcpus": 2,
"memory_mib": 4096,
"root_volume": {"size_gib": 30, "storage_policy_id": "sp_replicated"},
"interfaces": [{"network_id": "net_production"}],
"labels": {"service": "web", "environment": "production"}
}' \
"${INFRA_API_URL}/organizations/org_main/projects/prj_payments/droplets"Read and list
/organizations/{organization_id}/projects/{project_id}/droplets/{droplet_id}Returns the full resource with its ETag header. Requires droplets:read.
The resource separates requested configuration from observed execution:
| Response field | Type | Meaning |
|---|---|---|
id | String | Immutable droplet ID |
revision | Integer | Configuration revision used by the ETag |
state | String | provisioning, running, stopped, preempting, preempted, deleting, or error |
health | Object | Named health conditions and their observation time |
placement | Object | Observed region, zone, node, and CPU profile |
interfaces | Array | Interface IDs, networks, and assigned addresses |
volume_attachments | Array | Root and data-volume attachment references |
active_operation_id | String or null | Current conflicting lifecycle operation |
The desired size fields are distinct from observed hypervisor values while an
update is pending. Guest initialization and application health are not implied
by state=running.
/organizations/{organization_id}/projects/{project_id}/dropletsLists droplets in the permitted project scope.
List the collection with the same scope. Filters include region_id, state,
and label in key=value form, plus standard pagination parameters.
Update configuration
/organizations/{organization_id}/projects/{project_id}/droplets/{droplet_id}Updates mutable droplet configuration.
Requires droplets:write and the current If-Match header. Writable fields are
name, labels, and deletion_protection. Omitted fields remain unchanged.
labels replaces the complete label map; an empty object removes all labels.
null is rejected for these fields.
Region, image, CPU, memory, and attachments cannot be changed through this patch.
Use the corresponding action or volume endpoint. A stale revision returns 412
without applying the patch.
Lifecycle actions
/organizations/{organization_id}/projects/{project_id}/droplets/{droplet_id}/actionsRequests a droplet lifecycle action.
Requires droplets:write. Send an object containing type and the fields for
that action. Actions return 202 and support idempotency keys.
Each action accepts the following fields and lifecycle conditions:
type | Additional fields | Requirement |
|---|---|---|
start | None | Droplet stopped or preempted; eligible capacity required |
shutdown | Optional grace_period_seconds, default 120, integer 1–3600 | Running guest; timeout fails without forced power-off |
restart | None | Running guest |
force_stop | None | Running or unresponsive guest |
resize | Required vcpus, memory_mib | Stopped droplet and supported target size |
migrate | Optional destination_node_id | Eligible running droplet; omitted destination invokes scheduling |
change_capacity_type | Required boolean spot | Stopped or preempted guest; requested capacity type offered by the region |
Invalid states or an active conflicting operation return 409. Unsupported
sizes and destinations return 422. See Lifecycle and
Live migration for execution and persistence rules.
Delete
/organizations/{organization_id}/projects/{project_id}/droplets/{droplet_id}Deletes a droplet and the selected root volume while retaining independent resources.
Requires droplets:write and If-Match. The optional delete_root_volume query
parameter is boolean and defaults to true. Separately managed data volumes,
reserved public addresses, and backups are retained.
Deletion protection returns 409 deletion_protected. Accepted deletion returns
202 with an operation reference. The resource can remain visible as deleting
until cleanup completes. A later read returns 404 after removal.
Migration transfer options
The migrate action also accepts max_bandwidth_bytes_per_second,
convergence_timeout_seconds, and max_pause_ms. Omitted bandwidth inherits
the regional ceiling; a supplied value must be a positive integer. Convergence
timeout defaults to 1800 seconds, inclusive range 60–86400. Pause budget
defaults to 500 milliseconds, inclusive range 50–5000.
Unsupported values return 422 invalid_migration_policy. These options cannot
make passthrough or scratch-backed guests eligible for live migration. A transfer
that cannot converge fails before commit rather than silently forcing a stop.
See migration controls for contention and cancellation.
Hardware policy, scratch devices, and NUMA requirements use the separate Hardware policy API. Console and rescue access use Guest Access API; public SSH-key registration uses SSH key API.