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
.
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
-
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)