RESTful API

You can use this API either by setting up your own mist.io installation as described in our Developer Guide or by using our hosted service at https://mist.io

Authenticate through https://mist.io

POST mist.io/auth

Authenticate to mist.io service

Example request:

POST /auth
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "email":"user376@mail.com",
  "password":"mysuperpassword"
}

Example response:

{
   "mist_api_token": "4a2c2j08099809709as098087832843e561abb495c4a30726a8590f73adad",
   "current_plan":
   {
       "started": 1384966750.686227,
       "has_expired": false,
       "promo_code": "PROMO50",
       "expiration": 1416502750.686229,
       "title": "Basic"
   },
   "user_details":
   {
       "country": "Greece",
       "number_of_servers": "1-5",
       "number_of_people": "1-5",
       "name": "John Doe",
       "company_name": "mist"
   }
}

Using this api token in your header you can now use all of mist.io’s API by passing in your headers:

Authorized: 4a2c2j08099809709as098087832843e561abb495c4a30726a8590f73adad

In case you have your own installation of mist, you do not have to authenticate and get a token to use mist.io’s RESTful API. However by doing so you can have your own setup and use the premioum services of mist such as monitoring, adding rules and alerts to your machine.

Supported Providers

GET /providers

List of all supported providers

Example request:

GET /providers
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

{
  "supported_providers": [
    {
      "provider": "bare_metal",
      "title": "Bare Metal Server"
    },
    {
      "provider": "ec2_ap_northeast",
      "title": "EC2 AP NORTHEAST"
    },
    {
      "provider": "ec2_ap_southeast",
      "title": "EC2 AP SOUTHEAST"
    },
    {
      "provider": "ec2_ap_southeast_2",
      "title": "EC2 AP Sydney"
    },
    {
      "provider": "ec2_eu_west",
      "title": "EC2 EU Ireland"
    },
    {
      "provider": "ec2_sa_east",
      "title": "EC2 SA EAST"
    },
    {
      "provider": "ec2_us_east",
      "title": "EC2 US EAST"
    },
    {
      "provider": "ec2_us_west",
      "title": "EC2 US WEST"
    },
    {
      "provider": "ec2_us_west_oregon",
      "title": "EC2 US WEST OREGON"
    },
    {
      "provider": "nephoscale",
      "title": "NephoScale"
    },
    {
      "provider": "digitalocean",
      "title": "DigitalOcean"
    },
    {
      "provider": "linode",
      "title": "Linode"
    },
    {
      "provider": "openstack",
      "title": "OpenStack"
    },
    {
      "provider": "rackspace:dfw",
      "title": "Rackspace DFW"
    },
    {
      "provider": "rackspace:ord",
      "title": "Rackspace ORD"
    },
    {
      "provider": "rackspace:iad",
      "title": "Rackspace IAD"
    },
    {
      "provider": "rackspace:lon",
      "title": "Rackspace LON"
    },
    {
      "provider": "rackspace:syd",
      "title": "Rackspace AU"
    },
    {
      "provider": "rackspace_first_gen:us",
      "title": "Rackspace US (OLD)"
    },
    {
      "provider": "rackspace_first_gen:uk",
      "title": "Rackspace UK (OLD)"
    },
    {
      "provider": "softlayer",
      "title": "SoftLayer"
    },
    {
      "provider": "openstack:az-1.region-a.geo-1",
      "title": "HP Cloud US West AZ 1"
    },
    {
      "provider": "openstack:az-2.region-a.geo-1",
      "title": "HP Cloud US West AZ 2"
    },
    {
      "provider": "openstack:az-3.region-a.geo-1",
      "title": "HP Cloud US West AZ 3"
    },
    {
      "provider": "openstack:region-b.geo-1",
      "title": "HP Cloud US East"
    }
  ]
}

Backends Actions

GET /backends

List of all added backends

Example request:

GET /backends
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

