DigitalOcean API (unofficial showcase)
POST/v2/droplets

Create one or more Droplets

Creates one or more Droplets using the supplied configuration. Include size and image, and provide either name for one Droplet or names for multiple Droplets; names supports up to ten Droplets per request. The 202 response means the request was accepted for processing, not that creation is complete; use the returned actions links to check progress.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

17 body fields

Droplet configuration for creating one Droplet or multiple Droplets. Include size and image, and provide name for a single Droplet or names for multiple Droplets.

namestringrequired
The human-readable string you wish to use when displaying the Droplet name. The name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. The name set during creation will also determine the hostname for the Droplet in its internal configuration.
regionstringoptional
The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not not important, a slug prefix (e.g. `nyc`) can be used to deploy the Droplet in any of the that region's locations (`nyc1`, `nyc2`, or `nyc3`). If the region is omitted from the create request completely, the Droplet may deploy in any region.
sizestringrequired
The slug identifier for the size that you wish to select for this Droplet.
imagestringrequired
The image ID of a public or private image or the slug identifier for a public image. This image will be the base image for your Droplet.<br>Requires `image:read` scope.
ssh_keysarray<string>optional
An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. You must add the keys to your team before they can be embedded on a Droplet.<br>Requires `ssh_key:read` scope.
Default:[]
backupsbooleanoptional
A boolean indicating whether automated backups should be enabled for the Droplet.
Default:false
backup_policyobjectoptional
ipv6booleanoptional
A boolean indicating whether to enable IPv6 on the Droplet.
Default:false
monitoringbooleanoptional
A boolean indicating whether to install the DigitalOcean agent for monitoring.
Default:false
tagsarray<string>optional
A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags.<br>Requires `tag:create` scope.
Default:[]
user_datastringoptional
A string containing 'user data' which may be used to configure the Droplet on first boot, often a 'cloud-config' file or Bash script. It must be plain text and may not exceed 64 KiB in size.
private_networkingbooleandeprecatedoptional
This parameter has been deprecated. Use `vpc_uuid` instead to specify a VPC network for the Droplet. If no `vpc_uuid` is provided, the Droplet will be placed in your account's default VPC for the region.
Default:false
volumesarray<string>optional
An array of IDs for block storage volumes that will be attached to the Droplet once created. The volumes must not already be attached to an existing Droplet.<br>Requires `block_storage:read` scpoe.
Default:[]
vpc_uuidstringoptional
A string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, the Droplet will be assigned to your account's default VPC for the region.<br>Requires `vpc:read` scope.
subnet_uuidstringoptional
An optional string specifying the UUID of the VPC subnet to which the Droplet will be assigned. If excluded, the Droplet will be assigned to a default subnet of the VPC.<br>Requires `vpc:read` scope.
with_droplet_agentbooleanoptional
A boolean indicating whether to install the DigitalOcean agent used for providing access to the Droplet web console in the control panel. By default, the agent is installed on new Droplets but installation errors (i.e. OS not supported) are ignored. To prevent it from being installed, set to `false`. To make installation errors fatal, explicitly set it to `true`.
public_networkingbooleanoptional
An optional boolean indicating whether this Droplet should be created with public networking or not. By default, all Droplets are created with public networking available. If explicitly set to `false`, only private networking will be enabled, and public networking will be disabled; currently this means that it will not have any public static or Reserved IPv4 or IPv6 address, nor can one be assigned later. If explicitly set to `false`, `ipv6` must also be `false`.
Default:true

5 status codes
202Returns a `droplet` object and action links for a single-Droplet request, or a `droplets` array and action links for a multiple-Droplet request. The actions let you check the status of each creation operation.
dropletobjectrequired
linksobjectrequired
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned when the credentials are invalid. A 429 is returned when the API rate limit is exceeded, and a 500 indicates a server error. Include size and image, and provide either name or names; names can contain up to ten names.