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.

[
  {
    "id": "773aea72-d068-4cb7-8e08-28841acef0cb",
    "code": "ubuntu-18.04",
    "name": "Ubuntu 18.04",
    "account_id": null,
    "image_id": null,
    "volume_id": "61c2cfe2-f7f3-46e7-b5c9-7b03ae25ea86",
    "short_description": "Ubuntu 18.04",
    "description": "The freely available Ubuntu 18.04 OS, minimally installed with just OpenSSH server",
    "default_username": "ubuntu",
    "cloud_config": "#cloud-config contents"
  },
  // ...
]

Example of listing available templates

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

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');
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 = 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).
code This is a unqiue, alphanumerical, short, human readable code for the template (required).
name This is a short human readable name for the template (optional).
volume_id This is the ID of a bootable volume, either owned by you or global (optional; but must be specified if no template_id is specified).
image_id This is the Openstack Glance Image ID or the ID of another template, either owned by you or global (optional; but must be specified if no volume_id is specified).
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. (this is technically optional, but you won't really be able to use instances without it - see our learn guide on templates for more information)

Response

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

{
  "result": "success",
  "id": "283d5ee6-fa9f-4e40-8e1a-bdc28812d593"
}

Example of creating a template

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/templates \
  -F name=My%20Linux%201.0 -F volume_id=61c2cfe2-f7f3-46e7-b5c9-7b03ae25ea86 -F short_description=... -F description=... -F cloud_config=@/some/file/path
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/templates',
  {
    "name": "My Linux 1.0",
    "volume_id": "61c2cfe2-f7f3-46e7-b5c9-7b03ae25ea86",
    "short_description": "...",
    "description": "...",
    "cloud_config": "..."
  },
  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/templates', 'name=My%20Linux%201.0&volume_id=61c2cfe2-f7f3-46e7-b5c9-7b03ae25ea86&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.

{
  "id": "283d5ee6-fa9f-4e40-8e1a-bdc28812d593",
  "code": "my-linux-1.0",
  "name": "My Linux 1.0",
  "account_id": null,
  "image_id": null,
  "volume_id": "e9f6e4d8-be7b-40c0-979d-4669813aa1ca",
  "short_description": "...",
  "description": "...",
  "default_username": "ubuntu",
  "cloud_config": "..."
}

Example of updating a template

curl -H "Authorization: bearer 12345" -X PUT https://api.civo.com/v2/templates/283d5ee6-fa9f-4e40-8e1a-bdc28812d593 \
  -F name=My%20Linux%201.0 -F volume_id=e9f6e4d8-be7b-40c0-979d-4669813aa1ca -F short_description=... -F description=... -F cloud_config=@/some/file/path
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/templates/283d5ee6-fa9f-4e40-8e1a-bdc28812d593',
  {
    "code": "my-linux-1.0",
    "name": "My Linux 1.0",
    "volume_id": "e9f6e4d8-be7b-40c0-979d-4669813aa1ca",
    "short_description": "...",
    "description": "...",
    "cloud_config": "..."
  },
  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/templates/283d5ee6-fa9f-4e40-8e1a-bdc28812d593', 'name=My%20Linux%201.0&volume_id=e9f6e4d8-be7b-40c0-979d-4669813aa1ca&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/283d5ee6-fa9f-4e40-8e1a-bdc28812d593
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/templates/283d5ee6-fa9f-4e40-8e1a-bdc28812d593',
  function (error, response, body) {
    if (!error && response.statusCode == 202) {
      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/templates/283d5ee6-fa9f-4e40-8e1a-bdc28812d593', headers)