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
count the number of instances to create (optional, default is 1)
hostname a fully qualified domain name that should be set as the instance's hostname (required)
reverse_dns a fully qualified domain name that should be used as the instance's IP's reverse DNS (optional, uses the hostname if unspecified)
size the identifier for the size, from the current list (required)
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 none, create or from. If from is specified then the move_ip_from parameter should also be specified (and contain the ID of the instance that will be releasing its IP). As aliases true will be treated the same as create and false will be treated the same as none. If create or true is specified it will automatically allocate an initial public IP address, rather than having to add the first one later (optional; default is create)
network_id this must be the ID of the network from the network listing (optional; default network used when not specified)
template_id the ID for the template to use to build the instance, from the current templates. Parameter also accepted as template. (optional; but must be specified if no snapshot is specified)
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 the template's default_username and fallback to "civo")
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",
  "openstack_server_id": "369588f7-de40-4eca-bc8d-4c2dbc1cc7f3",
  "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
  "reverse_dns": null,
  "size": "g2.xsmall",
  "region": "lon1",
  "network_id": "63906834-2455-4b72-b0c4-77617ef18b4e",
  "private_ip": "10.0.0.4",
  "public_ip": "31.28.66.181",
  "pseudo_ip": "172.31.0.230",
  "template_id": "f80a1698-8933-414f-92ac-a36d9cfc4ac9",
  "snapshot_id": null,
  "initial_user": "civo",
  "initial_password": "password_here",
  "ssh_key": "61f1b5c8-2c87-4cc7-b1af-6278f3050a28",
  "status": "ACTIVE",
  "notes": null,
  "firewall_id": "default",
  "tags": [
    "web",
    "main",
    "linux"
  ],
  "civostatsd_token": "f84d920f-c74b-4b48-a21e-5ff7a671e5f9",
  "civostatsd_stats": null,
  "civostatsd_stats_per_minute": [],
  "civostatsd_stats_per_hour": [],
  "openstack_image_id": null,
  "rescue_password": null,
  "volume_backed": true,
  "created_at": "2015-09-20T19:31:36+00:00"
}

Example of creating an instance

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances \
  -d "hostname=server1.prod.example.com&size=g2.xsmall&region=lon1&public_ip=true&template_id=b67d6fed-8ab6-45b9-be2d-2f3337c933c6&initial_user=example"
var request = require('request');

request.post(
  'https://api.civo.com/v2/instances',
  {
    form: {
      hostname: "server1.prod.example.com",
      size: "g2.xsmall",
      region: "lon1",
      public_ip: "true",
      template_id: "b67d6fed-8ab6-45b9-be2d-2f3337c933c6",
      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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/instances', 'hostname=server1.prod.example.com&size=g2.xsmall&region=lon1&public_ip=true&template_id=b67d6fed-8ab6-45b9-be2d-2f3337c933c6&initial_user=example"', headers)

List instances

A list of 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)
page which page of results to return (defaults to 1)
per_page how many instances to return per page (defaults to 20)

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",
    "openstack_server_id": "369588f7-de40-4eca-bc8d-4c2dbc1cc7f3",
    "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
    "reverse_dns": null,
    "size": "g2.xsmall",
    "region": "lon1",
    "network_id": "63906834-2455-4b72-b0c4-77617ef18b4e",
    "private_ip": "10.0.0.4",
    "public_ip": "31.28.66.181",
    "pseudo_ip": "172.31.0.230",
    "template_id": "f80a1698-8933-414f-92ac-a36d9cfc4ac9",
    "snapshot_id": null,
    "initial_user": "civo",
    "initial_password": "password_here",
    "ssh_key": "61f1b5c8-2c87-4cc7-b1af-6278f3050a28",
    "status": "ACTIVE",
    "notes": null,
    "firewall_id": "default",
    "tags": [
      "web",
      "main",
      "linux"
    ],
    "civostatsd_token": "f84d920f-c74b-4b48-a21e-5ff7a671e5f9",
    "civostatsd_stats": null,
    "civostatsd_stats_per_minute": [],
    "civostatsd_stats_per_hour": [],
    "openstack_image_id": null,
    "rescue_password": null,
    "volume_backed": true,
    "created_at": "2015-09-20T19:31:36+00:00"
  },
  // ...
]

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 12345',
  '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",
  "openstack_server_id": "369588f7-de40-4eca-bc8d-4c2dbc1cc7f3",
  "hostname": "b177ae0e-60fa-11e5-be02-5cf9389be614.clients.civo.com",
  "reverse_dns": null,
  "size": "g2.xsmall",
  "region": "lon1",
  "network_id": "63906834-2455-4b72-b0c4-77617ef18b4e",
  "private_ip": "10.0.0.4",
  "public_ip": "31.28.66.181",
  "pseudo_ip": "172.31.0.230",
  "template_id": "f80a1698-8933-414f-92ac-a36d9cfc4ac9",
  "snapshot_id": null,
  "initial_user": "civo",
  "initial_password": "password_here",
  "ssh_key": "61f1b5c8-2c87-4cc7-b1af-6278f3050a28",
  "status": "ACTIVE",
  "notes": null,
  "firewall_id": "default",
  "tags": [
    "web",
    "main",
    "linux"
  ],
  "civostatsd_token": "f84d920f-c74b-4b48-a21e-5ff7a671e5f9",
  "civostatsd_stats": null,
  "civostatsd_stats_per_minute": [],
  "civostatsd_stats_per_hour": [],
  "openstack_image_id": null,
  "rescue_password": null,
  "volume_backed": true,
  "created_at": "2015-09-20T19:31:36+00:00"
}

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 12345',
  '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 12345',
  '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 12345',
  '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 12345',
  '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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start', {}, headers)

Upgrading (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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize', {size: "g1.small"}, 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 setting the firewall for 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 12345',
  '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 12345',
  '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 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/instances/b177ae0e-60fa-11e5-be02-5cf9389be614', headers)