API

Disk Images

Disk Images contain the contents and structure of a disk volume or of an entire data storage device on the Civo cloud platform.

List disk images

A list of disk images accessible from an account is available by sending a GET request to https://api.civo.com/v2/disk_images.

Every Civo region will have a similar set of public disk images, but their IDs are unique per region.

Request

This request accepts an optional region parameter (query string) containing the name of the region where the disk image is located. A random one will be picked by the system if not specified.

For CivoStack Enterprise regions where custom disk images are enabled, the following parameter can be sent along with the request:

Name Description
type (optional) Accepts custom. If provided on a request to a region with custom disk images enabled, will filter to show custom images only. If the parameter is not provided, all images available to the requester on the region will be listed.

Response

The response is a JSON array of objects that describes summary details for each disk image.

[
    {
        "id": "d927ad2f-5073-4ed6-b2eb-b8e61aef29a8",
        "name": "ubuntu-focal",
        "version": "20.04",
        "state": "available",
        "distribution": "ubuntu",
        "description": null,
        "label": null
    }
]

Example of listing disk images

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/disk_images
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/disk_images',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/disk_images', headers)

Retrieving a disk image

A single disk image's details are available by sending a GET request to https://api.civo.com/v2/disk_images/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the disk image is located.

Response

The response is a JSON object that describes the details for the disk image.

{
    "id": "d927ad2f-5073-4ed6-b2eb-b8e61aef29a8",
    "name": "ubuntu-focal",
    "version": "20.04",
    "state": "available",
    "distribution": "ubuntu",
    "description": null,
    "label": null
}

For regions with custom disk images enabled, requesting the details of a custom disk image provides additional information:

{
    "id": "16b103e3-3d4f-4a8b-b817-5a2e214a7ce5",
    "name": "cust-demo-one-148ee-gxtri",
    "version": "0.0.1",
    "state": "available",
    "distribution": "archlinux",
    "os": "linux",
    "description": "archlinux",
    "label": "",
    "disk_image_url": "https://objectstore.myregion1.civo.com/cust-diskimages/disk-images/cust-demo-one-148ee-gxtri/disk.raw?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ULZKAJLTLGBCBJCSPWXE%2F20250417%2Fmyregion1%2Fs3%2Faws4_request&X-Amz-Date=20250417T103409Z&X-Amz-Expires=12000&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject&X-Amz-Signature=b287a84b35db1a0f983b98a6de2f5d0ad2c6c690dea51ecc28d4653752bff59b",
    "disk_image_size_bytes": 541063168,
    "logo_url": "https://objectstore.myregion1.civo.com/cust-diskimages/disk-images/cust-demo-one-148ee-gxtri/logo.svg",
    "created_at": "2025-04-17T10:34:09Z",
    "created_by": "77f454ca-45f8-4dc8-965e-ee2c9dfb09b8",
    "distribution_default": false
  }

Example of retrieving a disk image

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/disk_images/12345?region=LON1
    
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/disk_images/12345',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/disk_images/12345', headers)

Creating custom disk images

CivoStack Enterprise administrators can contact Civo Support to enable custom disk images to be available on their regions.

Creates a new disk image entry, processes the logo directly, and provides a pre-signed URL only for uploading the disk image

Request

The request is a multipart/form-data to support file upload

The following parameter(s) should be sent along with the request:

Name Description
name (required) Name of the disk image to be displayed in listings and the instance dashboard
distribution (required) Operating system distribution (e.g., ubuntu, centos)

version (required) Version of the operating system, to be displayed in listings and the instance dashboard

os (required) Operating system type. Defaults to linux. Supports windows and linux

region (required) The region code where the disk image is to be located

image_sha256 (required) SHA256 checksum of the disk image

image_md5 (required) MD5 checksum of the disk image

image_size (required) The size of the disk image, in bytes. Maximum size 30GB

logo_base64 (optional) A SVG file for the desired disk image logo, as a base64 encoded string

Response

The response is a JSON object that describes the details for the pending disk image.

{
  "id": "16b103e3-3d4f-4a8b-b817-5a2e214a7ce5",
  "name": "cust-demo-one-148ee-gxtri",
  "version": "0.0.1",
  "state": "upload_pending",
  "distribution": "archlinux",
  "os": "linux",
  "description": "archlinux",
  "label": "",
  "disk_image_url": "https://objectstore.myregion1.civo.com/cust-diskimages/disk-images/cust-custtest-148ee-tdkxv/disk.raw?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ULZKAJLTLGBCBJCSPWXE%2F20250417%2myregion1%2Fs3%2Faws4_request&X-Amz-Date=20250417T101842Z&X-Amz-Expires=12000&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject&X-Amz-Signature=dfdb6a2f71ab1e243a3ebf66ff9209ced434748bef99f214cc52bc9e96d2a41d",
  "disk_image_size_bytes": 528388,
  "logo_url": "https://objectstore.myregion1.civo.com/cust-diskimages/disk-images/cust-custtest-148ee-tdkxv/logo.svg",
  "created_at": "2025-04-17T10:18:42Z",
  "created_by": "77f454ca-45f8-4dc8-965e-ee2c9dfb09b8",
  "distribution_default": false
}

