API

Networks

To manage the private networks for an account, there are a set of APIs for listing them, as well as adding, renaming and removing them by ID.


Create a private network

Creating a private network is done by sending a POST request to the https://api.civo.com/v2/networks resource.

Request

The following parameter should be sent along with the request:

Name Description
label (required) a string that will be the displayed name/reference for the network
region (optional) the identifier for the region, from the current region list (a random one will be picked by the system if not specified)
cidr_v4 (optional) An RFC 1918-compliant CIDR, e.g. "10.11/160.0/24" for the range of IP addresses to be allocated in the network.
nameservers_v4 (optional) A comma-separated list of IPv4 addresses of 2-3 name servers that resources created in the network will use for DNS lookups.

Response

The response from the server will just be a confirmation of success.

{
    "result": "success",
    "label": "my-network",
    "id": "8c97b398-3aaf-4e53-beb1-c40500dc0065"
}

Example of creating a private network

curl -H "Authorization: bearer 12345" \
  https://api.civo.com/v2/networks -d label=my-network
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/networks',
  {
    form: {
      label: 'my-network'
    }
  },
  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/networks', 'label=my-network', headers)

Listing the private networks

Listing the labels of the private networks is done by sending a GET request to the https://api.civo.com/v2/networks resource.

Request

This request accepts an optional region parameter (query string) containing the name of the region where the network is located. A random one will be picked by the system if not specified.

Response

The response from the server will be a list of the networks for the current account holder.

[
    {
        "id": "8c97b398-3aaf-4e53-beb1-c40500dc0065",
        "default": false,
        "name": "cust-433e075e-4393-my-network",
        "label": "my-network"
    },
    {
        "id": "5c16ab17-933a-46ed-96c6-8a093a0179e1",
        "default": true,
        "name": "cust-433e075e-808d-default",
        "label": "Default"
    }
]

Example of listing the networks

curl -H "Authorization: bearer 12345" \
  https://api.civo.com/v2/networks
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

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

Renaming a private network

The account holder can rename a private network at any time, by sending a PUT request to https://api.civo.com/v2/networks/:id

Request

Name Description
label (required) a string that will be the displayed name/reference for the network
region (required) the identifier for the region, from the current region list

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.

{
    "result": "success",
    "id": "8c97b398-3aaf-4e53-beb1-c40500dc0065",
    "label": "my-new-network"
}

Example of renaming a private network

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/networks/12345 -d label=my-new-network -d region=LON1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/networks/12345',
  {
    "label": "my-new-network"
  }
  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/networks/12345', "label=my-new-network" headers)

Removing a private network

The account holder can remove a private network, providing there are no instances using it. This action is performed by sending a DELETE request to https://api.civo.com/v2/networks/: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 network is located.

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 removing a private network

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

var request = require('request');

request.del(
  'https://api.civo.com/v2/networks/12345',
  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/networks/12345', headers)