Mist.io Remote API

Mist.io includes a full featured REST API that will help you perform all tasks through it. The documentation includes examples in curl and Python.

1.Introduction

2.Clouds

3.Machines

4.Scripts

5.Keys

1. Introduction

1.1 Authenticating

To authenticate with the Mist.io API, you'll need an Authorization token. To generate one, log in to  https://mist.io and enter the account page by clicking at the gravatar at the top right and choosing "Account". Go to the API tokens section and click on Create Token. 

You'll need to provide your password again for security reasons. Copy your token once it is created and store it somewhere safe. This will be the Authorization token used in the examples below.

1.2 Curl example

Mist.io uses a RESTful API. You can test the API using curl. For example the following command will return a JSON object with all your clouds:

user@user:/tmp$ curl -X GET -H "Authorization: 51fb1fc5554d0861d80843dd2612234365feb8211e9d191a70fde56a340bf742" https://mist.io/api/v1/clouds
	

A POST command will add a cloud:

user@user:/tmp$ curl -H "Authorization: 51fb1fc5554d0861d80843dd2612234365feb8211e9d191a70fde56a340bf742" -X POST -d '{"title": "Digital Ocean", "provider": "digitalocean", "token": "digital_ocean_api_token"}' https://mist.io/api/v1/clouds
	

the response will look like this:

{"status": "off", "tenant_name": null, "id": "d68beac38992448e21319468a910b0695", "index": 8, "apikey": "digital_ocean_api_token", "title": "Digital Ocean", "region": null, "poll_interval": 10000, "apiurl": null, "provider": "digitalocean", "enabled": true}
	

To delete a cloud, you can send a DELETE request to  https://mist.io/api/v1/clouds/:id To delete the cloud we just added, we can get the id from the response above. Alternatively, we can get a list of all our clouds and their ids using the first command in this section.

user@user:/tmp$ curl -H "Authorization: 51fb1fc5554d0861d80843dd2612234365feb8211e9d191a70fde56a340bf742" -X DELETE https://mist.io/api/v1/clouds/d68beac38992448e21319468a910b0695
	

1.3 Python example

You can also use Python to access the API. We will use the excellent requests lib (./bin/pip install requests if not installed) that simplifies sending API requests. At the start of your python script, add:

import json, requests
headers = {'Authorization': TOKEN}
	

We will use these headers on any request from now on. To get a json object of all our clouds all we need to do is:

clouds = requests.get('https://mist.io/api/v1/clouds', headers=headers)
	

A POST request will add a cloud:

resp = requests.post('https://mist.io/api/v1/clouds', headers=headers, data=json.dumps({'title': 'Digital Ocean', 'provider': 'digitalocean', 'token': 'digital_ocean_token'}))
	

The response should look like this:

resp.content<br>'{"status": "off", "tenant_name": null, "id": "0380d6941ed12c22aec3330000a5716d", "index": 9, "apikey": "digital_ocean_token", "title": "Digital Ocean", "region": null, "poll_interval": 10000, "apiurl": null, "provider": "digitalocean", "enabled": true}'<br>
	

Using the cloud id we can also delete a cloud through the API:

resp = requests.delete('https://mist.io/api/v1/clouds/0380d6941ed12c22aec3330000a5716d', headers=headers)

2. Clouds

2.1 List clouds

GET api/v1/clouds

List of all added clouds on our account.

Example response:

[
 {"state": "online", "apikey": "XYZ_replaced", "tenant_name": "", "title": "Linode", 
"enabled": true, "region": "", "provider": "linode", "poll_interval": 10000, "id": "HiYUF5YDyxdfaNpxSs6FQakw4Wb"},
 {"state": "online", "apikey": "XYZ_replaced", "tenant_name": "", "title": "DigitalOcean",
 "enabled": true, "region": "", "provider": "digitalocean", "poll_interval": 10000, "id": "2UmAeuwfMZRMHz9bTFEE9zmEm1hJ"}, 
 {"state": "online", "apikey": "unwebme", "tenant_name": "", "title": "Rackspace Chicago", "enabled": true, "region": "ord", "provider": "rackspace", "poll_interval": 10000,
 "id": "2zMXgapqqaw9bSNUzSmuygFLy6Kp"}
]

This returns a list of the added clouds, providing info as the cloud id. Using a cloud id we can get a listing of the machines within the cloud, the id also is useful for performing other actions as creating machines on this cloud, listing of sizes, images, locations of this cloud etc.

2.1.2 Add cloud

POST /api/v1/clouds

The request should contain some of the following data, depending on the provider:

{
  "api_key": "string",
  "api_secret": "string",
  "apiurl": "string",
  "docker_port": "string",
  "machine_key": "string",
  "machine_port": "string",
  "machine_user": "string",
  "provider": "string",
  "remove_on_error": "string",
  "tenant_name": "string",
  "title": "string"
}

