List snapshots for an instance

Request

A list of snapshots for a particular instance is available by sending a GET request to https://api.civo.com/v2/instances/:id/snapshots?region=region-id.

Response

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

{
    [
  {
    "id": "snapshot-uuid",
    "name": "instance-snapshot-name",
    "description": "the instance snapshot description",
    "status": {
      "state": "Complete" | "Failed" | "Pending" | etc.,
      "volumes": [
          {
              "id": "volume_uuid_1",
              "state: "Completed"
          },
          {
              "id": "volume_uuid_2",
              "state: "Pending"
          },
      ]
    }
    "created_at": "2025-04-01T09:11:14Z"
 },
 {
    "id": "snapshot-2-uuid",
    "name": "instance-snapshot-2-name",
    "description": "the instance snapshot description for the second snapshot",
    "status": {
      "state": "Complete"
    }
    "created_at": "2025-03-21T10:45:00Z"
 }
}

Example of listing snapshots for an instance

• Curl
• Node.js
• Ruby

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances/abc123-45678/snapshots?region=myregion

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

var request = require('request');

request.get(
  'https://api.civo.com/v2/instances/abc123-45678/snapshots?region=myregion',
  {},
  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/instances/abc123-45678/snapshots?region=myregion', headers)

Update an instance snapshot

Users can modify the name or the description of any existing instance snapshot. Only fields that should be updated need to be provided, the rest will remain unchanged.

Request

An instance snapshot can be modified by sending a PUT request to https://api.civo.com/v2/instances/:id/snapshots/:snapshot-id?region=region-id.

Fields that can be provided as part of the request are:

Response

The response will be a JSON object describing the updated fields of the snapshot.

{
    "id": "snapshot-uuid",
    "name": "instance-snapshot-something-here",
    "description": "an updated description of the snapshot",
    "status": {
      "state": "Complete" | "Failed" | "Pending" | etc.,
      "volumes": [
          {
              "id": "volume_uuid_1",
              "state: "Complete"
          },
          {
              "id": "volume_uuid_2",
              "state: "Pending"
          },
      }
    },
    "created_at": "2025-04-01T09:11:14Z"
}

Example of updating an instance snapshot

• Curl
• Node.js
• Ruby

curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/instances/abc123-45678/snapshots/xyz312-776555?region=myregion \
  -d "name=instance-snapshot-something-here"

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

var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/abc123-45678/snapshots/xyz-312-776555?region=myregion',
  {
    "name": "instance-snapshot-something-here"
  },
  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.put('/v2/instances/abc123-45678/snapshots/xyz-312-776555?region=myregion', 'name=instance-snapshot-something-here', headers)

Restore from an instance snapshot

After a snapshot has completed, users are able to restore them, either by overriding the original instance, or by creating a new one from scratch.

Instances will be restored in the same Civo Network as the original snapshotted instance.

Request

Snapshots are restored by sending a POST request to https://api.civo.com/v2/instances/:id/snapshots/:snapshot-id/restore?region=region-id.

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

Response

If the request is valid, the API will return a JSON response containing the details of the newly created snapshot.

{
  "id": "restore-123",
  "name": "restore-operation-123",
  "hostname": "my-new-instance-hostname"
  "description": "Restored instance from snapshot",
  "from_snapshot": "snapshot-123",
  "private_ipv4": "10.0.0.1",
  "overwrite_existing": false,
  "status": {
    "state": "complete"
  },
  "created_at": "2022-01-01T12:00:00Z",
  "completed_at": "2022-01-01T12:05:00Z"
}

Example of restoring a snapshot

• Curl
• Node.js
• Ruby

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances/abc123-456789/snapshots/xyz312-776555/restore?region=myregion \
  -d "hostname=my-new-instance-hostname&overwrite_existing=false"

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

var request = require('request');

request.post(
  'https://api.civo.com/v2/instances/abc123-456789/snapshots/xyz312-776555/restore?region=myregion',
  {
    form: {
      hostname: "my-new-instance-hostname",
      overwrite_existing: false
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 201) {
      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/instances/abc123-456789?region=myregion', 'hostname=my-new-instance-hostname&volumes=true', headers)