[
   {
       "state": "wait",
       "apikey": "A09009NUMIQCIHA",
       "title": "EC2 AP NORTHEAST",
       "enabled": true,
       "region": "",
       "provider": "ec2_ap_northeast",
       "poll_interval": 10000,
       "id": "2tK74h4mXbj8nNohljLIzqc4SHn3"
   },
   {
       "state": "wait",
       "apikey": "myapikey",
       "title": "Rackspace DFW",
       "enabled": true,
       "region": "dfw",
       "provider": "rackspace",
       "poll_interval": 10000,
       "id": "3po809NuIjqiNgqqmDJAKSLWp6"
   }
]
POST /backends

Add Backend

Example request:

Add EC2 Backend

{
    "title":"EC2 AP Sydney",
    "provider":"ec2_ap_southeast_2",
    "apikey":"POIHJOINPOIMIQCIHA",
    "apisecret":"09jLlilkjIU087JKHgjhguy90ur"
}

Add Openstack Backend

{
    "title":"OpenStack",
    "provider":"openstack",
    "apikey":"myuser",
    "apisecret":"superstronpassword",
    "apiurl":"http://31.53.71.90:5000/v2.0",
    "tenant_name":"mist"
}
Json Parameters:
 
  • title (string) – required Title of the backend
  • provider (string) – required Provider as found in supported providers list
  • apikey (string) – APIKEY or username (depending on the provider)
  • apisecret (string) – APISECRET or password (depending on the provider)
  • apiurl (string) – APIURL needed by Openstack and HP Cloud
  • tenant_name (string) – Tenant needed by Openstack and HP Cloud
  • machine_ip (string) – Ip address needed when adding Bare Metal Server
  • machine_key (string) – Id of ssh key needed when adding Bare Metal Server
  • machine_user (string) – User for Bare Metal Server
  • region (string) – Necessary only if there is a custom Openstack region

Example response:

{
   "status": "off",
   "tenant_name": "",
   "id": "48emAUzL9teVYhkyJc9koRaPXEDp",
   "index": 2,
   "apikey": "POIHJOINPOIMIQCIHA",
   "title": "EC2 AP Sydney",
   "region": "",
   "poll_interval": 10000,
   "apiurl": "",
   "provider": "ec2_ap_southeast_2",
   "enabled": true
}
DELETE /backends/{backend_id}

Delete backend

Example request:

DELETE /backends/2tK74h4mXbjjLlkjjO4SHn3
Host: mist.io
Accept: application/json; charset=UTF-8
PUT /backends/{backend_id}

Rename backend

Example request:

PUT /backends
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "new_name":"Renamed Backend"
}
Json Parameters:
 
  • new_name (string) – required New name for backend
POST /backends/{backend_id}

Toggle state of backend between enabled and disabled

Example request:

POST /backends/2tK74h4mXbjjLlkjjO4SHn3
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "newState":"False"
}
Json Parameters:
 
  • newState (string) – required True to enable, False to disable backend
GET /backends/{backend_id}/sizes

List of all sizes provided by backend

Example request:

GET /backends/2tK74h4mXbjjLlkjjO4SHn3/sizes
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

