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:

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

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:

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

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

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.

Response

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

{
  "result": "success"
}

Example of retagging an instance

• Curl
• Node.js
• Ruby

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

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

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

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:

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

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:

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

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

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)