v8

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2025-10-165266542.4 MB

DigitalOcean-public.v2-new_Images

Create a Custom Image

To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

post/v2/images

Request body

namestring required

The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.

The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place.

descriptionstring

An optional free-form text field to describe an image.

urlstring required

A URL from which the custom Linux virtual machine image may be retrieved. The image it points to must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

region'ams1' | 'ams2' | 'ams3' | 'blr1' | 'fra1' | 'lon1' | 'nyc1' | 'nyc2' | 'nyc3' | 'sfo1' | 'sfo2' | 'sfo3' | 'sgp1' | 'tor1' | 'syd1' required

The slug identifier for the region where the resource will initially be available.

tagsstring[] nullable

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. <br><br>Requires tag:create scope.

Example request

{
  "name": "ubuntu-18.04-minimal",
  "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img",
  "distribution": "Ubuntu",
  "region": "nyc3",
  "description": "Cloud-optimized image w/ small footprint",
  "tags": [
    "base-image",
    "prod"
  ]
}

Response

The response will be a JSON object with a key set to image. The value of this will be an image object containing a subset of the standard image attributes as listed below, including the image's id and status. After initial creation, the status will be NEW. Using the image's id, you may query the image's status by sending a GET request to the /v2/images/$IMAGE_ID endpoint. When the status changes to available, the image will be ready for use.

Example response

{
  "image": {
    "id": 7555620,
    "name": "Nifty New Snapshot",
    "type": "snapshot",
    "distribution": "Ubuntu",
    "slug": "nifty1",
    "public": true,
    "regions": [
      "nyc1",
      "nyc2"
    ],
    "created_at": "2020-05-04T22:23:02Z",
    "min_disk_size": 20,
    "size_gigabytes": 2.34,
    "description": " ",
    "tags": [
      "base-image",
      "prod"
    ],
    "status": "NEW",
    "error_message": " "
  }
}