[
   {
       "name": "Micro Instance",
       "price":
       {
           "mswin": "$0.035/hour",
           "sles": "$0.037/hour",
           "mswinSQLWeb": "$0.081/hour",
           "rhel": "$0.087/hour",
           "linux": "$0.027/hour"
       },
       "ram": 613,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 15,
       "id": "t1.micro"
   },
   {
       "name": "Small Instance",
       "price":
       {
           "mswinSQL": "$0.706/hour",
           "mswinSQLWeb": "$0.161/hour",
           "mswin": "$0.115/hour",
           "rhel": "$0.155/hour",
           "linux": "$0.088/hour",
           "sles": "$0.122/hour"
       },
       "ram": 1740,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 160,
       "id": "m1.small"
   },
   {
       "name": "Medium Instance",
       "price":
       {
           "mswinSQL": "$0.821/hour",
           "mswinSQLWeb": "$0.276/hour",
           "mswin": "$0.23/hour",
           "rhel": "$0.22/hour",
           "linux": "$0.175/hour",
           "sles": "$0.234/hour"
       },
       "ram": 3700,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 410,
       "id": "m1.medium"
   },
   {
       "name": "Large Instance",
       "price":
       {
           "mswinSQL": "$1.051/hour",
           "mswinSQLWeb": "$0.506/hour",
           "mswin": "$0.46/hour",
           "rhel": "$0.419/hour",
           "linux": "$0.35/hour",
           "sles": "$0.465/hour"
       },
       "ram": 7680,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 850,
       "id": "m1.large"
   },
   {
       "name": "Extra Large Instance",
       "price":
       {
           "mswinSQL": "$1.511/hour",
           "mswinSQLWeb": "$0.966/hour",
           "mswin": "$0.92/hour",
           "rhel": "$0.769/hour",
           "linux": "$0.7/hour",
           "sles": "$0.815/hour"
       },
       "ram": 15360,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 1690,
       "id": "m1.xlarge"
   },
   {
       "name": "High-Memory Extra Large Instance",
       "price":
       {
           "mswinSQL": "$1.161/hour",
           "mswinSQLWeb": "$0.616/hour",
           "mswin": "$0.57/hour",
           "rhel": "$0.574/hour",
           "linux": "$0.505/hour",
           "sles": "$0.62/hour"
       },
       "ram": 17510,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 420,
       "id": "m2.xlarge"
   },
   {
       "name": "High-Memory Double Extra Large Instance",
       "price":
       {
           "mswinSQL": "$1.731/hour",
           "mswinSQLWeb": "$1.186/hour",
           "mswin": "$1.14/hour",
           "rhel": "$1.079/hour",
           "linux": "$1.01/hour",
           "sles": "$1.125/hour"
       },
       "ram": 35021,
       "driver": "Amazon EC2 (ap-northeast-1)",
       "bandwidth": null,
       "disk": 850,
       "id": "m2.2xlarge"
   }
]
GET /backends/{backend_id}/locations

List locations provided by backend

Example request:

GET /backends/2tK74h4mXbjjLlkjjO4SHn3/locations
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

[
   {
       "country": "Japan",
       "id": "0",
       "name": "ap-northeast-1a"
   },
   {
       "country": "Japan",
       "id": "1",
       "name": "ap-northeast-1b"
   },
   {
       "country": "Japan",
       "id": "2",
       "name": "ap-northeast-1c"
   }
]

Keys Actions

GET /keys

List added keys

Example request:

GET /keys
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

[
   {
       "default_key": true,
       "id": "passwordless",
       "machines":
       [
           [
               "2tKqwqDWFFWFDWFESgzqc4SHn3",
               "i-c0ca59c5",
               1389715866.596957,
               "ec2-user",
               "true"
           ]
       ],
       "name": "passwordless"
   },
   {
       "default_key": false,
       "id": "Key2",
       "machines":
       [
       ],
       "name": "Key 2"
   }
]

For each Key a list of associated machines is returned with backend_id, machine_id, username_of_machine, if_sudo in this order

PUT /keys

Add Key

Example request:

PUT /keys
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "id":"MyKey",
  "priv":"-----BEGIN RSA PRIVATE KEY-----OoiknlOnNJNKCAQEAtbBji1OMHW2bS2Va..."
}
Json Parameters:
 
  • id (string) – required Name of new key
  • priv (string) – required Private ssh key
POST /keys

Ask mist to generate a new private key

Example request:

GET /keys
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

{
  "priv":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCA..."
}
DELETE /keys/{key_id}

Delete key

Example request:

DELETE /keys/{key_id}
Host: mist.io
Accept: application/json; charset=UTF-8
PUT /keys/{key_id}

Rename key

Example request:

