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 disk image, 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 (required) a fully qualified domain name that should be set as the instance's hostname
size (required) the name of the size, from the current size list, e.g. "g2.small"
network_id (required) this must be the ID of the network from the network list
template_id (required) the ID for the disk image to use to build the instance, from the current disk image list
count (optional) the number of instances to create (default is 1)
firewall_id (optional) the ID for firewall from firewall list. The firewall must exists in the network (see network_id). If left blank and network_id is default network, the default firewall will be used (open to all).
reverse_dns (optional) a fully qualified domain name that should be used as the instance's IP's reverse DNS (uses the hostname if unspecified)
region (optional) the identifier for the region, from the current region list (a random one will be picked by the system if not specified)
public_ip (optional) this should be either none or create. 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 (default is create)
initial_user (optional) 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 (optional) 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)
script (optional) the contents of a script that will be uploaded to /usr/local/bin/civo-user-init-script on your instance, read/write/executable only by root and then will be executed at the end of the cloud initialization
tags (optional) 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. The script element only appears if one was sent at creation time.

{
    "id": "779d651a-8e10-4019-9cc0-448451d16157",
    "name": "test-b775c2ea",
    "hostname": "test",
    "account_id": "73993076-f1dc-4b53-88d8-158d97d7be92",
    "size": "g3.small",
    "firewall_id": "e9bcefa3-f942-43a3-98f5-354608f0d55e",
    "source_type": "diskimage",
    "source_id": "ubuntu-focal",
    "network_id": "950c8a1c-79d5-4e57-925a-6e941ebec8a3",
    "initial_user": "root",
    "initial_password": "foobar",
    "ssh_key": "ssh-rsa ...",
    "ssh_key_id": "21aa424f-13be-44db-a908-6d4625c7e4f4",
    "tags": [
        "first",
        "second"
    ],
    "user_script": "SGVsbG8gd29ybGQh",
    "status": "BUILDING",
    "civostatsd_token": "12fa5f73-9cca-4d9f-aca8-b7733a422a6b",
    "public_ip": null,
    "private_ip": null,
    "ipv6": null,
    "namespace_id": null,
    "notes": "",
    "reverse_dns": "",
    "cpu_cores": 1,
    "ram_mb": 2048,
    "disk_gb": 25
}

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"
// At a shell prompt run:
// npm init -y
// npm i --save request

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

You can optionally filter the list of instances by passing in:

Name Description
tags (optional) a space separated list of tags
page (optional) which page of results to return (defaults to 1)
per_page (optional) how many instances to return per page (defaults to 20)
region (optional) the identifier for the region, from the current region list (a random one will be picked by the system if not specified)

Response

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

{
    "page": 1,
    "per_page": null,
    "pages": 1,
    "items": [
        {
            "id": "779d651a-8e10-4019-9cc0-448451d16157",
            "name": "test-b775c2ea",
            "hostname": "test",
            "account_id": "73993076-f1dc-4b53-88d8-158d97d7be92",
            "size": "g3.small",
            "firewall_id": "e9bcefa3-f942-43a3-98f5-354608f0d55e",
            "source_type": "diskimage",
            "source_id": "ubuntu-focal",
            "network_id": "950c8a1c-79d5-4e57-925a-6e941ebec8a3",
            "initial_user": "root",
            "initial_password": "foobar",
            "ssh_key": "ssh-rsa ...",
            "ssh_key_id": "21aa424f-13be-44db-a908-6d4625c7e4f4",
            "tags": [
                "first",
                "second"
            ],
            "user_script": "SGVsbG8gd29ybGQh",
            "status": "ACTIVE",
            "civostatsd_token": "12fa5f73-9cca-4d9f-aca8-b7733a422a6b",
            "public_ip": "212.2.247.88",
            "private_ip": "192.168.1.2",
            "ipv6": null,
            "namespace_id": null,
            "notes": "",
            "reverse_dns": "",
            "cpu_cores": 1,
            "ram_mb": 2048,
            "disk_gb": 25
        }
    ]
}

