API

Instances

Instances are running virtual servers on the Civo cloud platform. They can be of variable size.


Create an instance

Any user can create an instance, providing it's within their quota. The size of the instance is from a list of sizes, as is the region to host the instance. Instances in a single region for a given account will all share an internal network, and can (optionally, but by default) have one public IP address assigned to them.

Instances are built from a template, which may be just a base operating system such as ubuntu-14.04, or it may be a ready configured application or control panel hosting system.

Instances are created by sending a POST request to https://api.civo.com/v2/instances.

Request

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

Name Description
hostname a fully qualified domain name that should be set as the instance's hostname (required)
size the identifier for the size, from the current list
region the identifier for the region, from the current region (optional; a random one will be picked by the system)
public_ip this should be either true or false and will automatically allocate an initial public IP address, rather than having to add the first one later (optional; default is true)
network_id this must be the ID of the network from the network listing (required)
template the identifier for the template to use to build the instance, from the current templates (optional; a base ubuntu-14.04 template will be chosen by default)
snapshot_id the ID for the snapshot to use to build the instance, from your snapshots (optional; but must be specified if no template is specified)
initial_user the name of the initial user created on the server (optional; this will default to "civo", important: it can't be set to "root" or "admin")
ssh_key_id the ID of an already uploaded SSH public key to use for login to the default user (optional; if one isn't provided a random password will be set and returned in the initial_password field)
tags a space separated list of tags, to be used freely as required (optional)

Response

The response is a JSON object that describes the initial setup of the instance, these details may not be returned in future calls to list instances.

{
  "id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
  "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
  "size": "g1.xsmall",
  "region": "lon1",
  "private_ip": "10.0.0.4",
  "public_ip": "31.28.66.181",
  "template": "ubuntu-14.04",
  "initial_user": "civo",
  "initial_password": "password_here",
  "firewall_name": "default",
  "tags": [
    "web",
    "main",
    "linux"
  ]
}

Example of creating an instance

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances \
  -d "hostname=server1.prod.example.com&size=g1.xsmall&region=lon1&public_ip=true&template=ubuntu-14.04&initial_user=example&network_id=00000000-0000-0000-0000-000000000000"
var request = require('request');

request.post(
  'https://api.civo.com/v2/instances',
  {
    form: {
      hostname: "server1.prod.example.com",
      size: "g1.xsmall",
      region: "lon1",
      public_ip: "true",
      template: "ubuntu-14.04",
      network_id: "00000000-0000-0000-0000-000000000000",
      initial_user: "example"
    }
  },
  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/instances', 'hostname=server1.prod.example.com&size=g1.xsmall&region=lon1&public_ip=true&template=ubuntu-14.04&initial_user=example&network_id=00000000-0000-0000-0000-000000000000"', headers)

List instances

A list of all instances accessible from an account is available by sending a GET request to https://api.civo.com/v2/instances.

Request

This request requires no parameters. However you can optionally filter the list of instances by passing in:

Name Description
tags a space separated list of tags, to be used freely as required. If multiple are supplied, instances must much all tags to be returned (not one or more)

Response

The response is a JSON array of objects that describes summary details for each instance (the civostatsd_stats currently is just a string containing CPU %, Memory %, Storage %).

[
  {
    "id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
    "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
    "size": "g1.xsmall",
    "region": "lon1",
    "private_ip": "10.0.0.4",
    "public_ip": "31.28.66.181",
    "template": "ubuntu-14.04",
    "initial_user": "civo",
    "firewall_name": "default",
    "tags": [
      "web",
      "main",
      "linux"
    ],
    "civostatsd_stats": "4.312534,15.763039,6.361219"
  },
  // ...
]

Example of listing instances

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

request.get(
  'https://api.civo.com/v2/instances',
  {},
  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/instances', headers)

Retrieving an instance

A single instance's details are available by sending a GET request to https://api.civo.com/v2/instances/:id.

Request

This request requires only the ID parameter in the URL.

Response

The response is a JSON object that describes the details for the instance (the civostatsd_stats currently is just a string containing CPU %, Memory %, Storage %).

{
  "id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
  "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
  "size": "g1.xsmall",
  "region": "lon1",
  "private_ip": "10.0.0.4",
  "public_ip": "31.28.66.181",
  "template": "ubuntu-14.04",
  "initial_user": "civo",
  "firewall_name": "default",
  "tags": [
    "web",
    "main",
    "linux"
  ],
  "civostatsd_stats": "4.312534,15.763039,6.361219"
}

Example of retrieving an instance

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

request.get(
  'https://api.civo.com/v2/instances/12345',
  {},
  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/instances/12345', headers)

Retagging an instance

A user can retag an instance at any time, as they require.

Instances are retagged by sending a PUT request to https://api.civo.com/v2/instances/:id/tags.

Request

This operation doesn't require any additional parameters. If you don't pass a tags parameter, it will remove all the existing tags.

Name Description
tags a space separated list of tags, to be used freely as required (optional)

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of retagging an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/tags -d tags=linux
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/tags',
  {
    "tags": "linux"
  },
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/tags', {tags: "linux"}, headers)

Rebooting an instance

A user can reboot an instance at any time, for example to fix a crashed piece of software.

Instances are hard rebooted by sending a POST request to https://api.civo.com/v2/instances/:id/reboots (or https://api.civo.com/v2/instances/:id/hard_reboots). If you prefer a soft reboot, you can make the same request to https://api.civo.com/v2/instances/:id/soft_reboots.

Request

This operation doesn't require any additional parameters.

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of rebooting an instance

curl -H "Authorization: bearer 12345" \
  -x POST https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/reboots
var request = require('request');

request.post(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/reboots',
  {},
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/reboots', {}, headers)

Shutting down an instance

A user can shut down an instance at any time, for example to stop it from being attacked further.

Instances are shut down by sending a PUT request to https://api.civo.com/v2/instances/:id/stop.

Request

This operation doesn't require any additional parameters.

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of rebooting an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop',
  {},
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop', {}, headers)

Starting an instance after being shut down

A user can re-start an instance after it's been shut down. Instances are started by sending a PUT request to https://api.civo.com/v2/instances/:id/start.

Request

This operation doesn't require any additional parameters.

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of rebooting an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start',
  {},
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start', {}, headers)

Updating (resizing) an instance

A user can resize an instance upwards, providing it's within their quota. The size of the instance is from a list of sizes.

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

Request

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

Name Description
size the identifier for the size, from the current list

Response

The response is a JSON object that describes the initial setup of the instance, these details may not be returned in future calls to list instances.

{
  "id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
  "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
  "size": "g1.small"
}

Example of resizing an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize -d size=g1.small
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize',
  {
    "size": "g1.small"
  },
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize', {size: "g1.small"}, headers)

Rebuilding an instance

A user can rebuild an instance using the same settings as when the instance was last built.

Instances are resized by sending a PUT request to https://api.civo.com/v2/instances/:id/rebuild.

Request

This call requires no further parameters.

Response

The response is a JSON object that describes the initial setup of the instance, these details may not be returned in future calls to list instances.

{
  "result": "success"
}

Example of rebuilding an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/rebuild
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/rebuild',
  {},
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/rebuild', {}, headers)

Restoring an instance from a snapshot

A user can restore an instance from a snapshot of the same size instance or smaller.

Instances are restored by sending a PUT request to https://api.civo.com/v2/instances/:id/restore.

Request

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

Name Description
snapshot the name of the snapshot, from the current list

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of resizing an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/restore -d snapshot=my-backup
var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/restore',
  {
    "snapshot": "my-backup"
  },
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/restore', {snapshot: "my-backup"}, headers)

Setting the firewall for an instance

A user can set the firewall to use for an instance by sending a PUT request to https://api.civo.com/v2/instances/:id/firewall.

Request

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

Name Description
firewall_id the ID of the firewall to use, from the current list. If left blank or not sent, the default firewall will be used (open to all)

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of resizing an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/firewall -d name=restrictive-firewall
var request = require('request');

request.put(
    'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/firewall',
    {
      "name": "restrictive-firewall"
    },
    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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/firewall', {name: "restrictive-firewall"}, headers)

Moving a public IP between instances

Given two instances, one with a public IP and one without, you can move the public IP by sending a PUT request to https://api.civo.com/v2/instances/:id/ip/:ip_address.

Request

The required parameter(s) are in the URL, the target instance ID (:id) and the public IP address (:ip_address). You must own both instances and the target instance must not already have a public IP.

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of moving a public IP address

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/ip/1.2.3.4
var request = require('request');

request.put(
    'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/ip/1.2.3.4',
    {
    },
    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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/ip/1.2.3.4', {}, headers)

Deleting an instance

An account holder can remove an instance by sending a DELETE request to https://api.civo.com/v2/instances/:id.

Request

This request takes no parameters, the ID of the instance to delete is in the URL. No confirmation step is required, this step will remove the instance immediately but will leave any snapshots taken of the instance and any mapped storage.

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.

{
  "id": "b177ae0e-60fa-11e5-be02-5cf9389be614",
  "result": "success"
}

Example of deleting an instance

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/instances/b177ae0e-60fa-11e5-be02-5cf9389be614
var request = require('request');

request.del(
  'https://api.civo.com/v2/instances/b177ae0e-60fa-11e5-be02-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/instances/b177ae0e-60fa-11e5-be02-5cf9389be614', headers)