PUT /keys/{key_id}
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "new_id":"New Key Name"
}
Json Parameters:
 
  • new_id (string) – required New name for key
POST /keys/{key_id}

Set default key

Example request:

POST /keys/{key_id}
Host: mist.io
Accept: application/json; charset=UTF-8
GET /keys/{key_id}/private

Get private key

Example request:

GET /keys/{key_id}/private
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

"-----BEGIN RSA PRIVATE KEY-----\nMIIE..."
GET /keys/{key_id}/public

Get public key

Example request:

GET /keys/{key_id}/public
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

"ssh-rsa AAAAB3NzaC1yc2EAAAADAQA..."

Images Actions

GET /backends/{backend_id}/images

List available images for this backend

Example request:

GET /backends/2tK74h4mXbjjLlkjjO4SHn3/images
Host: mist.io
Accept: application/json; charset=UTF-8

{
  "search_term":"Gentoo"
}
Json Parameters:
 
  • search_term (string) – not required

If search_term is given, mist will return only images that include the search term, otherwise mist will return all available images for the given backend. If the given backend is an EC2 Backend, mist will search through all EC2 images including community and custom images.

Example response:

[
    {
       "star": false,
       "id": "73764eb8-3c1c-42a9-8fff-71f6beefc6a7",
       "name": "Gentoo 13.3",
       "extra":
       {
           "status": "ACTIVE",
           "updated": "2013-11-21T19:12:29Z",
           "created": "2013-10-15T20:02:10Z",
           "minDisk": 0,
           "progress": 100,
           "minRam": 512,
           "serverId": null,
           "metadata":
           {
               "os_distro": "gentoo",
               "com.rackspace__1__visible_core": "1",
               "com.rackspace__1__build_rackconnect": "0",
               "com.rackspace__1__release_id": "600",
               "image_type": "base",
               "com.rackspace__1__release_build_date": "2013-10-15_11-22-13",
               "com.rackspace__1__source": "kickstart",
               "org.openstack__1__os_distro": "org.gentoo",
               "cache_in_nova": "True",
               "com.rackspace__1__visible_rackconnect": "1",
               "com.rackspace__1__release_version": "6",
               "com.rackspace__1__platform_target": "PublicCloud",
               "org.openstack__1__os_version": "13.3",
               "auto_disk_config": "True",
               "com.rackspace__1__options": "0",
               "os_type": "linux",
               "com.rackspace__1__build_core": "1",
               "com.rackspace__1__visible_managed": "0",
               "org.openstack__1__architecture": "x64",
               "com.rackspace__1__build_managed": "0"
           }
       }
    }
]

Machines Actions

GET /backends/{backend_id}/machines

List of all added machines for this backend

Example request:

GET /backends/2tK74h4mXbjjLlkjjO4SHn3/machines
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

[
   {
       "can_start": false,
       "can_reboot": true,
       "uuid": "447c23edbe944911f23145538915865ebddec230",
       "name": "i-5ebfdc59",
       "tags":
       [
           "ap-northeast-1a"
       ],
       "can_stop": true,
       "can_destroy": true,
       "extra":
       {
           "status": "running",
           "productcode":
           [
           ],
           "groups":
           [
               null
           ],
           "tags":
           {
           },
           "instanceId": "i-5ebfdc59",
           "dns_name": "ec2-173-21-215-201.ap-northeast-1.compute.amazonaws.com",
           "launchdatetime": "2014-01-13T13:58:03.000Z",
           "iam_profile": null,
           "imageId": "ami-2f61fe2e",
           "kernelid": "aki-42992843",
           "keyname": "Mykey",
           "availability": "ap-northeast-1a",
           "clienttoken": "",
           "launchindex": "0",
           "ramdiskid": null,
           "private_dns": "ip-10-153-6-20.ap-northeast-1.compute.internal",
           "instancetype": "t1.micro"
       },
       "public_ips":
       [
           "170.21.215.111"
       ],
       "private_ips":
       [
           "10.153.6.20"
       ],
       "imageId": "ami-2f61fe2e",
       "state": "running",
       "can_tag": true,
       "id": "i-5ebfdc59",
       "size": "t1.micro"
   }
]
POST /backends/{backend_id}/machines