Status Codes:

  • 200 - no error
  • 401 - unauthorized or wrong cloud credentials

To get a list of all supported providers, you can run:

GET /api/v1/providers

for a detailed breakdown of what arguments each provider requires, check  http://docs.mist.io/article/141-adding-clouds-api

2.1.3 Delete cloud

DELETE /api/v1/clouds/{cloud_id}

This request will delete the cloud with id cloud_id. Mist.io monitoring will be disabled on machines belonging to that cloud.

Query Parameters:

  • cloud_id – required, the id of the cloud. Can be obtained with list clouds

Status Codes:

  • 200 - no error
  • 401 - unauthorized
  • 404 - cloud not found

2.2 List Cloud sizes

GET /api/v1/clouds/{cloud_id}/sizes

List of all sizes provided by the cloud provider. Most often used before creating a machine in order to specify a size id for machines to be provisioned. 

Example request:

GET /api/v1/clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ/sizes
Host: mist.io

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
 {
  "name": "512mb", 
  "price": "$0.00744/hour, $5.0/month",
  "ram": "512mb", 
  "driver": "Digital Ocean",
  "bandwidth": 0,
  "disk": "20G SSD",
  "id": "512mb"},
 {
  "name": "1gb",
  "price": "$0.01488/hour,
  $10.0/month",
  "ram": "1gb", 
  "driver": "Digital Ocean",
  "bandwidth": 0,
  "disk": "30G SSD",
  "id": "1gb"}
 }
]

Query Parameters:

  • cloud_id – required, the id of the cloud. Can be obtained with list clouds

Status Codes:

  • 200 - no error
  • 404 - cloud not found
  • 503 - cloud unavailable

2.3 List Cloud locations

GET /api/v1/clouds/{cloud_id}/locations

List of all regions provided by the cloud provider. Most often used before creating a machine in order to specify the region id for machines to be provisioned. 

Example request:

GET /api/v1/clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ/locations
Host: mist.io

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8  

[
 {
  "country": null,
  "id": "nyc1",
  "name": "New York 1"
 }, 
 {
  "country": null, 
  "id": "sfo1",
  "name": "San Francisco 1"}
]

Query Parameters:

  • cloud_id – required, the id of the cloud. Can be obtained with list clouds

Status Codes:

  • 200 - no error
  • 404 - cloud not found
  • 503 - cloud unavailable

2.4 List Cloud images

GET /api/v1/clouds/{cloud_id}/images

List available images for this cloud

Example request:

GET /api/v1/clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ/images
Host: mist.io

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8  

[
 {
  "star": true, 
  "id": "6372581", 
  "name": "Debian 6.0 x64", 
  "extra": {"distribution": "Debian"}},
 {
  "star": true, "id": "6372662", 
  "name": "Debian 6.0 x32",
  "extra": {"distribution": "Debian"}}
]
Query Parameters:
  • cloud_id – required, the id of the cloud. Can be obtained with list clouds
JSON Parameters:
  • search_term (string) - optional. If search_term is given, mist.io will return only images that include the search term, otherwise it will return all available images for the given cloud. If the given cloud is an EC2 Cloud, mist.io will search through all EC2 images including community and custom images for this term.
Status Codes:
  • 200 - no error
  • 404 - cloud not found
  • 503 - cloud unavailable

2.5 List Cloud networks

3. Machines

Machine related actions. Machines could be virtual machines, docker containers, or bare metal servers.

3.1 List machines

GET /api/v1/clouds/{cloud_id}/machines

Returns all the machines for a cloud, including information as name, state, public and private ips, and extra metadata. This differs from provider to provider, for example some providers return a datetime when the server was provisioned, the current pricing model for the server, the image it has been provisioned and other useful info.

Example request

GET /api/v1/clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ/machines
Host: mist.io

Example response

