Snapshots

We provide a backup service for our Instances called snapshots. This takes an exact copy of the instance's virtual hard drive. At any point an instance can be restored to the state it was in when the snapshot was made. These snapshots can also be used to build a new instance to scale identically configured infrastructure.

As snapshot storage is chargeable, at any time these can be deleted. They can also be scheduled rather than immediately created, and if desired repeated at the same schedule each week (although the repeated snapshot will overwrite itself each week not keep multiple weekly snapshots).

Create a new or update an old snapshot

Any user can create snapshots for their instances, this space is charged separately from their quota.

New snapshots are created by sending a PUT request to https://api.civo.com/v2/snapshots/:name.

Request

The only required parameters are the instance ID as a body parameter and the snapshot name in the URL. Two optional parameters of safe and cron_timing can also be passed. If the snapshot already exists it will be overwritten.

Name	Description
instance_id	The ID of the instance to snapshot
safe	If `true` the instance will be shut down during the snapshot to ensure all files are in a consistent state (e.g. database tables aren't in the middle of being optimised and hence risking corruption). The default is `false` so you experience no interruption of service, but a small risk of corruption.
cron_timing	If a valid cron string is passed, the snapshot will be saved as an automated snapshot, continuing to automatically update based on the schedule of the cron sequence provided. The default is `nil` meaning the snapshot will be saved as a one-off snapshot.

Response

The response is a JSON object that confirms the details given, with a null for snapshot_at (as it won't have been taken yet).

{
  "id": "0ca69adc-ff39-4fc1-8f08-d91434e86fac",
  "instance_id": "44aab548-61ca-11e5-860e-5cf9389be614",
  "hostname": "server1.prod.example.com",
  "template_id": "0b213794-d795-4483-8982-9f249c0262b9",
  "openstack_snapshot_id": null,
  "region": "lon1",
  "name": "my-instance-snapshot",
  "safe": 1,
  "size_gb": 0,
  "state": "new",
  "cron_timing": null,
  "requested_at": null,
  "completed_at": null
}

Example of creating a snapshot

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/snapshots/my-instance-snapshot \
  -d "instance_id=b177ae0e-60fa-11e5-be02-5cf9389be614&safe=true"

var request = require('request');

request.post(
  'https://api.civo.com/v2/snapshots/my-instance-snapshot',
  {
    "instance_id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
    "safe": true
  },
  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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/snapshots/my-instance-snapshot', 'instance_id=b177ae0e-60fa-11e5-be02-5cf9389be614&safe=true', headers)

List snapshots

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

Request

This request takes no parameters.

Response

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

[
  {
    "id": "0ca69adc-ff39-4fc1-8f08-d91434e86fac",
    "instance_id": "44aab548-61ca-11e5-860e-5cf9389be614",
    "hostname": "server1.prod.example.com",
    "template_id": "0b213794-d795-4483-8982-9f249c0262b9",
    "openstack_snapshot_id": null,
    "region": "lon1",
    "name": "my-instance-snapshot",
    "safe": 1,
    "size_gb": 0,
    "state": "in-progress",
    "cron_timing": null,
    "requested_at": null,
    "completed_at": null
  },
  // ...
]

Example of listing snapshots

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/snapshots

var request = require('request');

request.get(
  'https://api.civo.com/v2/snapshots',
  {},
  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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

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

Deleting a snapshot

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

Request

This request takes no parameters, only the name of the snapshot to delete is in the URL. No confirmation step is required, this step will remove the snapshot 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 202 Accepted.

{
  "result": "success"
}

Example of deleting a snapshot

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/snapshots/my-instance-snapshot

var request = require('request');

request.del(
  'https://api.civo.com/v2/snapshots/my-instance-snapshot',
  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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/snapshots/my-instance-snapshot', headers)