Example of creating a custom disk image

curl -H "Authorization: bearer 12345" -X POST https://api.civo.com/v2/disk_images?region=myregion1 \
-F "name=my-new-image" \
-F "distribution=archlinux" \
-F "version=0.0.1" \
-F "os=linux" \
-F "image_sha256=a1b2c3d4e5f6..." \
-F "image_md5=sy867ucf234hjk27..." \
-F "image_size=2346823089" \
-F "logo_base64=dfgk6sy867ucf234hjk27"
              
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/disk_images/?region=myregion1',
  form : {
            "id": "cddfc9f4-ed69-48b9-94eb-18dd0f8234f8",
            "name": "my-new-image",
            "distribution": "archlinux",
            "version": "0.0.1",
            "os": "linux",
            "image_sha256": "a1b2c3d4e5f6...",
            "image_md5": "sy867ucf234hjk27...",
            "image_size": 2346823089,
            "logo_base64": "dfgk6sy867ucf234hjk27"
          },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http/post/multipart'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}
form_data = {
  'name' => 'my-new-image',
  'distribution' => 'archlinux',
  'version' => '0.0.1',
  'os' => 'linux',
  'image_sha256' => 'a1b2c3d4e5f6...',
  'image_md5' => 'sy867ucf234hjk27...',
  'image_size' => '2346823089',
  'logo_base64' => 'dfgk6sy867ucf234hjk27'
}
resp, data = http.post('/v2/disk_images/?region=myregion1', form_data, headers)

Uploading the disk image file to the pre-signed URL

Once the above request succeeds, the desired disk image must be uploaded to the pre-signed URL generated by the API. The pre-signed URL generated for image upload expires in 200 minutes. If the upload fails, you must retry the creation process to get a new URL.

The API only accepts .qcow2 or .raw file formats for the disk image.

The upload is performed via a PUT request to the generated pre-signed disk_image_url URL.


# Assume the image to be uploaded is at ./arch.qcow2 and the presigned_url is the same as in the example above
export PRESIGNED_URL="https://objectstore.myregion1.civo.com/cust-diskimages/disk-images/cust-custtest-148ee-tdkxv/disk.raw?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ULZKAJLTLGBCBJCSPWXE%2F20250417%2myregion1%2Fs3%2Faws4_request&X-Amz-Date=20250417T101842Z&X-Amz-Expires=12000&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject&X-Amz-Signature=dfdb6a2f71ab1e243a3ebf66ff9209ced434748bef99f214cc52bc9e96d2a41d"
curl -H "Authorization: bearer 12345" -X PUT --upload-file ./arch.qcow2 $PRESIGNED_URL

The state of a custom disk image moves through the following:

  • upload_pending - the image is not uploaded (initial state)
  • upload_completed - the image been successfully uploaded using the pre-signed url
  • pending - the disk image is being processed internally
  • available - the disk image is abailable to be used for creating instances
Other states that a custom disk image may return are:
  • error - an error has occurred in processing the disk image
  • upload_expired - The image was not fully uploaded in the allotted 200 minutes

Deleting custom disk images

Deletes a custom disk image entry and the corresponding disk image from the region's stored images

Request

This action is performed by sending a DELETE request to https://api.civo.com/v2/disk_images/:id

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the disk image is located.

Response

The response from the server will be a JSON block. If successful, the response will have the HTTP status 204 No Content. If the requested disk image id is not found in the region specified, the response will ahve the HTTP status 404 Not Found.

Example of deleting a custom disk image

curl -H "Authorization: bearer 12345" -X DELETE https://api.civo.com/v2/disk_images/cddfc9f4-ed69-48b9-94eb-18dd0f8234f8?region=MYREGION1
              
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/disk_images/cddfc9f4-ed69-48b9-94eb-18dd0f8234f8?region=MYREGION1',
    function (error, response, body) {
    if (!error && response.statusCode == 204) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'require net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
}
resp, data = http.delete('/v2/disk_images/cddfc9f4-ed69-48b9-94eb-18dd0f8234f8?region=MYREGION1', headers)