[
 {"can_start": false, "tags": [], "can_destroy": true, "private_ips": [], "imageId": null, "can_tag": false, "id": "4499827", "size": null, "can_reboot": true, "uuid": "4cb9ffc3787dd801b022be449427920d71ebec34", "can_stop": true, "extra": {"kernel": {"version": "3.2.0-4-amd64", "id": 3285, "name": "Debian 7.0 x64 vmlinuz-3.2.0-4-amd64 (3.2.65-1+deb7u1)"}, "name": "monitor.markos.com", "backup_ids": [], "created_at": "2015-03-17T14:49:09Z", "features": ["virtio"], "memory": 512, "disk": 20, "image": {"min_disk_size": 20, "slug": "debian-7-0-x64", "name": "7.0 x64", "created_at": "2015-01-28T16:09:29Z", "id": 10322059, "regions": ["nyc1", "ams1", "sfo1", "nyc2", "ams2", "sgp1", "lon1", "nyc3", "ams3", "fra1", "tor1"], "distribution": "Debian", "type": "snapshot", "public": true}, "size": {"price_monthly": 5.0, "available": true, "transfer": 1.0, "price_hourly": 0.00744, "regions": ["nyc1", "sgp1", "ams1", "sfo1", "nyc2", "lon1", "nyc3", "ams3", "ams2", "fra1"], "vcpus": 1, "memory": 512, "disk": 20, "slug": "512mb"}}, "public_ips": ["107.170.218.51"], "name": "monitor.markos.com", "state": "running", "can_rename": true}, 
{"can_start": false, "tags": [], "can_destroy": true, "private_ips": ["10.128.253.139"], "imageId": null, "can_tag": false, "id": "6220698", "size": null, "can_reboot": true, "uuid": "a0200f99aa61e2f9a60c96813cf86132778d2cd3", "can_stop": true, "extra": {"kernel": {"version": "3.13.0-57-generic", "id": 5175, "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-57-generic"}, "name": "kvm", "backup_ids": [], "created_at": "2015-07-20T10:00:00Z", "features": ["private_networking", "virtio"], "memory": 512, "disk": 20, "image": {"min_disk_size": 20, "slug": null, "name": "14.04 x64", "created_at": "2015-07-17T16:39:08Z", "id": 12790328, "regions": ["nyc1", "ams1", "sfo1", "nyc2", "ams2", "sgp1", "lon1", "nyc3", "ams3", "fra1", "tor1"], "distribution": "Ubuntu", "type": "snapshot", "public": false}, "size": {"price_monthly": 5.0, "available": true, "transfer": 1.0, "price_hourly": 0.00744, "regions": ["nyc1", "sgp1", "ams1", "sfo1", "nyc2", "lon1", "nyc3", "ams3", "ams2", "fra1"], "vcpus": 1, "memory": 512, "disk": 20, "slug": "512mb"}}, "public_ips": ["104.131.217.171"], "name": "kvm", "state": "running", "can_rename": true}
]

Query Parameters:

  • cloud_id – required, the id of the cloud. Can be obtained with list clouds

Status Codes:

  • 200 - no error
  • 404 - cloud not found

3.2 Machine actions

POST /api/v1/clouds/{cloud_id}/machines/{machine_id}

Machine actions like reboot, destroy, shutdown, start, rename and resize.

Example request

POST /api/v1/clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ/machines/7350375
Host: mist.io 

{"action": "start"}

Query Parameters:

  • cloud_id – required, the id of the cloud. Can be obtained with list clouds
  • machine_id - required, the id of the machine. Can be obtained with list machines
  • action - required, the action to perform. Can be one of 'start', 'stop', 'reboot', 'destroy', 'resize', 'rename'
  • plan_id - optional, in use with resize. Specifies the plan that the VM will be resized to. Only a subset of the supported clouds provide this
  • name - optional, in use with rename. Specifies the new name of the server. Only a subset of the supported clouds provide this

Status Codes:

  • 200 - no error
  • 404 - cloud not found

4. Scripts

script related actions. Scripts can be executable scripts or ansible playbooks, and are currently supported only by the Mist.io SaaS version at  https://mist.io

4.1 List scripts

GET /scripts

lists all user scripts. Response is a list of the available scripts, containing script id, name, description and content. 

Example response

[
 {"description": "", "extra": {}, "script": "#!/bin/bash\ntouch `date +%Y-%m-%dT%H:%M`", "exec_type": "executable", "entrypoint": "", "user": "mgogoulos@unweb.me", "script_id": "f19f52311a654ae495094251d96cc649", "location_type": "inline", "name": "proto"}, 
{"description": "", "extra": {}, "script": "#!/bin/bash\napt-get update; apt-get -y upgrade", "exec_type": "executable", "entrypoint": "", "user": "mgogoulos@unweb.me", "script_id": "221e63b2d55a45ff95cfabda0f88c04d", "location_type": "inline", "name": "deutero"}
]

4.2 Add script

POST /scripts

adds a script. Scripts can be executables or ansible playbooks

Example request

POST /scripts 
Host: mist.io 

{
 "name":"tester",
 "script":"#!/bin/bash\ntouch ~/me", 
 "location_type":"inline", 
 "exec_type":"executable"
}

Example response

{"description": "", "extra": {}, "deleted": false, "script": "#!/bin/bash\ntouch ~/me", "exec_type": "executable", "entrypoint": "", "user": "mgogoulos@unweb.me", "script_id": "0f2c68d324bd42328bcf4115fed0e689", "location_type": "inline", "name": "tester"}
the response contains the id of the newly added script.

