API Intro

Our ReSTful HTTP cloud computing API allows users to create drives, upload and download drive images, and create and control virtual servers on our infrastructure. You can download our ready-made command line tools, or make direct calls to the API from your own scripts.

We provide ready-made scripts to let you control your cloud computing platform infrastructure without writing any code.

Linux/Unix and Windows Cygwin users should download our simple command line tool , drive upload tool and drive download tool.

Once you have these scripts, in just two commands, you can upload a drive image and boot a server. See below for the full input and output to do exactly this, or head straight to the documentation here.

Worked example – using the tools

Each command corresponds to a single API HTTP GET or POST, with the URL corresponding to the command-line arguments, and the input and output data exactly as seen on the command line here.

1. Set API end-point for your availability zone   For example, if your account is in our London West (lon-b) zone, use api.lon-b.elastichosts.com. Alternatively, you can hard-code the value of EHURI in your local copy of the scripts.

$ export EHURI=https://api.<zone>.elastichosts.com/

2. Set authentication credentials (from account profile)   Omit the secretkey if you are running on a very old Unix system that leaks the content of your environment to other users via ps e. You will then be interactively prompted for your secret key by curl. Alternatively, you can hard-code the value of EHAUTH in your local copy of the scripts, but make sure they aren’t world-readable!

$ export EHAUTH=<user uuid >:<secret API key>

3. Create drive and upload image   We use the drive upload tool to automatically upload in gzipped chunks.

$ elastichosts-upload image.raw

Created drive 08c92dd5-70a0-4f51-83d2-835919d254df of size


Uploading 2 chunks of 5242880 bytes: .. completed

NOTE: for reference, a more basic upload with the raw API would be:

$ elastichosts -c drives create << EOF | grep drive

> name TestDrive

> size 10000000


drive 08c92dd5-70a0-4f51-83d2-835919d254df

$ elastichosts -f image.raw drives 08c92dd5-70a0-4f51-83d2-835919d254df write

4. Boot a server from the drive   Boot a server from the drive, with 2000 core MHz and 1024 MB RAM. (Set "persistent false" to make a temporary server that will be destroyed when shut down.)

$ elastichosts -c servers create << EOF

> name TestServer

> cpu 2000

> mem 1024

> ide:0:0 08c92dd5-70a0-4f51-83d2-835919d254df

> boot ide:0:0

> nic:0:model e1000

> nic:0:dhcp auto

> vnc auto

> persistent true

> password XXXXXXXX


server 85ef58c8-6f5d-4f7f-8f1c-0c19d45d7c1c

user a9ce98d2-e306-4222-b6dc-a8c3cf903120

name TestServer

cpu 2000

mem 1024

boot ide:0:0

ide:0:0 08c92dd5-70a0-4f51-83d2-835919d254df

ide:0:0:read:bytes 0

ide:0:0:read:requests 0

ide:0:0:write:bytes 0

ide:0:0:write:requests 0

nic:0:dhcp auto



nic:0:mac 6e:65:re:1d:51:8a

nic:0:model e1000

nic:0:rx:bytes 0

nic:0:rx:packets 0

nic:0:tx:bytes 0

nic:0:tx:packets 0

persistent true

smp:cores 1

started 1493804466

status active

vnc auto


password XXXXXXXX

Using the API

The API is implemented in a ReST style, using the URL to specify an object and an action, HTTP GET to read state and HTTP POST to change state. In the description below, API URLs are relative to the stem https://api-<zone>.elastichosts.com/ where <zone> refers to the availability zone of your Elastichosts account.

Users, drives and servers are identified by UUIDs, which are assigned by our infrastructure and passed as a string in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.


API calls must use HTTP Basic Authentication, specifying the user’s UUID as the username and their secret API key as the password. Both are available from the user’s account profile.

Data formats

The API can be used in either text/plain(default) or application/json modes. You should specify the type of input data with an HTTP Content-Type: header, and request a type for output with an HTTP Accept: header. text/plain is the default if no headers are set.

The API sends or receives one of three types of data, according to the call:

Single object, key value pairs of properties


Multiple lines of text, each containing a key, followed by a space, followed by the value. e.g.:

name TestServer

cpu 4000

mem 2048

Data is accompanied by the HTTP header ‘X-Elastic-Output: properties’


JSON object. e.g.:


"cpu":4000, "mem":2048}

Multiple objects, list of values


Multiple lines of text, each containing a space separated list of values for the same set of keys. e.g.:




Data is accompanied by the HTTP header ‘X-Elastic-Output: list’


JSON array of objects. e.g.:

[{"type":"ip", "resource":""},

{"type":"ip", "resource":""},

{"type":"ip", "resource":""}]

Multiple objects, key value pairs of properties for each


Multiple lines of text, each containing a key, followed by a space, followed by the value. Blank lines separating objects. e.g.:

name TestServer1

cpu 2000

mem 1024

name TestServer2

cpu 4000

mem 2048

Data is accompanied by the HTTP header ‘X-Elastic-Output: properties list’


JSON array of objects. e.g.:

[{"name":"TestServer1", "cpu":2000,


{"name":"TestServer2", "cpu":4000,



Errors are returned with an appropriate HTTP status code, an X-Elastic-Error header specifying the error type, and a text description in the HTTP body. The error types are:

HTTP Status Code X-Elastic Error Meaning
200 OK n/a Command succeeded, data returned (possibly 0 length)
204 No Content n/a Command succeeded, no data returned (by definition)
400 Bad Request usage Invalid input data to command
401 Unauthorized auth HTTP Basic Authentication missing or incorrect
402 Payment Required billing Account balance and/or subscriptions do not cover command
404 Not Found missing Command, drive, server or other object not found
405 Method Not Allowed method GET used on command expecting POST
409 Conflict busy Drive, server or other resource is busy
500 Internal Server Error failed Failed command
500 Internal Server Error system System error
507 Insufficient Storage full Drive or other resource is full