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

Statuses

The possible values for the status attribute for a snapshot are:

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.

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
• Node.js
• Ruby

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"

// At a shell prompt run:
// npm init -y
// npm i --save request

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');

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.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
• Node.js
• Ruby

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

// At a shell prompt run:
// npm init -y
// npm i --save request

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');

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/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
• Node.js
• Ruby

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

// At a shell prompt run:
// npm init -y
// npm i --save request

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');

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.delete('/v2/snapshots/my-instance-snapshot', headers)