Create

Create a New Droplet

post/v2/droplets

To create a new Droplet, send a POST request to /v2/droplets setting the required attributes.

A Droplet will be created using the provided information. The response body will contain a JSON object with a key called droplet. The value will be an object containing the standard attributes for your new Droplet. The response code, 202 Accepted, does not indicate the success or failure of the operation, just that the request has been accepted for processing. The actions returned as part of the response's links object can be used to check the status of the Droplet create event.

Create Multiple Droplets

Creating multiple Droplets is very similar to creating a single Droplet. Instead of sending name as a string, send names as an array of strings. A Droplet will be created for each name you send using the associated information. Up to ten Droplets may be created this way at a time.

Rather than returning a single Droplet, the response body will contain a JSON array with a key called droplets. This will be set to an array of JSON objects, each of which will contain the standard Droplet attributes. The response code, 202 Accepted, does not indicate the success or failure of any operation, just that the request has been accepted for processing. The array of actions returned as part of the response's links object can be used to check the status of each individual Droplet create event.

Body ParametersExpand Collapse

body: optional object { image, name, size, 12 more } or object { image, names, size, 12 more }

Accepts one of the following:

DropletSingleCreate = object { image, name, size, 12 more }

image: string or number

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.
Requires image:read scope.

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

name: string

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.

maxLength255

size: string

The slug identifier for the size that you wish to select for this Droplet.

backup_policy: optional DropletBackupPolicy

An object specifying the backup policy for the Droplet. If omitted and backups is true, the backup plan will default to daily.

backups: optional boolean

A boolean indicating whether automated backups should be enabled for the Droplet.

ipv6: optional boolean

A boolean indicating whether to enable IPv6 on the Droplet.

monitoring: optional boolean

A boolean indicating whether to install the DigitalOcean agent for monitoring.

Deprecatedprivate_networking: optional boolean

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.

region: optional string

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.

ssh_keys: optional array of string or number

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.
Requires ssh_key:read scope.

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

tags: optional array of string

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.
Requires tag:create scope.

user_data: optional string

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.

volumes: optional array of string

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.
Requires block_storage:read scpoe.

vpc_uuid: optional string

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.
Requires vpc:read scope.

with_droplet_agent: optional boolean

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.

DropletMultiCreate = object { image, names, size, 12 more }

image: string or number

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.
Requires image:read scope.

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

names: array of string

An array of human human-readable strings you wish to use when displaying the Droplet name. Each name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. Each name set during creation will also determine the hostname for the Droplet in its internal configuration.

size: string

The slug identifier for the size that you wish to select for this Droplet.

backup_policy: optional DropletBackupPolicy

An object specifying the backup policy for the Droplet. If omitted and backups is true, the backup plan will default to daily.

backups: optional boolean

A boolean indicating whether automated backups should be enabled for the Droplet.

ipv6: optional boolean

A boolean indicating whether to enable IPv6 on the Droplet.

monitoring: optional boolean

A boolean indicating whether to install the DigitalOcean agent for monitoring.

Deprecatedprivate_networking: optional boolean

region: optional string

ssh_keys: optional array of string or number

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

tags: optional array of string

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.
Requires tag:create scope.

user_data: optional string

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.

volumes: optional array of string

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.
Requires block_storage:read scpoe.

vpc_uuid: optional string

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.
Requires vpc:read scope.

with_droplet_agent: optional boolean

ReturnsExpand Collapse

SingleDropletResponse = object { droplet, links }

droplet: Droplet

links: object { actions }

actions: optional array of ActionLink

MultipleDropletResponse = object { droplets, links }

droplets: array of Droplet

links: object { actions }

actions: optional array of ActionLink

curl https://api.digitalocean.com/v2/droplets \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN"

{
  "droplet": {
    "id": 3164444,
    "name": "example.com",
    "memory": 1024,
    "vcpus": 1,
    "disk": 25,
    "disk_info": [
      {
        "type": "local",
        "size": {
          "amount": 25,
          "unit": "gib"
        }
      }
    ],
    "locked": false,
    "status": "new",
    "kernel": null,
    "created_at": "2020-07-21T18:37:44Z",
    "features": [
      "backups",
      "private_networking",
      "ipv6",
      "monitoring"
    ],
    "backup_ids": [],
    "next_backup_window": null,
    "snapshot_ids": [],
    "image": {
      "id": 63663980,
      "name": "20.04 (LTS) x64",
      "distribution": "Ubuntu",
      "slug": "ubuntu-20-04-x64",
      "public": true,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "created_at": "2020-05-15T05:47:50Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.36,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    "volume_ids": [],
    "size": {
      "slug": "s-1vcpu-1gb",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "transfer": 1,
      "price_monthly": 5,
      "price_hourly": 0.00743999984115362,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "available": true,
      "description": "Basic"
    },
    "size_slug": "s-1vcpu-1gb",
    "networks": {
      "v4": [],
      "v6": []
    },
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "available": true,
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192g"
      ]
    },
    "tags": [
      "web",
      "env:prod"
    ]
  },
  "links": {
    "actions": [
      {
        "id": 7515,
        "rel": "create",
        "href": "https://api.digitalocean.com/v2/actions/7515"
      }
    ]
  }
}

Returns Examples

{
  "droplet": {
    "id": 3164444,
    "name": "example.com",
    "memory": 1024,
    "vcpus": 1,
    "disk": 25,
    "disk_info": [
      {
        "type": "local",
        "size": {
          "amount": 25,
          "unit": "gib"
        }
      }
    ],
    "locked": false,
    "status": "new",
    "kernel": null,
    "created_at": "2020-07-21T18:37:44Z",
    "features": [
      "backups",
      "private_networking",
      "ipv6",
      "monitoring"
    ],
    "backup_ids": [],
    "next_backup_window": null,
    "snapshot_ids": [],
    "image": {
      "id": 63663980,
      "name": "20.04 (LTS) x64",
      "distribution": "Ubuntu",
      "slug": "ubuntu-20-04-x64",
      "public": true,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "created_at": "2020-05-15T05:47:50Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.36,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    "volume_ids": [],
    "size": {
      "slug": "s-1vcpu-1gb",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "transfer": 1,
      "price_monthly": 5,
      "price_hourly": 0.00743999984115362,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "available": true,
      "description": "Basic"
    },
    "size_slug": "s-1vcpu-1gb",
    "networks": {
      "v4": [],
      "v6": []
    },
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "available": true,
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192g"
      ]
    },
    "tags": [
      "web",
      "env:prod"
    ]
  },
  "links": {
    "actions": [
      {
        "id": 7515,
        "rel": "create",
        "href": "https://api.digitalocean.com/v2/actions/7515"
      }
    ]
  }
}