API

Volumes

We provide a flexible size additional storage service for our Instances called volumes. This creates and attaches an additional virtual disk to the instance, allowing you to put backups or database files on the separate volume and later move the volume to another instance.

As volume storage is chargeable, at any time these can be deleted.


Create a new volume

Any user can create volumes to be attached to their instances, this takes up usage from Disk space under their quota.

New volumes are created by sending a POST request to https://api.civo.com/v2/volumes. Important: the creation of a volume and attaching it to an instance are two completely separate steps.

Request

The only required parameters are the name of the volume and the size required in gigabytes as a body parameter.

Name Description
name A name that you wish to use to refer to this volume (required)
size_gb A minimum of 1 and a maximum of your available disk space from your quota specifies the size of the volume in gigabytes (required).

Response

The response is a JSON object that confirms the details given, with a potential null for openstack_id (as it may not have been created in OpenStack yet).

{
  "id": "44aab548-61ca-11e5-860e-5cf9389be614",
  "name": "my-volume",
  "instance_id": "null",
  "mountpoint": "null",
  "openstack_id": "null",
  "size_gb": 25,
  "created_at": "2015-09-20T19:31:36+00:00"
}

Example of creating a volume

curl -X POST -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes \
  -d "name=my-volume&size_gb=25"
var request = require('request');

request.post(
  'https://api.civo.com/v2/volumes',
  {
    "name": "my-volume",
    "size_gb": 25
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/volumes', 'name=my-volume&size_gb=25', headers)

List volumes

A list of all volumes in your account is available by sending a GET request to https://api.civo.com/v2/volumes.

Request

This request takes no parameters.

Response

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

[
  {
    "id": "44aab548-61ca-11e5-860e-5cf9389be614",
    "name": "my-volume",
    "instance_id": "null",
    "mountpoint": "null",
    "openstack_id": "null",
    "size_gb": 25,
    "created_at": "2015-09-20T19:31:36+00:00"
  },
  // ...
]

Example of listing volumes

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes
var request = require('request');

request.get(
  'https://api.civo.com/v2/volumes',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

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

Resizing a volume

An unattached volume can be increased in size by the user. The upper limit is still the available space in the user's quota, and a volume can never be reduced in size. Civo knows nothing about what disk format you are using (Ext3, Ext4, BTRFS, etc) so it's up to the user to expand their filesystem afterwards.

Volumes are resized by sending a PUT request to https://api.civo.com/v2/volumes/:id/resize.

Request

The only required parameters are the id of the volume in the URL and the new size required in gigabytes as a body parameter.

Name Description
size_gb A minimum of the existing size of the volume plus 1 and a maximum of your available disk space from your quota specifies the size of the volume in gigabytes (required).

Response

The response is a simple JSON object that confirms the success of the call.

{
  "result": "success"
}

Example of resizing a volume

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/resize \
  -d "size_gb=50"
var request = require('request');

request.post(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/resize',
  {
    "size_gb": 50
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/resize', 'size_gb=50', headers)

Attach a volume to an instance

Once the volume is created and has an openstack_id, you can attach it to the instance (which is like plugging a USB drive into a computer - it still needs partitioning, formatting and mounting)..

Volumes are attached by sending a PUT request to https://api.civo.com/v2/volumes/:id/attach. Important: volumes can only be attached to one instance at a time.

Request

The required parameters are the id of the volume in the URL and the ID of the instance as a body parameter.

Name Description
instance_id The ID of an instance that you wish to attach this volume to (required)

Response

The response is a JSON object that confirms the details given, with a potential null for openstack_id (as it may not have been created in OpenStack yet).

{
  "result": "success"
}

Example of attaching a volume to an instance

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach \
  -d "instance_id=862eddfe-404a-40a7-a55f-13e287595340"
var request = require('request');

request.put(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach',
  {
    "instance_id": "862eddfe-404a-40a7-a55f-13e287595340"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/attach', 'name=862eddfe-404a-40a7-a55f-13e287595340', headers)

Detach a volume from an instance

If you've finished with the volume or want to move it to another instance, you can detach it from the instance (which is like unplugging a USB drive from a computer - you should still have safely unmounted the drive first or you risk corruption).

Volumes are detached by sending a PUT request to https://api.civo.com/v2/volumes/:id/detach.

Request

The only required parameter is the ID of the volume in the URL.

Response

The response is a JSON object that confirms the action is being taken, with a potential null for openstack_id (as it may not have been created in OpenStack yet).

{
  "result": "success"
}

Example of detaching a volume

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach
var request = require('request');

request.put(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614/detach', '', headers)

Deleting a volume

An account holder can remove a volume, freeing up the space used (and therefore the cost) by sending a DELETE request to https://api.civo.com/v2/volumes/:id.

Request

This request takes no parameters, only the ID of the volume to delete is in the URL. No confirmation step is required, this step will remove the volume immediately.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.

{
  "result": "success"
}

Example of deleting a volume

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614
var request = require('request');

request.del(
  'https://api.civo.com/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/volumes/44aab548-61ca-11e5-860e-5cf9389be614', headers)