Create machine

Example request:

POST /backends/2tK74h4mXbjjLlkjjO4SHn3/machines
Host: mist.io
Accept: application/json; charset=UTF-8

{
    "name":"WebServer 3",
    "key":"MyKey2",
    "image":"ami-2f61fe2e",
    "location":"0",
    "size":"t1.micro",
    "script":"echo `uptime` > new_file.txt",
    "image_extra":"",
    "disk":""
}
Json Parameters:
 
  • name (string) – required Name of the machine
  • key (string) – required The id of the key to be associated with the machine
  • image (string) – required Id of image to be used
  • location (string) – required Id of the location to be used
  • size (string) – required Id of size to be used
  • namerequired Bash command to be run when machine is initiated, given as a string
  • image_extra (string) – required Needed only by Linode backend, otherwise empty string
  • disk (string) – required Needed only by Linode backend, otherwise empty string

Example response:

{
   "public_ips":
   [
       "50.253.51.216"
   ],
   "extra":
   {
       "status": "running",
       "productcode":
       [
       ],
       "groups":
       [
           null
       ],
       "tags":
       {
           "Name": "WebServer 3"
       },
       "instanceId": "i-50dd7257",
       "dns_name": "ec2-50-253-51-216.ap-northeast-1.compute.amazonaws.com",
       "launchdatetime": "2014-01-15T05:37:50.000Z",
       "iam_profile": null,
       "imageId": "ami-2f61fe2e",
       "kernelid": "aki-42992843",
       "keyname": "MyKey2",
       "availability": "ap-northeast-1a",
       "clienttoken": "",
       "launchindex": "0",
       "ramdiskid": null,
       "private_dns": "ip-10-160-226-156.ap-northeast-1.compute.internal",
       "instancetype": "t1.micro"
   },
   "id": "i-50dd7257",
   "private_ips":
   [
       "10.160.226.156"
   ],
   "name": "WebServer 3"
}
POST /backends/{backend_id}/machines/{machine_id}

Machine actions like reboot, destroy, shutdown and start

Example request:

  POST /backends/2tK74h4mXbjjLlkjjO4SHn3/machines/i-50aa7257
  Host: mist.io
  Accept: application/json; charset=UTF-8

{
    "action":"reboot"
}
Json Parameters:
 
  • action (string) – required Can be reboot, shutdown, start or destroy depending on the available actions for each machine
POST /backends/{backend_id}/machines/{machine_id}/metadata

Add tags/metadata for machine

Example request:

POST /backends/2tK74h4mXbjjLlkjjO4SHn3/machines/i-50aa7257/metadata
Host: mist.io
Accept: application/json; charset=UTF-8

{
    "tag":"Backup Machine"
}
Json Parameters:
 
  • tag (string) – required Tags are used as metadata for each machine and can be handy to group machines with same tags

Shell

GET /backends/{backend_id}/machines/{machine_id}/shell?host={host_ip}&command={shell_command}

Run shell command in machine. Mist will yield an html body with the command’s output.

Example request:

GET /backends/2tK74h4mXbjjLlkjjO4SHn3/machines/i-50aa7257/shell?host=129.113.146.116&command=uptime
Host: mist.io
Accept: application/json; charset=UTF-8

Example response:

<html>
<body>
<script type='text/javascript'>parent.appendShell \
(' 06:29:06 up 1 day, 21:00,  1 user,  load average: 0.00, 0.01, 0.05<br/>'); \
</script>
<script type='text/javascript'>parent.completeShell(1);</script>
</body>
</html>

Error Codes

400:Bad Request
401:Unauthorized
403:Forbidden
404:Not Found
405:Not Allowed
409:Conflict
500:Internal Error
503:Service Unavailable