API

Templates

Instances are built from a template. Templates may be either a base OS install such as Ubuntu 14.04 LTS, a control-panel based hosting setup or a fully setup application ready to configure for your use.


Listing available templates

Listing the available templates is possible by making a GET request to the https://api.civo.com/v2/templates resource.

Request

This request doesn't take any parameters.

Response

The response from the server will be a JSON array of templates.

[
  {
    "name": "Ubuntu 14.04 LTS",
    "description": "The freely available Ubuntu 14.04 OS, minimally installed with just OpenSSH server",
    "minimum_cpu_cores": 1,
    "minimum_ram_mb": 512,
    "minimum_disk_gb": 25,
    "default_username": "ubuntu"
  },
  // ...
]

Example of listing available templates

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/templates
var request = require('request');

request.get(
  'https://api.civo.com/v2/templates',
  {},
  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 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = get('v2/templates', headers)

Create a new template

Any user can create templates for their account, only administrators can create global templates.

New templates are created by sending a POST request to https://api.civo.com/v2/templates.

Request

The required parameters are listed below. Template IDs must be unique within a given account, but can be the same as a global template (to override that template for your instances).

Name Description
id This is a short identifier for the template, it should be lowercase letters, dashs, underscores, full stop/periods and numbers only (optional: defaults to a new UUID).
name This is a short human readable name for the template (optional).
image_id This is the Openstack Glance Image ID or the ID of another template, either owned by you or global (required).
short_description A one line description of the template (optional)
description A multi-line description of the template, in Markdown format (optional).
default_username The default username to suggest that the user creates (optional: defaults to civo).
cloud_config Commonly referred to as 'user-data', this is a customisation script that is run after the instance is first booted. We recommend using cloud-config as it's a great distribution-agnostic way of configuring cloud servers. If you put $INITIAL_USER in your script, this will automatically be replaced by the initial user chosen when creating the instance, $INITIAL_PASSWORD will be replaced with the random password generated by the system, $HOSTNAME is the fully qualified domain name of the instance and $SSH_KEY will be the content of the SSH public key. (optional)

Response

The response is a JSON object that simply confirms that the template was created.

{
  "result": "success"
}

Example of creating a template

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/templates \
  -F id=my-linux-1.0 -F name=My%20Linux%201.0 -F image_id=123456 -F short_description=... -F description=... -F cloud_config=@/some/file/path
var request = require('request');

request.post(
  'https://api.civo.com/v2/templates',
  {
    "id": "my-linux-1.0",
    "name": "My Linux 1.0",
    "image_id": "123456",
    "short_description": "...",
    "description": "...",
    "cloud_config": "..."
  },
  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 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/templates', 'id=my-linux-1.0&name=My%20Linux%201.0&image_id=123456&short_description=...&description=...&cloud_config=...', headers)

Update a template

After creating a custom template, any user can update their template.

Templates are updated by sending a PUT request to https://api.civo.com/v2/templates/:id.

Request

The parameters are as per creation of templates.

Response

The response is a JSON object that simply confirms that the template was updated.

{
  "result": "success"
}

Example of updating a template

curl -H "Authorization: bearer 12345" -X put https://api.civo.com/v2/templates/my-linux-1.0 \
  -F name=My%20Linux%201.0 -F image_id=123456 -F short_description=... -F description=... -F cloud_config=@/some/file/path
var request = require('request');

request.put(
  'https://api.civo.com/v2/templates/my-linux-1.0',
  {
    "name": "My Linux 1.0",
    "image_id": "123456",
    "short_description": "...",
    "description": "...",
    "cloud_config": "..."
  },
  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 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.put('/v2/templates/my-linux-1.0', 'name=My%20Linux%201.0&image_id=123456&short_description=...&description=...&cloud_config=...', headers)

Deleting a template

An account holder can remove one of their custom templates by sending a DELETE request to https://api.civo.com/v2/templates/:id. Global templates CANNOT be removed by the API, they must be removed directly from the system (due to the risk of breakages for a large number of account holders).

Request

This request takes no parameters, only the id of the template to delete is in the URL. No confirmation step is required, this step will remove the template 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 202 Accepted.

{
  "result": "success"
}

Example of deleting a template

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/templates/my-template
var request = require('request');

request.del(
  'https://api.civo.com/v2/templates/my-template',
  function (error, response, body) {
    if (!error && response.statusCode == 202) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/templates/my-template', headers)