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)

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 SSH keys known 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)