Example of listing instances

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances?region=LON1
// At a shell prompt run:
// npm init -y
// npm i --save request

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');
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', 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 the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

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": "779d651a-8e10-4019-9cc0-448451d16157",
    "name": "test-b775c2ea",
    "hostname": "test",
    "account_id": "73993076-f1dc-4b53-88d8-158d97d7be92",
    "size": "g3.small",
    "firewall_id": "e9bcefa3-f942-43a3-98f5-354608f0d55e",
    "source_type": "diskimage",
    "source_id": "ubuntu-focal",
    "network_id": "950c8a1c-79d5-4e57-925a-6e941ebec8a3",
    "initial_user": "root",
    "initial_password": "foobar",
    "ssh_key": "ssh-rsa ...",
    "ssh_key_id": "21aa424f-13be-44db-a908-6d4625c7e4f4",
    "tags": [
        "first",
        "second"
    ],
    "user_script": "SGVsbG8gd29ybGQh",
    "status": "ACTIVE",
    "civostatsd_token": "12fa5f73-9cca-4d9f-aca8-b7733a422a6b",
    "public_ip": "212.2.247.88",
    "private_ip": "192.168.1.2",
    "ipv6": null,
    "namespace_id": null,
    "notes": "",
    "reverse_dns": "",
    "cpu_cores": 1,
    "ram_mb": 2048,
    "disk_gb": 25
}

Example of retrieving an instance

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances/12345?region=NYC1
    
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/instances/12345?region=NYC1',
  {},
  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/12345?region=NYC1', 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 (required) a space separated list of tags
region (required) the identifier for the region, from the current region list

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
// At a shell prompt run:
// npm init -y
// npm i --save request

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');
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/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 request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

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?region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/reboots?region=NYC1',
  {},
  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/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/reboots?region=NYC1', {}, 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 request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

Response

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

{
  "result": "success"
}

Example of shutting down an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop?region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop?region=NYC1',
  {},
  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/4a07ac84-70f8-11e5-8fe9-5cf9389be614/stop?region=NYC1', {}, 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 request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

Response

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

{
  "result": "success"
}

Example of restarting a stopped instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start?region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start?region=NYC1',
  {},
  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/4a07ac84-70f8-11e5-8fe9-5cf9389be614/start?region=NYC1', {}, 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 (required) the identifier for the size, from the current list
region (required) the identifier for the region, from the list of regions, where the instance is running

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 resizing an instance

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize -d size=g3.small -d region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize',
  {
    "size": "g3.small",
    "region": "NYC1"
  },
  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/4a07ac84-70f8-11e5-8fe9-5cf9389be614/resize', {size: "g1.small", region: "NYC1"}, 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 (required) the ID of the firewall to use, from the current list. The firewall must exists in the network (see instance's network_id). If left blank and network_id is default network, the default firewall will be used (open to all).
region (required) the identifier for the region, from the list of regions, where the instance is running

Response

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

{
    "id": "779d651a-8e10-4019-9cc0-448451d16157",
    "name": "test-b775c2ea",
    "hostname": "test",
    "account_id": "73993076-f1dc-4b53-88d8-158d97d7be92",
    "size": "g3.large",
    "firewall_id": "b6dfca68-059e-48c8-85a7-bac37996fde1",
    "source_type": "diskimage",
    "source_id": "ubuntu-focal",
    "network_id": "950c8a1c-79d5-4e57-925a-6e941ebec8a3",
    "initial_user": "root",
    "initial_password": "foobar",
    "ssh_key": "ssh-rsa ...",
    "ssh_key_id": "21aa424f-13be-44db-a908-6d4625c7e4f4",
    "tags": [
        "first",
        "second"
    ],
    "user_script": "SGVsbG8gd29ybGQh",
    "status": "ACTIVE",
    "civostatsd_token": "12fa5f73-9cca-4d9f-aca8-b7733a422a6b",
    "public_ip": "212.2.247.88",
    "private_ip": "192.168.1.2",
    "ipv6": null,
    "namespace_id": null,
    "notes": "",
    "reverse_dns": "",
    "cpu_cores": 4,
    "ram_mb": 8192,
    "disk_gb": 100
}

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
// At a shell prompt run:
// npm init -y
// npm i --save request

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');
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/4a07ac84-70f8-11e5-8fe9-5cf9389be614/firewall', {name: "restrictive-firewall"}, 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 requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running. No confirmation step is required; this step will remove the instance 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 200 OK.

{
    "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?region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

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');
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/instances/b177ae0e-60fa-11e5-be02-5cf9389be614', headers)