Json Parameters:

  • name – required, the name of the script
  • location_type - required, should be one of 'url','github','inline'. Url will be imported, so make sure it is the script itself (in plain, not html). Github can be a github repository (eg https://github.com/mistio/ansible-wordpress), while inline is if you plan to upload a custom script. 
  • exec_type - required, should be one of executable (for any executable) or ansible (for ansible playbooks)
  • script - required if location_type is inline. This is the script. Should start with a badge (#!/bin/bash, #!/usr/bin/env python2 etc)

4.3 Run script

POST /scripts/{script_id}

will run the script id to the machine specified (via cloud_id and machine_id). Get the cloud_id and machine_id via list clouds and list machines

Example request

POST /scripts/0f2c68d324bd42328bcf4115fed0e689
Host: mist.io   

{
  "cloud_id": "2UmAeuwfMZRMHz9bTFEE9zmEm1hJ",
  "machine_id": "7655629"
}

Example response

{"job_id": "68c09b1dcefa4a5ebe6f485407438fef"}

the job id, we can have full access to the logs through it

Query Parameters:

  • script_id – required, the script_id. Can be obtained with list scripts

Json Parameters:

  • cloud_id - required, the id of the cloud. Can be obtained with list clouds
  • machine_id - required, the id of the machine. Can be obtained with list machines

4.4 Show script logs

GET /jobs/{job_id}

This will return the output of a script that has run on a server. Details include when the job was started, when it was finished, and what has been the output (or errors). 

Example request

GET https://mist.io/jobs/c5d7d891a7534a878ba582ed9fa9dac3

The job_id can be found by running a GET /scripts/{script_id} with the script id being the id of the script we have run

GET https://mist.io/jobs/c5d7d891a7534a878ba582ed9fa9dac3

This will return a dict with job ids, each job_id representing a time the script has been run on a server.

4.5 Delete script

DELETE /scripts/{script_id}

delete the script with id script_id. 

Example request

DELETE /scripts/f19f52311a654ae495094251d96cc649
Host: mist.io

Query Parameters:

  • script_id – required, the id of the script to delete. Can be obtained with list scripts

Status Codes:

  • 200 - no error
  • 404 - script not found

5. Keys

ssh keys actions

5.1 List keys

GET /keys

lists all ssh keys. Response is a list of the available keys, containing ids of keys, and machines the keys are associated with

Example response

[
 {
  "id": "staging", 
  "machines": [["2UmAeuwfMZRMHz9bTFEE9zmEm1hJ", "7350364", 1442416344.683256, "root", true, 22]], "isDefault": true
 }
]

5.1.1 Get public key

GET /keys/{key_id}/public

response is the public key of the key with id key_id. 

5.1.2 Get private key

GET /keys/{key_id}/private

response is the private key of the key with id key_id. 

5.2 Add key 

PUT /keys

Add an ssh key. 

Example request

PUT /keys HTTP/1.1
Host: mist.io


{
 "id": "staging_key",
 "priv": "-----BEGIN RSA PRIVATE KEY-----\nMIIEp"
 ....
}

JSON Parameters:

  • id - required. A name for the ssh key
  • priv - required. An ssh RSA private key
Status Codes:
  • 200 - no error
  • 400 - invalid private key
  • 409 - keypair exists, if key id exists already

5.3 Generate key

POST /keys

response is an RSA 2048bit ssh key generated by mist.io. The key is not stored on the users keys. 

5.4 Delete key

DELETE /keys/{key_id}

deletes the ssh key with id key_id. 

5.5 Associate key to a machine

PUT  /clouds/{cloud_id}/machines/{machine_id}/keys/{key_id}

Associates an existing ssh key with a server on a cloud provider. Will add the association only after successful ssh connection

Example request

PUT /clouds/2UmAeuwfMZRMHz9bTFEE9zmEm1hJ666/machines/7350375/keys/staging

{
 "host": "3of3.unweb.me"
}

Example response

[["2UmAeuwfMZRMHz9bTFEE9zmEm1hJ", "7350364", 1442421110.957179, "root", true, 22], ["2UmAeuwfMZRMHz9bTFEE9zmEm1hJ", "7350375", 1442421213.769826, "root", null, 22]]

Response after successful association contains the list of cloud_id/machine_id and time the host was probed, plus the username and ssh port that has been used.

Query Parameters:

  • cloud_id  - required
  • machine_id  - required
  • key_id - required

JSON Parameters:

  • host - required. The hostname or ip of the machine that the key will be associated. 
  • user - optional. If not specified 'root' will be used
  • port - optional. If not specified 22 will be used
Status Codes:
  • 200 - no error
  • 400 - bad request, host is missing
  • 404 - not found (invalid key_id or cloud_id or machine_id)
  • 503 - invalid host

Still need help? Contact Us Contact Us