BetterServers API

BetterServers API Documentation

The BetterServers API may be used to provision, manage, and delete VM instances, volumes, snapshots, and other data center resources. All API calls must be cryptographically signed and made via HTTPS. This document explains how to use the REST API directly.
The BetterServers API may be used to provision and manage data center resources (such as server instances) by making HTTP requests to API URIs. Each URI represents a collection or item in a collection of resources. The BetterServers API will respond with an HTTP status code and often a JSON document.
The sections labeled API requests and Request authentication below describe in detail how to make an authenticated API HTTP request. The section labeled API responses describes what an API response looks like.

You should be familiar with common terminology and conventions in RFC 2616, including HTTP methods, HTTP headers, URIs, etc.

The BetterServers API uses several kinds of strings that act as resource identifiers, including UUIDs:

4e5cda75-55c2-437b-bf81-d1944453f22e

and hexadecimal encoded SHA-256 hashes:

1fad63ad36bde0c9f671b96d3cd12792b33f5e73448c8ce8455f37f556b4b4e5

For the sake of brevity, this document will generally refer to these as (UUID) and (SHA256) respectively, though sometimes an actual string (or abbreviated version) will be used in an example.

The easiest way to access the BetterServers API is to use one of our API helper libraries available here. We officially support API helpers for the following languages:

  • JavaScript
  • Perl
  • PHP
  • Ruby
  • Python
  • Node.js

These helpers abstract API authentication and the request/response cycle so you can focus on your data center resources.

If your favorite language isn't listed above, or you want to deal with the HTTP API directly, the following sections will help you get going.

Here is a brief but complete example of using the PHP API helper:

<?php
require_once('BetterServersAPI.php');

$api_id     = '4224C98B-E0A6-11E3-18D9-32332ADFB917';
$api_secret = 'WmCUKjD43dlGuAVarqJighfCnVt2s1fRpOWWSgA+5Ym';
$auth_type  = 'LOMA23KA';
$api_host   = 'api.betterservers.com';

$api = new BetterServersAPI(array("api_id"     => $api_id,
                                  "api_secret" => $api_secret,
                                  "auth_type"  => $auth_type,
                                  "api_host"   => $api_host));

$resp = $api->request(array("method" => "GET",
                            "uri"    => "/v1/accounts/$api_id/instances"));

$response_content = json_decode($resp['content'],true);
$servers = $response_content['instances'];
?>
<table>
    <thead>
        <tr>
            <th>UUID</th><th>Name</th><th>CPUs</th><th>RAM (MB)</th><th>Template (OS)</th>
        </tr>
    </thead>
    <tbody>
        <?php foreach($servers as $server) { ?>
        <tr>
            <td><?= $server['id']; ?></td>
            <td><?= $server['displayname']; ?></td>
            <td><?= $server['cpucount']; ?> CPUs</td>
            <td><?= $server['memory']; ?> MB</td>
            <td><?= $server['templatename']; ?></td>
        </tr>
        <?php } ?>
    </tbody>
</table>
          

In order to make API requests, you will need an API id, secret, and auth type. These are available on the API access page of your account.

BetterServers API requests may be made using any HTTP client: curl, wget, Perl's LWP or mojolicious libraries, Ruby's Patron library, Python's httplib library, PHP's native HTTP library, etc. Virtually any HTTP client capable of communicating via SSL will work.

All API requests must have the following elements:

  • an HTTP method (GET, POST, etc.)
  • a URI naming the resource to be accessed (/v1/accounts/(UUID))
  • a Host header (api.betterservers.com)
  • a Date header (as specified in RFC 2616)
  • a Content-Type header (application/json)
  • a signed Authorization header
  • optional body content

Nearly all HTTP clients supply the method, Host, and Date headers automatically. If your request client suffers from clock drift, you may request the /date resource from api.betterservers.com which will respond with a date representation you may use without modification.

API requests may have additional HTTP headers depending on the content being accessed.

A typical BetterServers API GET request looks like this:

GET https://api.betterservers.com/v1/accounts/(UUID)/isos
Host: api.betterservers.com
Date: Mon, 14 May 2012 16:14:41 GMT
Authorization: (AuthType) (UUID):(SHA256)
          

Here is a common POST request:

POST https://api.betterservers.com/v1/accounts/(UUID)/instances
Content-type: application/json
Host: api.betterservers.com
Date: Mon, 14 May 2012 16:31:18 GMT
Authorization: (AuthType) (UUID):(SHA256)

  {"zone_id":"(UUID)","template_id":"(UUID)","hypervisor":"KVM","service_offering_id":"(UUID)",
   "disk_offering_id":"(UUID)","displayname":"My%20new%20server","hostname":"bananaboat12"}
          

The BetterServers API responds only to HTTPS requests to ensure privacy and authentication; non-HTTPS requests are not supported.

Before diving into the details, if you're planning on using the BetterServers REST API, you should consider using one of the available helper libraries which have been tested. If a helper library is not available in your preferred language, or the helper library is not an option for your environment, read on!

All BetterServers API requests must be signed to ensure the request is made from an authorized user, ensure the request has not been tampered with, and to limit the window of replay attacks. A signed API request is a standard HTTP request with an Authorization header which includes the authentication method (e.g., "TAKU83FA"), the API id (this is analogous to a username in some authentication schemes), and a request signature, like this:

Authorization: TAKU83FA 4e5cda75-55c2-437b-bf81-d1944453f22e:1fad63ad36bde0c9f671b96d3cd12792b33f5e73448c8ce8455f37f556b4b4e5
          

This Authorization header includes the string TAKU83FA followed by a space, followed by the API id (4e5cda75-55c2-437b-bf81-d1944453f22e--a UUID) followed by a colon (':'), followed by the request signature (1fad63ad36bde0c9f671b96d3cd12792b33f5e73448c8ce8455f37f556b4b4e5).

The request signature is created by creating a request string and taking the HMAC SHA-256 digest of the string, using your API secret for the HMAC key. The request string is created by concatenating the following fields with the standard network EOL marker (CRLF):

  • the HTTP method (GET, POST, DELETE, etc.)
  • the fully-qualified hostname (api.betterservers.com)
  • the date as specified in RFC 2616 3.3.1 (e.g., Sun, 06 Nov 2011 08:49:37 GMT)
  • the relative request URI (/v1/accounts/fa05c140.../instances)
  • the body of the request (use the empty string if the request has no body)

In Perl:

my $req_str = join("\x0d\x0a", $method, $host, $date, $uri, $body);
          

In PHP:

$req_str = implode("\r\n", array($method, $host, $date, $uri, $body));
          

In Java:

            String sep = Character.toString((char) 13) + Character.toString((char) 10);
            String joined = "GET" + sep + host + sep + date + sep + uri + sep + payload;
            byte[] digest = mac.doFinal(joined.getBytes(Charset.defaultCharset()));
            String auth   = auth_type + " " + toHexString(digest);
          

Once you have the request string, calculate its HMAC SHA-256 digest with your API secret (not your API id). Both your API id and API secret are available in the API portal area.

Here is an example of a complete API request in Perl using LWP:

use POSIX 'strftime';
use HTTP::Request;
use LWP::UserAgent;
use Digest::SHA 'hmac_sha256_hex';
use JSON 'encode_json';

## the request
my $api_id = 'B2C3B258-3C71-11E3-A82B-89A390C1A40F';
my $secret = '9/gCm0w7C3w7YmBSC3a2eUEYIAECPwtuY4fbQkgZdzk';
my $auth_type = 'QUNO76NU';
my $host = 'api.betterservers.com';
my $date = strftime("%a, %d %b %Y %T GMT", gmtime);
my $uri = "/v1/accounts/$api_id/instances";
my $body = encode_json({plan_id => '6ba7b814-9dad-11d1-80b4-00c04fd430c8'});
my $method = "post";

## create the signature
my $signature = hmac_sha256_hex( join("\x0d\x0a" => (uc($method), $host, $date, $uri, $body)),
                                 $secret );

## use LWP
my $req = HTTP::Request->new(uc($method) => "https://" . $host . $uri);
$req->header(Date => $date);
$req->header(Authorization => $auth_type . " " . $api_id . ":" . $signature);
$req->content($body);
my $res = LWP::UserAgent->new->request($req);
          

Here is an example using Mojolicious; if you're using Perl, we recommend Mojolicious over LWP for its ease of installation, ease of use, improved aesthetics, and ability to run non-blocking:

use Mojo::UserAgent;
use Mojo::JSON;
use Digest::SHA 'hmac_sha256_hex';
use POSIX 'strftime';

## the request
my $api_id = 'B2C3B258-3C71-11E3-A82B-89A390C1A40F';
my $secret = '9/gCm0w7C3w7YmBSC3a2eUEYIAECPwtuY4fbQkgZdzk';
my $auth_type = 'QUNO76NU';
my $host = 'api.betterservers.com';
my $date = strftime("%a, %d %b %Y %T GMT", gmtime);
my $uri = "/v1/accounts/$api_id/instances";
my $body = Mojo::JSON->new->encode({plan => '6ba7b814-9dad-11d1-80b4-00c04fd430c8'});
my $method = "post";

## create the signature
my $signature = hmac_sha256_hex( join("\x0d\x0a" => (uc($method), $host, $date, $uri, $body)),
                                 $secret );

my $res = Mojo::UserAgent->new->$method("https://" . $host . $uri,
                                        { Date => $date,
                                          "Content-Type" => "application/json",
                                          Authorization => "$auth_type $api_id:$signature" },
                                        $body)->res;
          

and here's an alternative approach using curl instead of LWP:

open my $pipe, "-|", ('curl', '--include', '--request', 'POST',
                      '--header', "Date: $date",
                      '--header', "Host: api.betterservers.com",
                      '--header', "Authorization: $auth_type $api_id:$signature",
                      '--data-binary', $body,
                      "https://api.betterservers.com" . $uri) or die $!;
my $response = join('', <$pipe>);
close $pipe;
          

This code provisions a new VM instance under the account identified by $api_id (actually, the examples are missing some parameters in the interest of space).

The BetterServers API follows RFC 2616 recommendations and other commonly accepted standards for RESTful API designs regarding HTTP response codes. Your HTTP client should always check the HTTP response code in order to take any additional action if necessary.

With few exceptions, the BetterServers API responses return resources and error codes in JSON format. For example, if you made an API call to create a new instance but left off a critical parameter, you should receive this HTTP response:

400 Bad request
Content-type: application/json

{"error":"hypervisor parameter required"}
          

If you corrected this oversight and no other errors were present, you should receive this HTTP response:

202 Accepted
Content-type: application/json

{"job_id":"(UUID)"}
          

Note that the successful response code is 202 Accepted rather than 201 Created or 200 OK; this is intentional because it indicates that the resource you requested may take some time to create. You are given a job id you may use to query the API for the status of the job.

Resource URIs that merely return information about the state of a resource will generally return 200 OK while resource URIs that create new resources will generally return 201 Created.

Other possible response codes are detailed under each API endpoint.

Some resources such as instances have a search endpoint that allows you to specify boolean logic to winnow the result set.

The syntax for boolean searches is as follows:

[+|-][field] [operator] (value)

Spaces are optional but may aid readability.

+|- (include or exclude), field and operator are optional. If neither of + or - are specified, an include (+) is assumed. If field is not specified, all fields will be searched. If operator is not specified, a colon (:) is used, which implies a "contains" relationship.

The inclusion/exclusion (+ or -) allows you to eliminate certain criteria from your result set. For example, you may include all instances whose templatename includes the string "freebsd", but exclude any whose instancename includes the word "test":

+templatename:freebsd -instancename:test

Remember that + is the default if neither + or - is specified.

Valid fields depend on the resource you're searching; for example, the instances resource allows you to search any of the fields included in the list instances results, including the following fields:

cpunumber, cpuspeed, cpuused, created, displayname, hostname,
hypervisor, id, instancename, isoid, memory, name, networkkbsread,
networkkbswrite, networkid, passwordenabled, macaddress, netmask,
ipaddress, traffictype, type, serviceoffering, serviceofferingname,
state, templatedisplaytext, templateid, templatename
          

See each resource for all fields.

Operators determine how records are matched; for example, the colon means the specified value may appear anywhere in the specified field. An equals sign (= or ==) means the specified value must exactly match the value of the specified field. The following list describes valid operators and their semantics. Keep in mind that if no field is specified, all fields will be used in the comparison.

  • :: the specified field contains the specified value as a substring
  • =: the specified field exactly matches the specified value
  • ==: identical to =
  • <, <=, >, or >=: the specified numeric field fulfills the inequality operation. If the field is non-numeric, an error is returned.

For example, to match all instances whose CPU speed is greater than 2000:

cpuspeed>=2000

To match all instances whose cpuspeed value is greater than 2000 but whose displayname does not contain the word "dev":

cpuspeed>=2000 -displayname:dev

Use these methods to create, manage, and remove API accounts. An API account allows a customer the ability to create, destroy, and modify their own virtual instances. Changes to the customer account are automatically billed and reflected in the reseller billing information available in the BetterServers billing area.

View account resource totals.
method
GET
URL
/v1/accounts/{api_id}/totals
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D56FEB04-C8FB-11E1-A175-92A2D15968DE/totals
HTTP Response
status-code
200
reason-phrase
OK
body
  • instance_total: number of instances allocated
  • network_total: number of networks allocated
  • volume_total: number of volumes allocated
  • vpc_total: number of VPCs allocated
examples
  1. {"volume_total":"6","instance_total":"3","vpc_total":"1","network_total":"1"}
View account info.
method
GET
URL
/v1/accounts/{api_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D56FEB04-C8FB-11E1-A175-92A2D15968DE
HTTP Response
status-code
200
reason-phrase
OK
body
  • api_id: API identifier for this account
  • api_secret: API secret for this account
  • account: account identifier (often an email address)
  • disabled: if present, epoch time when the account was/will be disabled
  • is_admin: if true, this account is an administrative account
  • is_read_only_api: if true, this account has read-only API access
  • allow_cs_passthru: if true, this account may make direct CloudStack API calls
  • allow_basic_auth: if true, this account may use HTTP Basic Authentication
examples
  1. {"api_id":"D56FEB04-C8FB-11E1-A175-92A2D15968DE",
     "api_secret":"Djbr05yglCuiudasdfeiFtfw123lj99MYwq",
     "account":"biff@schmoe.org",
     "disabled":null,
     "is_admin":null,
     "is_read_only_api":null,
     "allow_cs_passthru":null,
     "allow_basic_auth":null}
    
View internal account details; these numbers may not reflect additional IP addresses allocated to the account via other means. This call is deprecated; use View account totals instead
method
GET
URL
/v1/accounts/{api_id}/details
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D56FEB04-C8FB-11E1-A175-92A2D15968DE/details
HTTP Response
status-code
200
reason-phrase
OK
body
  • ipavailable: number of IPs available
  • iplimit: maximum allowed IP addresses
  • iptotal: total number of IPs allocated
  • networkavailable: number of networks available
  • networklimit: maximum number of networks allowed
  • networktotal: total number of networks allocated
  • receivedbytes: network bytes received
  • sentbytes: network bytes sent
  • snapshotavailable: number of snapshots available
  • snapshotlimit: maximum number of snapshots allowed
  • snapshottotal: total number of snapshots created
  • vmavailable: number of VMs available
  • vmlimit: maximum number of VMs allowed
  • vmrunning: number of VMs running
  • vmstopped: number of VMs stopped
  • vmtotal: total number of VMs created
  • volumeavailable: number of volumes available
  • volumelimit: maximum number of volumes allowed
  • volumetotal: total number of volumes created
examples
  1. {
      "ipavailable": "Unlimited",
      "iplimit": "Unlimited",
      "iptotal": 0,
      "networkavailable": "Unlimited",
      "networklimit": "Unlimited",
      "networktotal": 0,
      "receivedbytes": 0,
      "sentbytes": 0,
      "snapshotavailable": "Unlimited",
      "snapshotlimit": "Unlimited",
      "snapshottotal": 0,
      "vmavailable": "Unlimited",
      "vmlimit": "Unlimited",
      "vmrunning": 0,
      "vmstopped": 0,
      "vmtotal": 0,
      "volumeavailable": "Unlimited",
      "volumelimit": "Unlimited",
      "volumetotal": 0
    }
View resource totals for all accounts.
This method is available only to admin accounts.
method
GET
URL
/v1/totals
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/totals
HTTP Response
status-code
200
reason-phrase
OK
body
  • instance_total: number of instances allocated
  • network_total: number of networks allocated
  • volume_total: number of volumes allocated
  • vpc_total: number of VPCs allocated
examples
  1. {"volume_total":"6","instance_total":"3","vpc_total":"1","network_total":"1"}
Create a new account.
This method is available only to admin accounts.
method
POST
URL
/v1/accounts
query parameters
(none)
body parameters
  • account: unique account identifier (e.g., an email address)
  • (optional)disabled: an integer representing an epoch time at which this account whould be disabled (default: false)
  • (optional)is_admin: if true, the account will have administrative privileges (default: false)
  • (optional)is_read_only_api: if true, this account has read-only API access (default: false)
  • (optional)allow_basic_auth: if true, this account may authenticate using HTTP Basic Authentication (default: false)
examples
  1. POST /v1/accounts
    
    {"account":"joe@schmoe.org","is_read_only_api":1}
HTTP Response
status-code
201
reason-phrase
Created
body
  • api_id: API identifier for this account
  • api_secret: API secret for this account
  • account: account identifier (usually an email address)
  • disabled: if present, the epoch time when the account was/will be disabled
  • is_admin: if true, this account is an administrative account
  • is_read_only_api: if true, this account has read-only API access
  • allow_cs_passthru: if true, this account may make CloudStack API calls
  • allow_basic_auth: if true, this account may use HTTP Basic Authentication
examples
  1. 201 Created
    
    {"account":"joe@schmoe.org",
    "auth-type":"SomeCompany",
    "api_id":"34259ED6-CF83-11E1-8665-83291D9586CD",
    "api_secret":"Djbr05yglCuiudg93\/U1EAYeiFtfw1i\/s\/+Av99MYwq",
    "is_read_only_api":"1"}
Update an existing account.
This method is available only to admin accounts.
method
PATCH
URL
/v1/accounts/{api_id}
query parameters
(none)
body parameters
  • account: unique account identifier (e.g., an email address)
  • (optional)disabled: an integer representing an epoch time at which this account whould be disabled. Use 0 to enable an account.
  • is_admin: if true, the account will have administrative privileges.
  • is_read_only_api: if true, this account has read-only API access.
  • allow_cs_passthru: if true, this account may make CloudStack API calls.
  • allow_basic_auth: if true, this account may authenticate using HTTP Basic Authentication.
examples
  1. PATCH /v1/accounts/D56FEB04-C8FB-11E1-A175-92A2D15968DE
    
    {"disabled":1342477802,"is_admin":0}
HTTP Response
status-code
200
reason-phrase
OK
body
(same as <% 'create-account' %>)
examples
  1. {"account":"biff@schmoe.org",
    "auth-type":"SomeCompany",
    "api_id":"D56FEB04-C8FB-11E1-A175-92A2D15968DE",
    "api_secret":"99VS5ddOgnk+o05UNfi9XFuDgdZ5vecM2\/ftpE4JKes",
    "disabled":1342477802,
    "is_admin":0}
List accounts matching the supplied criteria, or all accounts if no criteria are given.
This method is available only to admin accounts.
method
GET
URL
/v1/accounts
query parameters
  • (optional)account: the account name (e.g., an email address)
body parameters
(none)
examples
  1. GET /v1/accounts?account=biff%40schmoe.org
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of accounts in the result
  • accounts: a list of account records
examples
  1. {"count":"1",
     "accounts":[{"api_id":"34259ED6-CF83-11E1-8665-83291D9586CD",
                  "api_secret":"Djbr05yglCuiudasdfeiFtfw123lj99MYwq",
                  "account":"biff@schmoe.org",
                  "disabled":null,
                  "is_admin":null,
                  "is_read_only_api":null,
                  "allow_cs_passthru":null,
                  "allow_basic_auth":null}]}
Delete an account.
This method is available only to admin accounts.
method
DELETE
URL
/v1/accounts/{api_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D56FEB04-C8FB-11E1-A175-92A2D15968DE
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the account was successfully removed
examples
  1. 200 OK
    
    {"message":"account removed"}

Snapshots are points in time that the volume can be rolled back to. Backups are all the data either for the entire volume, or a delta from a previous backup point.

Given a volume, create a full backup point for that volume
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/full
query parameters
(none)
body parameters
  • (optional)locations: comma-separated list of location ids
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/full
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: A UUID representing the asynchronous job for the full backup
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "result" : "success", "backupId", "1239adasf-1857-89521ab7a8b1a", "warnings" : "" 
    }
Given a volume, create a incremental backup point for that volume (requires a full backup to have been done on the volume first though)
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/incremental
query parameters
(none)
body parameters
  • (optional)locations: comma-separated list of location ids
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/incremental
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: A UUID representing the asynchronous job for the incremental backup
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "result" : "success", "backupId", "1239adasf-1857-89521ab7a8b1a", "warnings" : "" 
    }
Given a volume, create a downloadable image backup for that volume
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/image
query parameters
(none)
body parameters
  • (optional)locations: comma-separated list of location ids
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/image
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: A UUID representing the asynchronous job for the downloadable backup
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "result" : "success", "backupId", "1239adasf-1857-89521ab7a8b1a", "warnings" : "" 
    }
List all pending backups for either a volume, an account or a domain
method
GET
URL
/v1/accounts/{api_id}/pending-backups
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/pending-backups?volume_id=91234ABD-1251-1239-AB92C18521412
  2. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/pending-backups?by_account=true
  3. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/pending-backups?domain_id=488143B3-3851-8854-8A82118C24418
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: volume uuid
  • uuid: uuid of the backup job
  • uploaded: 0
  • estSize: The estimated size of the backup
  • started: Epoch time when the backup started
  • backup: The name of the backup
  • result: current status of backup
examples
  1. {
     	"volume": "BIGVOLUMEISFORTESTINGONLY",
     	"result": "inprogress",
     	"uuid": "2ac3b93e-aec3-11e2-8333-9cd9fc753a98",
     	"uploaded": 0,
     	"estSize": "633864192",
     	"started": 1367016403,
     	"backup": "backup2"
     }
List all backups for a given volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/91234ABD-1251-1239-AB92C18521412/backups
HTTP Response
status-code
200
reason-phrase
OK
body
  • connection: -
  • date: Date when backup was taken
  • uuid: unique identifier of the backup
  • size: Size of the backup
  • snapshot: The name of the snapshot that this backup was created from
  • backup: backup name
  • volume: The uuid of the volume
  • name: backup name
  • estsize: ? (size is right above here, not sure what this refers to)
  • type: Full, or Incremental
  • creation: Epoch timestamp of the creation time of the backup
examples
  1. {
     	"date": "Fri, 26 Apr 2013 22:23:56 GMT", 
    	"uuid": "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"size": "637821576", 
    	"snapshot": "snapshot1", 
    	"backup": "backup1", 
    	"name": "backup1", 
    	"volume": "BIGVOLUMEISFORTESTINGONLY", 
    	"estsize": "316981248", 
    	"type": "full", 
    	"creation": "1367005901" 
    }
Given a volume, restore a volume to the specified snapshot
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshots/{snapshot_id}/restore
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/snapshots/3a86feea-5a2f-482e-ab9b-1a4e6cd0a051
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: A UUID representing the asynchronous job for the snapshot restore
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "success" : "true" 
    }
List all backups for volumes provided
method
POST
URL
/v1/accounts/{api_id}/backups
query parameters
(none)
body parameters
  • volume_id: An array of volume id's
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/backups
HTTP Response
status-code
200
reason-phrase
OK
body
  • connection: -
  • date: Date when backup was taken
  • uuid: unique identifier of the backup
  • size: Size of the backup
  • snapshot: The name of the snapshot that this backup was created from
  • backup: backup name
  • volume: The uuid of the volume
  • name: backup name
  • estsize: ? (size is right above here, not sure what this refers to)
  • type: Full, or Incremental
  • creation: Epoch timestamp of the creation time of the backup
examples
  1. { "count" : 1, "backups" : { "volume_id" : "91234ABD-1251-1239-AB92C18521412", "count" : 1, "data" : [ {
     	"date": "Fri, 26 Apr 2013 22:23:56 GMT", 
    	"uuid": "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"size": "637821576", 
    	"snapshot": "snapshot1", 
    	"backup": "backup1", 
    	"name": "backup1", 
    	"volume": "BIGVOLUMEISFORTESTINGONLY", 
    	"estsize": "316981248", 
    	"type": "full", 
    	"creation": "1367005901" 
    } ] } }
List available storage locations; image backups have their own storage locations.
method
GET
URL
/v1/accounts/{api_id}/storage-locations
query parameters
  • is_public: show public locations only (used for image backups); defaults to false
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/storage-locations
HTTP Response
status-code
200
reason-phrase
OK
body
  • location: storage storage location
  • id: id of the storage location
examples
  1. {
      "storage-locations": [
        {
          "location": "Provo, UT",
          "id": "5d51549f-c0c0-4231-a903-b32eaf358a80"
        },
        {
          "location": "Los Angeles, CA",
          "id": "2c01fd56-e066-44d1-a825-04b6376b606b"
        }
      ],
      "count": 2
    }
List all snapshots for a given volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshots
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/91234ABD-1251-1239-AB92C18521412/snapshots
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: the uuid of the volume
  • name: Name of the snapshot
  • mountpoint: -
  • avail: -
  • used: 0
  • snapshot: the name of the snapshot
  • creation: epoch creation time
  • refer: 2.38G
examples
  1. {
     	"name": "hdpool0/thisisauuid@cool",
     	"refer": "2.38G",
     	"used": "0",
     	"snapshot": "cool",
     	"avail": "-",
     	"volume": "91234ABD-1251-1239-AB92C18521412",
     	"creation": "1367595985",
     	"mountpoint": "-"
     }
Given a volume and backup id of a downloadable image backup, generate a time limited URL to download that backup
method
POST
URL
/v1/{api_id}/volumes/{volume_id}/backups/{backup_id}/url
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/3d2a4aca-28f7-13c6-1818-15293c34b6aa/url
HTTP Response
status-code
200
reason-phrase
OK
body
  • url: A temporary download link to which you can download the backup
examples
  1. {
      "url" : "http://cheezburger.com/7422405376"
    }
Get status of a specific backup job
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/{job_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/91234ABD-1251-1239-AB92C18521412/backups/438848B2-2851-8739-B777218521412
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: The uuid of the volume
  • backup: backup name
  • uuid: Unique identifier of the backup job (inprogress, error, success, packaging
  • result: The current status of the job
  • started: When the job was started
examples
  1. { 
    	"volume" : "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"backup": "backup1", 
    	"uuid": "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"result" : "inprogress", 
    	"started" : "1367017633" 
    }
Given a volume, create a snapshot for that volume
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshots
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/snapshots
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: A UUID representing the asynchronous job for the snapshot creation
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "result" : "true", "snapshotid", "1239adasf-1857-89521ab7a8b1a" 
    }
List all snapshots for volumes provided
method
POST
URL
/v1/accounts/{api_id}/snapshots
query parameters
(none)
body parameters
  • volume_id: An array of volume id's
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/snapshots
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: the uuid of the volume
  • name: Name of the snapshot
  • mountpoint: -
  • avail: -
  • used: 0
  • snapshot: the name of the snapshot
  • creation: epoch creation time
  • refer: 2.38G
examples
  1. {
     "count" : 1, "snapshots" : [ { 	"volume_id" : "91234ABD-1251-1239-AB92C18521412", "count" : 1, "data" : [ { 	"name": "hdpool0/thisisauuid@cool",
     	"refer": "2.38G",
     	"used": "0",
     	"snapshot": "cool",
     	"avail": "-",
     	"volume": "91234ABD-1251-1239-AB92C18521412",
     	"creation": "1367595985",
     	"mountpoint": "-"
     } ] } }
Restore a volume from a backup, given the volume and backup id
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/{backup_id}/restore
query parameters
(none)
body parameters
  • (optional)location_id: restore the backup stored at this location id
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/2b96feea-8a2f-422e-949b-4a4e62d0a051/restore
HTTP Response
status-code
202
reason-phrase
OK
body
  • job_id: A UUID representing the asynchronous job for the restore
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "success" : "true", "uuid", "1239adasf-1857-89521ab7a8b1a" 
    }
Get status of a specific restore job
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/retores/{job_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/91234ABD-1251-1239-AB92C18521412/restores/438848B2-2851-8739-B777218521412
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: The uuid of the volume
  • backup: backup name
  • uuid: Unique identifier of the backup job (inprogress, error, success, packaging
  • result: The current status of the job
  • started: When the job was started
examples
  1. {
     	 "volume" : "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"backup": "backup1", 
    	"uuid": "e988752b-aebf-11e2-8150-9cd9fc753a98", 
    	"result" : "inprogress", 
    	"started" : "1367017633" 
    }
List all pending backups for either a volume, an account or a domain
method
GET
URL
/v1/accounts/{api_id}/pending-backups-for-volumes
query parameters
(none)
body parameters
  • volume_id: An array of volume id's
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/pending-backups-for-volumes
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: volume uuid
  • uuid: uuid of the backup job
  • uploaded: 0
  • estSize: The estimated size of the backup
  • started: Epoch time when the backup started
  • backup: The name of the backup
  • result: current status of backup
examples
  1. {
     "count" : 1, "backups" : [ { 	"volume": "BIGVOLUMEISFORTESTINGONLY",
     	"result": "inprogress",
     	"uuid": "2ac3b93e-aec3-11e2-8333-9cd9fc753a98",
     	"uploaded": 0,
     	"estSize": "633864192",
     	"started": 1367016403,
     	"backup": "backup2"
     } ] }
List all retores for a given volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/restores
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/91234ABD-1251-1239-AB92C18521412/restores
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: The UUID of the volume
  • started: The epoch timestamp when the restore started
  • uuid: The UUID of the job running the restore
  • backup: The name of the backup
  • result: The status of the restoration process
examples
  1. {
     	"volume": "BIGVOLUMEISFORTESTINGONLY",
     	"result": "inprogress",
     	"started": 1367017633,
     	"backup": "backup1",
     	"uuid": "080c2c53-aec6-11e2-805e-9cd9fc753a98"
     }
Delete given backup id for a volume; if {location_id} is specified, only delete the backup at that location. If no locations are supplied, all backups are deleted.
method
DELETE
URL
/v1/accounts/{api_id}/volumes/{volume_id}/backups/{backup_id}/{location_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/4d5a9aaa-5af7-42d5-af79-d52d33b4165b/backups/aac8feea-122c-a32e-849b-b28862aaac54
HTTP Response
status-code
200
reason-phrase
OK
body
  • backup: A data structure containing an object containing the success attribute
examples
  1. {
      "backup" : {  "success" : "true" } 
    }
Delete a snapshot for a given volume and snapshot id
method
DELETE
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshots
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/snapshots/1b9pfgea-a92f-492e-944b-4a4y62d0a021
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • snapshot: A data structure containing an object containing the success attribute
examples
  1. {
      "job_id" : "2b96feea-8a2f-422e-949b-4a4e62d0a051"
    }
  2. {
     "success" : "true" 
    }
List all restores for volumes given
method
GET
URL
/v1/accounts/{api_id}/pending-restores-for-volumes
query parameters
(none)
body parameters
  • volume_id: An array of volume id's
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/pending-restores-for-volumes
HTTP Response
status-code
200
reason-phrase
OK
body
  • volume: The UUID of the volume
  • started: The epoch timestamp when the restore started
  • uuid: The UUID of the job running the restore
  • backup: The name of the backup
  • result: The status of the restoration process
examples
  1. {
     "count" : 1, "restores" : [ { 	"volume": "BIGVOLUMEISFORTESTINGONLY",
     	"result": "inprogress",
     	"started": 1367017633,
     	"backup": "backup1",
     	"uuid": "080c2c53-aec6-11e2-805e-9cd9fc753a98"
     } ] }

Chains are composite API calls; think of them as functions or methods to invoke multiple, chained API calls on your behalf. Each chain API call is designed to consolidate a sequence of commonly-run API calls.

Deploy a datacenter, network, and server in a single API call. Payload (body) parameters must match the corresponding resource payload (e.g., VPC, network, or server).
method
POST
URL
/v1/accounts/{api_id}/chains/deploy-site
query parameters
(none)
body parameters
  • datacenter: payload for a datacenter (e.g., zone_id, name, cidr, vpc_offering_id, etc.)
  • network: payload for a network (e.g., zone_id, name, network_offering_id, gateway, etc.). No vpc_id parameter is required; the API will supply this.
  • (optional)acl_rules: an array of ACL rules.
  • (optional)server: payload for a server (e.g., zone_id, template_id, hypervisor, etc.). No network_ids parameter is required; the API will supply this.
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/chains/deploy-site
    
    {
      "datacenter": {
        "cidr": "10.99.222.0/24",
        "display_text": "84726.api-test-vpc-84726",
        "name": "84726.api-test-vpc-84726",
        "network_domain": "84726.api-test",
        "vpc_offering_id": "fe7aa774-4329-45e3-8e32-c19d6f6d4da9",
        "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
      },
      "network": {
        "display_text": "84726.api-test-network-1/27-84726",
        "gateway": "10.99.222.1",
        "name": "84726.api-test-network-1/27-84726",
        "netmask": "255.255.255.224",
        "network_offering_id": "86a1011e-e715-46b6-9b5f-21b21af716c9",
        "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
      },
      "acl_rules": [
        {
          "protocol" : "icmp",
          "cidr_list" : "0.0.0.0/0",
          "icmp_code" : -1,
          "icmp_type" : -1,
          "traffic_type" : "ingress"
        }
      ],
      "server": {
        "disk_offering_id": "ed498aa3-9e0b-47c1-b643-091e7437bd1c",
        "display_name": "84726.api-test-vm-84726",
        "hypervisor": "KVM",
        "service_offering_id": "451ef01e-4f60-4320-a034-1bcd500770d5",
        "template_id": "7c2a39a6-52da-4891-a61f-aca3365a13bd",
        "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
      }
    }
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • queue_ids: a list of UUIDs (in the order they were submitted to the queue) referring to the internal job queue handling these jobs. These jobs may be queried using the queue resource.
examples
  1. {
      "queue_ids": [
        "699BBDD6-781D-11E3-8BA0-80D9B09D27A5",
        "69A33BF7-781D-11E3-8BA0-80D9B09D27A5",
        "69A9D484-781D-11E3-8BA0-80D9B09D27A5"
      ]
    }

An instance is a virtual machine associated with a customer account. Customers with their own API keys may manage their own instances using the API. Changes to customer accounts are automatically reflected in the reseller billing information available in the BetterServers billing area.

Attach an ISO image to an instance
method
PUT
URL
/v1/accounts/{api_id}/instances/{instance_id}/iso
query parameters
(none)
body parameters
  • iso_id: The UUID of the iso to attach
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/iso
    
    {"iso_id":"5DF2A1B4-CF8B-11E1-A175-6E042D956CD8"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID referencing the job responsible for attaching the ISO
examples
  1. {
      "job_id" : "b952b203-1c0f-4ec8-9c13-c0d28387269c"
    }
List all instances associated with this account matching the specified criteria; if no criteria are given, list all instances.
method
GET
URL
/v1/accounts/{api_id}/instances
query parameters
  • (optional)id: UUID of an instance
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of instances in this response
  • instances: a list of instance records
examples
  1. {"count": 2,
     "instances": [{"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Biff 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "b627b88e-9959-4703-b139-7df96e19e069",
                    "instancename": ,
                    "isoid": ,
                    "isoname": ,
                    "memory": 2048,
                    "name": "b627b88e-9959-4703-b139-7df96e19e069",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"id": "76ec30c0-ff69-43d1-9244-3d769cdab075",
                             "isdefault": 1,
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "NEW 10G",
                    "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
                    "templatename": "Ubuntu 12.04 x64"},
                   {"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Joe 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "instancename": ,
                    "isoid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "isoname": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "memory": 2048,
                    "name": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"gateway": "10.49.0.1",
                             "id": "0af3358c-56f5-4de1-9911-33f7999d6702",
                             "ipaddress": "10.49.0.30",
                             "isdefault": 1,
                             "macaddress": "60:78:44:D0:00:f1",
                             "netmask": "255.255.255.0",
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "templateid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "templatename": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso"}]}
Detach an ISO image from an instance
method
DELETE
URL
/v1/accounts/{api_id}/instances/{instance_id}/iso
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/iso
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID referencing the job responsible for detaching the ISO
examples
  1. {
      "job_id" : "b952b203-1c0f-4ec8-9c13-c0d28387269c"
    }
Start a temporary SSH proxy to an instance
method
POST
URL
/v1/accounts/{api_id}/instances/{instance_id}/start-ssh-proxy
query parameters
(none)
body parameters
  • ip: the IP address to allow through
  • cidr: a mask to apply to the IP address; defaults to 32 (e.g., 12.34.56.78/32)
  • timeout: the duration of the proxy in seconds; defaults to 60
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/start-ssh-proxy
    
    {"ip":"12.34.56.78"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • ssh: an object containing "address" and "port" of the SSH proxy
examples
  1. {"ssh" : {"address":"86.75.30.9","port":"13224"}
Change the service offering (CPU and RAM) of an instance or change the display_name (these two options are mutually exclusive). Valid service offerings are available through the serviceofferings resource. See List service offerings.
method
PATCH
URL
/v1/accounts/{api_id}/instances/{instance_id}
query parameters
(none)
body parameters
  • (optional)service_offering_id: The UUID of the new service offering.
  • (optional)display_name: A new display name for this server.
examples
  1. PATCH /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069
    
    {"service_offering_id":"c487c5a7-cecd-1b30-f489-c737a9129ae1"}
HTTP Response
status-code
200
reason-phrase
OK
body
(same as View account instance)
examples
(none)
Retrieve the last known root password for an instance. When an instance is created or its password is reset, the job system retains the result of that action, including the new random password string, for up to 24 hours.

You are highly encouraged to set your own instance root password directly; password changes outside of this API are not stored and are not retrievable via the API.

method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/password
query parameters
  • (optional)job_id: UUID of a specific job_id
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/password
HTTP Response
status-code
200
reason-phrase
OK
body
  • last_known_password: a string containing the last known password for this instance, if any.
examples
  1. {"last_known_password":"aSdf982vVx11"}
Irretrievably destroy an instance.
method
DELETE
URL
/v1/accounts/{api_id}/instances/{instance_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069
HTTP Response
status-code
202
reason-phrase
OK
body
  • job_id: a UUID referencing the job responsible for destroying the instance
examples
  1. {
      "job_id" : "b952b203-1c0f-4ec8-9c13-c0d28387269c"
    }
Stop a VM, change the service offering (CPU and RAM), then start the VM. Valid service offerings are available through the service-offerings resource. See List service offerings.
method
PATCH
URL
/v1/accounts/{api_id}/instances/{instance_id}/service-offering
query parameters
(none)
body parameters
  • service_offering_id: The UUID of the new service offering.
examples
  1. PATCH /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/service-offering
    
    {"service_offering_id":"c487c5a7-cecd-1b30-f489-c737a9129ae1"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • queue_ids: a list of UUIDs referring to the queued jobs handling the update in the order they were queued
examples
(none)
Stop, start, reboot, or reset the password of an instance.
method
POST
URL
/v1/accounts/{api_id}/instances/{instance_id}/runstate
query parameters
(none)
body parameters
  • action: one of start, stop, reboot, or resetpassword
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069/runstate
    
    {"action":"reboot"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID referencing the job responsible for changing the run-state of the instance
examples
  1. {"job_id" : "b952b203-1c0f-4ec8-9c13-c0d28387269c"}
List all instances matching the specified criteria; if no criteria are given, list all instances.
This method is available only to admin accounts.
method
GET
URL
/v1/instances
query parameters
  • (optional)instance_id: UUID of an instance
  • (optional)state: one of stopped, running, starting, stopping, or error
  • (optional)page: for results pagination, the page of results to return
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/instances
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of instances in this response
  • instances: a list of instance records
examples
  1. {"count": 2,
     "instances": [{"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Biff 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "b627b88e-9959-4703-b139-7df96e19e069",
                    "instancename": ,
                    "isoid": ,
                    "isoname": ,
                    "memory": 2048,
                    "name": "b627b88e-9959-4703-b139-7df96e19e069",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"id": "76ec30c0-ff69-43d1-9244-3d769cdab075",
                             "isdefault": 1,
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "NEW 10G",
                    "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
                    "templatename": "Ubuntu 12.04 x64"},
                   {"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Joe 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "instancename": ,
                    "isoid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "isoname": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "memory": 2048,
                    "name": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"gateway": "10.49.0.1",
                             "id": "0af3358c-56f5-4de1-9911-33f7999d6702",
                             "ipaddress": "10.49.0.30",
                             "isdefault": 1,
                             "macaddress": "60:78:44:D0:00:f1",
                             "netmask": "255.255.255.0",
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "templateid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "templatename": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso"}]}
View details of an instance.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/b627b88e-9959-4703-b139-7df96e19e069
HTTP Response
status-code
200
reason-phrase
OK
body
  • cpunumber: number of CPUs
  • cpuspeed: speed of CPUs
  • cpuused: CPU used
  • created: ISO 8601 formatted date
  • displayname: description
  • hostname: hostname
  • hypervisor: hypervisor
  • id: UUID identifying this VM instance
  • instancename: internal name used to identify this instance
  • isoid: UUID of ISO used to create this instance (if applicable)
  • isoname: name of ISO used to create this instance (if applicable)
  • memory: MB of RAM
  • name: name of this instance
  • networkkbsread: network KBs read
  • networkkbswrite: network KBs written
  • nic: information about the NIC on the instance
  • serviceoffering: UUID of the service offering
  • serviceofferingname: name of the service offering
  • state: state of the instance (e.g., stopped)
  • templatedisplaytext: description of the template used to create this instance
  • templateid: UUID of the template used to create this instance
  • templatename: name of the template used to create this instance
examples
  1. {
      "cpunumber" : 2,
      "cpuspeed" : 2200,
      "cpuused" : null,
      "created" : "2012-07-16T17:29:28-0600",
      "displayname" : "HostingCo Biff 55419",
      "hostname" : null,
      "hypervisor" : null,
      "id" : "b627b88e-9959-4703-b139-7df96e19e069",
      "instancename" : null,
      "isoid" : null,
      "isoname" : null,
      "memory" : 2048,
      "name" : "b627b88e-9959-4703-b139-7df96e19e069",
      "networkkbsread" : null,
      "networkkbswrite" : null,
      "nic" : [
        {
          "id" : "76ec30c0-ff69-43d1-9244-3d769cdab075",
          "isdefault" : 1,
          "networkid" : "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
          "traffictype" : "Guest",
          "type" : "Shared"
        }
      ],
      "serviceoffering" : null,
      "serviceofferingname" : "Level1",
      "state" : "Starting",
      "templatedisplaytext" : "NEW 10G",
      "templateid" : "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
      "templatename" : "Ubuntu 12.04 x64"
    }
Create an instance associated with this account.
method
POST
URL
/v1/accounts/{api_id}/instances
query parameters
(none)
body parameters
  • (optional)display_name: display name of the instance
  • (optional)hostname: hostname (sans domain name) of the instance
  • template_id: UUID of the desired template or ISO. If ISO is specified, a disk offering must be provided.
  • hypervisor: desired hypervisor
  • service_offering_id: UUID of the desired service offering
  • network_ids: a list of network UUIDs
  • ip_v4_address: bring up this IPv4 address (must be within the attached VM network)
  • ip_v6_address: bring up this IPv6 address (must be within the attached VM network)
  • (optional)disk_offering_id: UUID of the disk offering. If ISO is specified for template_id, disk offering is required.
  • zone_id: UUID of the desired zone
  • (optional)size: size of the data disk in GB; required if VM has a data disk and disk_offering_id specifies an offering with a custom size
  • (optional)rootsize: size of the root volume in GB; defaults to the template size (virtual) if not specified
  • (optional)start_vm: if false, the VM will not be started after it is provisioned. Defaults to true
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances
    
    {"disk_offering_id":"14229deb-8ee6-4ddd-b0b0-7d1039889c7a",
     "network_ids":"4d5a9aaa-5af7-42d5-af79-d52d33b4165b,5ed51b11-1205-4c0c-873a-216068b37e74",
     "hostname":"joe55419",
     "display_name":"HostingCo Joe 55419"}
    
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID referring to the internal job handling the creation of the instance
  • id: a UUID referring to the new instance
examples
  1. {"job_id":"c73791a7-cedc-4830-b1f9-a2c487c59ea1",
     "id":"a2a9bce3-bb01-4d75-b0c6-e95fc124ce80"}
List all instances associated with this account matching the specified criteria. This resource also accepts the page and range (page, pagesize, begin, end, order_by,desc`) arguments of the list resource
method
GET
URL
/v1/accounts/{api_id}/instances/search
query parameters
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/search?query=cpuspeed%3c%3d2400
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of instances in this response
  • instances: a list of instance records
examples
  1. {"count": 2,
     "instances": [{"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Biff 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "b627b88e-9959-4703-b139-7df96e19e069",
                    "instancename": ,
                    "isoid": ,
                    "isoname": ,
                    "memory": 2048,
                    "name": "b627b88e-9959-4703-b139-7df96e19e069",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"id": "76ec30c0-ff69-43d1-9244-3d769cdab075",
                             "isdefault": 1,
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "NEW 10G",
                    "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
                    "templatename": "Ubuntu 12.04 x64"},
                   {"cpunumber": 2,
                    "cpuspeed": 2200,
                    "cpuused": ,
                    "created": "2012-07-16T17:29:28-0600",
                    "displayname": "HostingCo Joe 55419",
                    "hostname": ,
                    "hypervisor": ,
                    "id": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "instancename": ,
                    "isoid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "isoname": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "memory": 2048,
                    "name": "3ce11220-30dd-4219-accd-12746ef1cbb8",
                    "networkkbsread": ,
                    "networkkbswrite": ,
                    "nic": [{"gateway": "10.49.0.1",
                             "id": "0af3358c-56f5-4de1-9911-33f7999d6702",
                             "ipaddress": "10.49.0.30",
                             "isdefault": 1,
                             "macaddress": "60:78:44:D0:00:f1",
                             "netmask": "255.255.255.0",
                             "networkid": "6e291d4b-d4e7-4a9c-a90b-5c229713cf83",
                             "traffictype": "Guest",
                             "type": "Shared"}],
                    "serviceoffering": ,
                    "serviceofferingname": "Level1",
                    "state": "Starting",
                    "templatedisplaytext": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso",
                    "templateid": "f0388b0c-2f0d-4e2b-8666-a5e001ce171e",
                    "templatename": "FreeBSD-9.0-RELEASE-amd64-bootonly.iso"}]}

You can allocate and free IP blocks, associate/disassociate them with a network, and list IP blocks allocated to your account.

List IP blocks allocated to this account and which have been assigned to a network.
method
GET
URL
/v1/accounts/{api_id}/ip_blocks?status=assigned
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/713393BA-2ACC-11E2-97BB-7F8CE6D04373/ip_blocks?status=assigned
    
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of blocks in this response
  • blocks: a list of blocks from this account which have been assigned
examples
  1. {
      "count": 1,
      "blocks": [
        {
          "api_id": "713393BA-2ACC-11E2-97BB-7F8CE6D04373",
          "assigned": "2012-11-12 10:00:46",
          "ip": "10.128.0.1",
          "cidr": "24",
          "network_uuid": "83d00a2a-13f8-432d-b8ce-d56eee58a28d"
        }
      ]
    }
Take a block of size {cidr} from your allocated block {block} and assign it to a network {network_id}.
method
PUT
URL
/v1/accounts/{api_id}/networks/{network_id}/ip_blocks/{block}/{cidr}
query parameters
(none)
body parameters
  • block: a super block from which to allocate
  • cidr: the size in cidr notation of the block you want to allocate
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/networks/83d00a2a-13f8-432d-b8ce-d56eee58a28d/ip_blocks/10.128.0.0/24
    
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result of the operation
examples
  1. {"message":"Block assigned"}
    
List IP blocks allocated to this account.
method
GET
URL
/v1/accounts/{api_id}/ip_blocks?status=allocated
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/713393BA-2ACC-11E2-97BB-7F8CE6D04373/ip_blocks?status=allocated
    
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of blocks in this response
  • blocks: a list of blocks allocated to this account
examples
  1. {
      "count": 2,
      "blocks": [
        {
          "allocated": "2012-11-12 09:48:05",
          "api_id": "713393BA-2ACC-11E2-97BB-7F8CE6D04373",
          "ip": "10.128.0.0",
          "cidr": "17"
        },
        {
          "allocated": "2012-11-12 09:48:05",
          "api_id": "713393BA-2ACC-11E2-97BB-7F8CE6D04373",
          "ip": "10.128.128.0",
          "cidr": "17"
        }
      ]
    }
Take a block of size {cidr} from superblock {block} and allocate it to your account. This does not associate it with any particular network, but reserves it for later use.
method
POST
URL
/v1/accounts/{api_id}/ip_blocks
query parameters
(none)
body parameters
  • block: a super block from which to allocate
  • cidr: the size in cidr notation of the block you want to allocate
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ip_blocks
    
    {"block":"50.114.0.0","cidr":"24"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result of the operation
  • block: the starting IP of the allocated block
  • cidr: the size in cidr notation of the allocated block
examples
  1. {
      "message": "Block allocated",
      "block": "50.114.129.0",
      "cidr": "24"
    }
Unassign an IP block from network {network_id}. It remains allocated to your account and may be re-assigned to another network.
method
DELETE
URL
/v1/accounts/{api_id}/networks/{network_id}/ip_blocks/{block}/{cidr}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/networks/83d00a2a-13f8-432d-b8ce-d56eee58a28d/ip_blocks/10.128.0.0/24
    
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result of the operation
examples
  1. {"message":"Block unassigned"}
    
List free IP blocks of a given size (in cidr notation). This will tell you which superblocks will fit your cidr.
method
GET
URL
/v1/accounts/{api_id}/ip_blocks?status=free&cidr={cidr}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/713393BA-2ACC-11E2-97BB-7F8CE6D04373/ip_blocks?status=free&cidr=16
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of results
  • blocks: a list of superblocks that will fit the requested cidr
examples
  1. {"count":1,"blocks":["10.128.0.0"]}
    
Free (unallocate) an IP block from your account. Freeing a block implicitly unassigns all sub-blocks from their networks. An unallocated IP block is not guaranteed to be re-allocated.
method
DELETE
URL
/v1/accounts/{api_id}/ip_blocks/{block}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ip_blocks/50.114.129.0
    
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result of the operation
examples
  1. {
      "message": "Block freed"}

You can reserve IP addresses, allocate (reserved) IP addresses, associate (allocated) IP addresses with an instance, free IP addresses from an instance, deallocate them, and list your IP addresses.

Reserves a quantity of IP addresses (between 1 and 15) to your account for a limited time. Reserved addresses may be allocated to your account or allowed to expire. If you make a new reservation request, previously reserved-but-unallocated IP addresses are released and a new set is reserved.
method
POST
URL
/v1/accounts/{api_id}/ips
query parameters
(none)
body parameters
  • quantity: an integer between 1 and 15 inclusive
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ips
    
    {"quantity":"4"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • ips: a list of IP addresses
  • count: how many IP addresses in the list
examples
  1. {
     "count":5,
     "ips":["255.55.1.32","255.55.1.33","255.55.1.34","255.55.1.35","255.55.1.36"]
    }
Assign an IP address to a network.
method
PUT
URL
/v1/accounts/{api_id}/networks/{network_id}/ips
query parameters
(none)
body parameters
  • ip: An IP address allocated to your account.
  • (optional)instance_id: The UUID of the instance to associate the IP with.
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/networks/76294d32-4420-4a06-bcb3-a5fccd9822f4/ips
    
    {"ip":"255.50.12.8"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "IP 2b96feea-8a2f-422e-949b-4a4e62d0a051 assigned"
    }
Unassign an IP address from an instance. This method removes the IP address from the list of IP addresses assigned to the instance, but the IP address is still allocated to your API account. Note that this method does not make any changes to your instance directly. You will still need to remove any network configuration changes you may have made within the instance.
method
DELETE
URL
/v1/accounts/{api_id}/instances/{instance_id}/ips/{ip}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/67924d32-4420-4a06-bcb3-a5fcc9d8f422/ips/255.50.12.8
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "IP unassigned"
    }
List private IP addresses by account.
method
GET
URL
/v1/accounts/{api_id}/private-ips
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/private-ips
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of IPs returned in this response
  • ips: a list of private IP addresses used by servers
examples
  1. {
      "count": 2,
      "ips": [
        {
          "id": "c55322df-ec3a-47bb-82b3-8c9fded7629e",
          "instance_id": "c921f707-5618-4f39-9fad-3df39d24b8b5",
          "ip": "10.99.222.10",
          "netmask": "255.255.255.224",
          "network_id": "be33d651-ad15-4d51-ab89-64a79c494f88",
          "zone_id": "0d81380e-d32f-47c6-9a99-910c44ee6264"
        },
        {
          "id": "427c826e-0587-4c9c-a08f-3af059738d36",
          "instance_id": "a05c55f3-7fae-4048-ad4d-19868efa60e8",
          "ip": "10.99.222.16",
          "netmask": "255.255.255.224",
          "network_id": "be33d651-ad15-4d51-ab89-64a79c494f88",
          "zone_id": "0d81380e-d32f-47c6-9a99-910c44ee6264"
        }
      ]
    }
Allocate a new IP address to your account. This does not associate it with any particular instance, but makes it available to you for later use. You must first reserve an IP address before it may be allocated to your account.
method
PUT
URL
/v1/accounts/{api_id}/ips/{ip}
query parameters
(none)
body parameters
(none)
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ips/255.50.12.8
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result
examples
  1. {"message":"255.55.1.40 allocated"}
Unassign an IP address from a network and instance. This method removes the IP address from the list of IP addresses assigned to the instance, but the IP address is still allocated to your API account. Note that this method does not make any changes to your instance directly. You will still need to remove any network configuration changes you may have made within the instance.
method
DELETE
URL
/v1/accounts/{api_id}/networks/{network_id}/ips/{ip}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/networks/76294d32-4420-4a06-bcb3-a5fcc9df8224/ips/255.50.12.8
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "IP unassigned"
    }
List the IP addresses associated with this instance.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/ips
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/1806a7e4-b729-4caf-a542-60fce7ae16eb/ips
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: the number of IP addresses in this response
  • ips: a list of IP addresses associated with this instance
examples
  1. {
       "count" : 1,
       "ips" : [
          {
             "ptr" : {
                "ttl" : 300,
                "content" : "www8.hosting.com",
                "name" : "58.15.156.180.in-addr.arpa"
             },
             "status" : "assigned",
             "ip" : "180.156.15.58",
             "cidr" : 32,
             "network_uuid" : "2725c9da-0d4e-452b-8f66-97ef3a92fd19",
             "is_source" : true,
             "assigned" : "2014-08-19 11:09:56",
             "zone_id" : "0d81380e-d32f-47c6-9a99-910c44ee6264",
             "instance_uuid" : "c6d8178c-f291-4a0e-8e0f-d495d31bad23"
          }
       ],
       "total" : 1
    }
This method can be used to set or unset the source IP for a virtual machine instance. If a source IP is set, it will be the default outbound (source) IP for all traffic.
method
PATCH
URL
/v1/accounts/{api_id}/instances/{instance_id}/ips/{ip}
query parameters
(none)
body parameters
  • is_source: (boolean) true or false
examples
  1. PATCH /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/67924d32-4420-4a06-bcb3-a5fcc9d8f422/ips/255.50.12.8
    
    {"is_source":true}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "255.50.12.8 successfully updated"
    }
Set an IP addresses reverse DNS entry (in-addr.arpa).
method
PUT
URL
/v1/accounts/{api_id}/rdns/{ip}
query parameters
(none)
body parameters
  • ptr: the content of the PTR record
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/rdns/255.50.12.8
    
    {"ptr":"my.example.com"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result
examples
  1. {"message":"rDNS set"}
View an IP addresses reverse DNS entry (in-addr.arpa) for a given IP address.
method
GET
URL
/v1/accounts/{api_id}/rdns/{ip}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/rdns/255.50.12.8
HTTP Response
status-code
200
reason-phrase
OK
body
  • rdns: an rDNS record for the specified IP
examples
  1. {
      "rdns": {
        "content": "my.example.com",
        "name": "8.12.50.255-in-addr.arpa",
        "ttl": "300",
        "type": "PTR"
      }
    }
List IP addresses by account.
method
GET
URL
/v1/accounts/{api_id}/ips
query parameters
  • (optional)instance_id: UUID of an instance
  • (optional)network_id: UUID of a network
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ips?network_id=CD07CF98-C4D3-11E2-ABC7-C9DDC2706323
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of IPs returned in this response
  • ips: a list of IP addresses allocated to this account
examples
  1. {
      "count": 2,
      "ips": [
          {
             "ptr" : {
                "ttl" : 300,
                "content" : "180-156-15-48.dc-extras.com",
                "name" : "48.15.156.180.in-addr.arpa"
             },
             "ip" : "180.156.15.48",
             "status" : "allocated",
             "cidr" : 32,
             "allocated" : "2014-08-18 15:20:33",
             "is_source" : false,
             "zone_id" : "0d81380e-d32f-47c6-9a99-910c44ee6264"
          },
          {
             "ptr" : {
                "ttl" : 300,
                "name" : "58.15.156.180.in-addr.arpa",
                "content" : "180-156-15-58.dc-extras.com"
             },
             "status" : "assigned",
             "ip" : "180.156.15.58",
             "cidr" : 32,
             "network_uuid" : "2725c9da-0d4e-452b-8f66-97ef3a92fd19",
             "is_source" : true,
             "assigned" : "2014-08-19 11:09:56",
             "zone_id" : "0d81380e-d32f-47c6-9a99-910c44ee6264",
             "instance_uuid" : "c6d8178c-f291-4a0e-8e0f-d495d31bad23"
          }
      ]
    }
Free an IP address that was allocated to your account.
method
DELETE
URL
/v1/accounts/{api_id}/ips/{ip}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/ips/255.50.0.12
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "IP successfully freed"
    }

other responses

status-code reason-phrase description
409 Conflict The IP address is assigned to a VM or is in some other state of conflict and cannot be freed.
Assign an IP address to an instance.
method
PUT
URL
/v1/accounts/{api_id}/instances/{instance_id}/ips
query parameters
(none)
body parameters
  • ip: An IP address allocated to your account.
  • network_id: The UUID of the network to associate the IP with.
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/instances/67924d32-4420-4a06-bcb3-a5fcc9d8f422/ips
    
    {"ip":"255.50.12.8","network_id":"680659FE-B83D-11E2-8C3F-1F383AC9E08F"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the results of the operation
examples
  1. {
      "message": "IP 2b96feea-8a2f-422e-949b-4a4e62d0a051 assigned to instance 67924d32-4420-4a06-bcb3-a5fcc9d8f422"
    }

You can create ISOs from a URL, list isos, etc.

View an ISO's details.
method
GET
URL
/v1/accounts/{api_id}/isos/{iso_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/isos/a04c9d80-4c09-4ec8-9106-35ee4c288c59
HTTP Response
status-code
200
reason-phrase
OK
body
  • bootable: (boolean) true if this ISO is bootable
  • checksum: a checksum for this ISO
  • created: ISO 8601 formatted date when the ISO was created
  • cross_zones: (boolean) true if this ISO is enabled across multiple zones
  • display_text: description of the ISO
  • format: format of the ISO if available
  • hypervisor: hypervisor, if any
  • id: id the ISO
  • is_public: (boolean) true if the ISO is public
  • is_ready: (boolean) true if the ISO is ready to use
  • name: short name of the ISO
  • os_type_id: ID of the OS type
  • os_type_name: OS type of the ISO
  • removed: (boolean) true if this ISO has been removed
  • size: size of the ISO
  • status: current ISO status
  • zone_id: id of the zone this ISO was created in
  • zone_name: name of the zone this ISO was created in
examples
  1. {
      "bootable": true,
      "checksum": "9a190c8b2bd382c2d046dbc855cd2f2b",
      "created": "2014-01-16T11:11:49-0700",
      "cross_zones": false,
      "display_text": "",
      "format": null,
      "hypervisor": null,
      "id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
      "is_public": false,
      "is_ready": true,
      "name": "large iso",
      "os_type_id": "d1e55243-f803-483b-b399-9a976fd28e73",
      "os_type_name": "CentOS 6.0 (64-bit)",
      "removed": null,
      "size": 4603248640,
      "status": "Successfully Installed",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_name": "US-UTAH1-TEST"
    }
Create a new ISO from a URL.
method
POST
URL
/v1/accounts/{api_id}/isos
query parameters
(none)
body parameters
  • display_text: a description of the ISO
  • name: the name of the ISO
  • os_type_id: an ID identifying an OS type (see list OS types)
  • url: the URL of an .iso image
  • zone_id: the UUID of the zone this ISO will be available in
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/isos
    
    {
      "display_text": "69278-test-url-iso",
      "name": "69278-test-url-iso",
      "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
      "url": "http://example.com/d88130962a4c456cbc494333e6539d77.iso",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }
HTTP Response
status-code
201
reason-phrase
Created
body
  • bootable: (boolean)
  • checksum: a checksum for the ISO
  • created: date ISO was created
  • cross_zones: (boolean)
  • display_text: description of ISO
  • auth_type: auth_type of ISO
  • id: UUID of new ISO
  • is_ready: (boolean)
  • name: name of ISO
  • os_type_id: UUID of OS type
  • os_type_name: description of OS type
  • password_enabled: (boolean)
  • size: ISO size
  • source_template_id: UUID of source template
  • ssh_key_enabled: (boolean)
  • status: ISO status
  • tags: tags
  • zone_id: the zone of the ISO
examples
  1. {
      "account": "biff@scott-89434.api-test",
      "account_id": null,
      "auth_type": "ZEBE59WI",
      "bootable": true,
      "checksum": null,
      "created": "2014-01-08T15:30:45-0700",
      "cross_zones": false,
      "display_text": "biff-iso-ZEBE59WI-89434",
      "hostname": null,
      "hypervisor": null,
      "id": "06aae74e-1b2d-4105-85a7-1691a2a0c2f1",
      "is_ready": false,
      "name": "biff-iso-ZEBE59WI-89434",
      "os_type_id": "3d6a8af1-7e41-4c9d-aefc-c0d0550ea2c4",
      "os_type_name": "Other CentOS (64-bit)",
      "password_enabled": null,
      "size": null,
      "source_template_id": null,
      "ssh_key_enabled": null,
      "status": "",
      "tags": [
      ],
      "template_tag": null,
      "template_type": null,
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }
List isos.
method
GET
URL
/v1/accounts/{api_id}/isos
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/isos
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of isos in this response
  • isos: list of isos
examples
  1. {
      "count": 3,
      "isos": [
        {
          "id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
          "name": "CentOS 6.3 x64"
        },
        {
          "id": "26581568-554a-4bb3-a2d0-926f3a301d08",
          "name": "Ubuntu 12.04 LTS x64"
        },
        {
          "id": "ffce0c75-01e5-4b4d-aa98-103971646453",
          "name": "xs-tools.iso"
        }
      ]
    }

A job is an asynchronous API process. API calls that take longer than a few seconds to complete will return an identifier you may use to query the status of the job. These API methods allow you list and query the status of current and recently completed jobs.

List current and recently completed jobs.
method
GET
URL
/v1/accounts/{api_id}/jobs
query parameters
  • (optional)state: only return jobs in the given state (pending, success, error)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/jobs
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of jobs returned in this response
  • jobs: a list of jobs
examples
  1. {
      "count": 2,
      "jobs": [
        {
          "accountid": "2552c838-3ed6-4818-bfa7-2184ce08dc42",
          "cmd": "com.cloud.api.commands.DeployVMCmd",
          "created": "2012-07-17T15:24:32-0600",
          "job_id": "55aeff54-7cfc-4577-8d73-0d2670c9c9b9",
          "jobprocstatus": 0,
          "jobresult": {
            "virtualmachine": {
              "account": "joe@schmoe.org",
              "cpunumber": 2,
              "cpuspeed": 2200,
              "created": "2012-07-17T15:24:32-0600",
              "id": "18354cf6-153b-49f4-b94e-262353a33b13",
              "memory": 2048,
              "name": "18354cf6-153b-49f4-b94e-262353a33b13",
              "password": "Ven7hkvrz",
              "passwordenabled": 1,
              "serviceofferingid": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
              "state": "Running",
              "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
              "zoneid": "be2e2453-fe37-4058-92d7-b5c829ac7967"
            }
          },
          "jobresultcode": 0,
          "jobresulttype": "object",
          "jobstatus": 1,
          "userid": "ebecb044-7a5a-4867-8bb6-4f4986a02b08"
        },
        {
          "accountid": "2552c838-3ed6-4818-bfa7-2184ce08dc42",
          "cmd": "com.cloud.api.commands.ResetVMPasswordCmd",
          "created": "2012-07-17T15:25:59-0600",
          "job_id": "dd9a840c-e265-46c7-ae03-e13d96a36b22",
          "jobprocstatus": 0,
          "jobresult": {
            "virtualmachine": {
              "account": "joe@schmoe.org",
              "cpunumber": 2,
              "cpuspeed": 2200,
              "cpuused": "0.2%",
              "created": "2012-07-17T15:24:32-0600",
              "id": "18354cf6-153b-49f4-b94e-262353a33b13",
              "memory": 2048,
              "name": "18354cf6-153b-49f4-b94e-262353a33b13",
              "password": "Pd7vttcrc",
              "passwordenabled": 1,
              "serviceofferingid": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
              "state": "Running",
              "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
              "zoneid": "be2e2453-fe37-4058-92d7-b5c829ac7967"
            }
          },
          "jobresultcode": 0,
          "jobresulttype": "object",
          "jobstatus": 1,
          "userid": "ebecb044-7a5a-4867-8bb6-4f4986a02b08"
        }
      ]
    }
View a job's details.
method
GET
URL
/v1/accounts/{api_id}/jobs/{job_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/jobs/55aeff54-7cfc-4577-8d73-0d2670c9c9b9
HTTP Response
status-code
200
reason-phrase
OK
body
  • created: ISO 8601 formatted date string when the job was created
  • job_id: UUID identifying the job
  • result: (dependent on the job)
  • jobstatus: 0 = pending, 1 = succeeded, 2 = failed
  • status: text equivalent of jobstatus
examples
  1. {
      "accountid" : "2552c838-3ed6-4818-bfa7-2184ce08dc42",
      "cmd" : "com.cloud.api.commands.DeployVMCmd",
      "created" : "2012-07-17T15:24:32-0600",
      "job_id" : "55aeff54-7cfc-4577-8d73-0d2670c9c9b9",
      "jobprocstatus" : 0,
      "jobresult" : {
        "virtualmachine" : {
          "account" : "joe@schmoe.org",
          "cpunumber" : 2,
          "cpuspeed" : 2200,
          "created" : "2012-07-17T15:24:32-0600",
          "id" : "18354cf6-153b-49f4-b94e-262353a33b13",
          "memory" : 2048,
          "name" : "18354cf6-153b-49f4-b94e-262353a33b13",
          "password" : "Ven7hkvrz",
          "passwordenabled" : 1,
          "serviceofferingid" : "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
          "state" : "Running",
          "templateid" : "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
          "zoneid" : "be2e2453-fe37-4058-92d7-b5c829ac7967"
        }
      },
      "jobresultcode" : 0,
      "jobresulttype" : "object",
      "jobstatus" : 1,
      "userid" : "ebecb044-7a5a-4867-8bb6-4f4986a02b08"
    }
    
List jobs by supplying ids.
method
POST
URL
/v1/accounts/{api_id}/jobs/list
query parameters
(none)
body parameters
  • (optional)ids: an array of job ids
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/jobs/list
    
    {"ids":["55aeff54-7cfc-4577-8d73-0d2670c9c9b9","dd9a840c-e265-46c7-ae03-e13d96a36b22"]}
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of jobs returned in this response
  • jobs: a list of jobs
examples
  1. {
      "count": 2,
      "jobs": [
        {
          "accountid": "2552c838-3ed6-4818-bfa7-2184ce08dc42",
          "cmd": "com.cloud.api.commands.DeployVMCmd",
          "created": "2012-07-17T15:24:32-0600",
          "job_id": "55aeff54-7cfc-4577-8d73-0d2670c9c9b9",
          "jobprocstatus": 0,
          "jobresult": {
            "virtualmachine": {
              "account": "joe@schmoe.org",
              "cpunumber": 2,
              "cpuspeed": 2200,
              "created": "2012-07-17T15:24:32-0600",
              "id": "18354cf6-153b-49f4-b94e-262353a33b13",
              "memory": 2048,
              "name": "18354cf6-153b-49f4-b94e-262353a33b13",
              "password": "Ven7hkvrz",
              "passwordenabled": 1,
              "serviceofferingid": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
              "state": "Running",
              "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
              "zoneid": "be2e2453-fe37-4058-92d7-b5c829ac7967"
            }
          },
          "jobresultcode": 0,
          "jobresulttype": "object",
          "jobstatus": 1,
          "userid": "ebecb044-7a5a-4867-8bb6-4f4986a02b08"
        },
        {
          "accountid": "2552c838-3ed6-4818-bfa7-2184ce08dc42",
          "cmd": "com.cloud.api.commands.ResetVMPasswordCmd",
          "created": "2012-07-17T15:25:59-0600",
          "job_id": "dd9a840c-e265-46c7-ae03-e13d96a36b22",
          "jobprocstatus": 0,
          "jobresult": {
            "virtualmachine": {
              "account": "joe@schmoe.org",
              "cpunumber": 2,
              "cpuspeed": 2200,
              "cpuused": "0.2%",
              "created": "2012-07-17T15:24:32-0600",
              "id": "18354cf6-153b-49f4-b94e-262353a33b13",
              "memory": 2048,
              "name": "18354cf6-153b-49f4-b94e-262353a33b13",
              "password": "Pd7vttcrc",
              "passwordenabled": 1,
              "serviceofferingid": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
              "state": "Running",
              "templateid": "1f40c630-a8ab-49da-bfa4-94bf0229cd73",
              "zoneid": "be2e2453-fe37-4058-92d7-b5c829ac7967"
            }
          },
          "jobresultcode": 0,
          "jobresulttype": "object",
          "jobstatus": 1,
          "userid": "ebecb044-7a5a-4867-8bb6-4f4986a02b08"
        }
      ]
    }

Locks are normally handled automatically by the API and other subsystems, but you may create, delete, view advisory locks on any resources.

View details of a lock.
method
GET
URL
/v1/accounts/{api_id}/locks/{resource_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/locks/b627b88e-9959-4703-b139-7df96e19e069
HTTP Response
status-code
200
reason-phrase
OK
body
  • action: why the lock is in effect
  • api_id: the owner of the resource
  • auth_type: the authorization type of the owner
  • expires: when the lock will expire automatically; normally 0
  • resource_id: id of the locked resource; this is also the lock id
  • location: where the lock was placed from
  • locktime: when the lock was placed
  • resource: the resource type the lock is affecting
examples
  1. {
      "action": "starting server",
      "api_id": "AE2A5E68-8ACD-11E3-A090-84F5B09D27A5",
      "auth_type": "LOVU95YI",
      "expires": "0",
      "resource_id": "58bd2d0f-2f01-4564-a77e-e73bff902fb7",
      "location": "10.52.0.36",
      "locktime": "2014-02-03 11:20:42",
      "resource": "server"
    }
Unlock a resource.
method
DELETE
URL
/v1/accounts/{api_id}/locks/{resource_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/locks/58bd2d0f-2f01-4564-a77e-e73bff902fb7
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result of the action
examples
  1. {"message":"Lock for 58bd2d0f-2f01-4564-a77e-e73bff902fb7 released"}
Create a lock on a resource associated with this account.
method
POST
URL
/v1/accounts/{api_id}/locks
query parameters
(none)
body parameters
  • resource_id: the resource id to lock
  • action: why the lock exists
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/locks
    
    {"resource_id":"58bd2d0f-2f01-4564-a77e-e73bff902fb7","action":"maintenance"}
    
HTTP Response
status-code
201
reason-phrase
Created
body
  • id: UUID of the locked resource
  • message: a brief message indicating the result
examples
  1. {
      "id": "58bd2d0f-2f01-4564-a77e-e73bff902fb7",
      "message": "Lock on 58bd2d0f-2f01-4564-a77e-e73bff902fb7 acquired"
    }
List all locks associated with this account.
method
GET
URL
/v1/accounts/{api_id}/locks
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/locks
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of locks in this response
  • servers: a list of lock records
examples
  1. {
      "count": 1,
      "locks": [
        {
          "action": "stopping server",
          "api_id": "AE2A5E68-8ACD-11E3-A090-84F5B09D27A5",
          "auth_type": "LOVU95YI",
          "expires": "0",
          "resource_id": "58bd2d0f-2f01-4564-a77e-e73bff902fb7",
          "location": "10.52.0.36",
          "locktime": "2014-02-03 11:18:34",
          "resource": "server"
        }
      ]
    }
/v1/locks
List all locks across all accounts.
This method is available only to admin accounts.
method
GET
URL
/v1/locks
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/locks
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of locks in this response
  • servers: a list of locks
examples
  1. {
      "count": 1,
      "locks": [
        {
          "action": "starting server",
          "api_id": "AE2A5E68-8ACD-11E3-A090-84F5B09D27A5",
          "auth_type": "LOVU95YI",
          "expires": "0",
          "resource_id": "58bd2d0f-2f01-4564-a77e-e73bff902fb7",
          "location": "10.52.0.36",
          "locktime": "2014-02-03 11:15:53",
          "resource": "server"
        }
      ]
    }

A network (also known as 'tier' or 'switch') enables you to connect one or more virtual machine instances together. Networks are initially created as private networks, but you may add public IP blocks to your network to make them public also.

List all ACL rules for a given network
method
GET
URL
/v1/accounts/{api_id}/networks/{network_id}/acl-rules
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/98D77724-8C17-88E2-8E7D-58A976C04311/acl-rules
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of network ACL rules in this response
  • network-acl-rules: list of network ACL rules
examples
(none)
List networks across all accounts.
This method is available only to admin accounts.
method
GET
URL
/v1/networks
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/networks
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • networks: list of networks
examples
  1. {
      "count": 1,
      "networks": [
        {
          "account": "joe@schmoe.org",
          "acltype": "Account",
          "assigned_ips": [
            {
              "assigned": "2013-06-16 19:33:53",
              "instance_uuid": "161db57f-51d7-4cfa-b04a-757a9442de7a",
              "ip": "255.55.0.32",
              "network_uuid": "e0a5ba9c-a843-4975-becb-cc0de61da23a",
              "status": "assigned"
            }
          ],
          "assigned_ip_count": 1,
          "broadcastdomaintype": "Vlan",
          "canusefordeploy": true,
          "cidr": "10.128.0.0/24",
          "displaytext": "network of awesomeness",
          "dns1": "8.8.8.8",
          "dns2": "8.8.4.4",
          "domain": "API-Test",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "gateway": "10.128.0.1",
          "id": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "issystem": false,
          "name": "api-test-net-73538",
          "netmask": "255.255.255.0",
          "networkdomain": "US-UTAH1-TEST.cs-zones",
          "networkofferingavailability": "Optional",
          "networkofferingdisplaytext": "customer internal networks",
          "networkofferingid": "817b1cd2-da17-4ab9-9fd0-58df5ec72976",
          "networkofferingname": "VPCPrivateNoLB",
          "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
          "related": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "restartrequired": false,
          "service": [
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedProtocols",
                  "value": "tcp,udp,icmp"
                }
              ],
              "name": "NetworkACL"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedVpnTypes",
                  "value": "pptp,l2tp,ipsec"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "VpnTypes",
                  "value": "s2svpn"
                }
              ],
              "name": "Vpn"
            },
            {
              "name": "UserData"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "RedundantRouter",
                  "value": "false"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedSourceNatTypes",
                  "value": "peraccount"
                }
              ],
              "name": "SourceNat"
            },
            {
              "name": "PortForwarding"
            },
            {
              "name": "Dhcp"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "AllowDnsSuffixModification",
                  "value": "true"
                }
              ],
              "name": "Dns"
            },
            {
              "name": "StaticNat"
            }
          ],
          "specifyipranges": false,
          "state": "Allocated",
          "tags": [
          ],
          "traffictype": "Guest",
          "type": "Isolated",
          "vpcid": "24a919a6-cb42-4473-8780-7edc71eb8aa8",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
Create a network ACL rule.
method
POST
URL
/v1/accounts/{api_id}/network-acl-rules
query parameters
(none)
body parameters
  • network_id: The network UUID
  • protocol: tcp, udp, or icmp
  • (optional)cidr_list: list of network address to allow from/to (e.g., 0.0.0.0/0)
  • (optional)start_port: The start port of the acl
  • (optional)end_port: The end port of the acl
  • (optional)icmp_code: icmpcode
  • (optional)icmp_type: icmptype
  • traffic_type: ingress or egress
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/network_acls
    
    {"network_id":"8844A124-7DD7-7CE2-8E8D-85A9E6D04373", "protocol":"TCP"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID of the new network acl
  • job_id: UUID identifying the job responsible for creating the network acl
examples
(none)
View a network's details
method
GET
URL
/v1/accounts/{api_id}/networks
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/ea3c906b-5364-47c9-a0ad-7778b8e4842c
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • networks: list of networks
examples
  1. {
      "account": "joe@schmoe.org",
      "acltype": "Account",
      "assigned_ip_count": 1,
      "assigned_ips": [
        {
          "assigned": "2013-06-16 19:33:53",
          "instance_uuid": "161db57f-51d7-4cfa-b04a-757a9442de7a",
          "ip": "255.55.0.32",
          "network_uuid": "e0a5ba9c-a843-4975-becb-cc0de61da23a",
          "status": "assigned"
        }
      ],
      "broadcastdomaintype": "Vlan",
      "canusefordeploy": true,
      "cidr": "10.128.0.0/24",
      "displaytext": "network of awesomeness",
      "dns1": "8.8.8.8",
      "dns2": "8.8.4.4",
      "domain": "API-Test",
      "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
      "gateway": "10.128.0.1",
      "id": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
      "issystem": false,
      "name": "api-test-net-73538",
      "netmask": "255.255.255.0",
      "networkdomain": "US-UTAH1-TEST.cs-zones",
      "networkofferingavailability": "Optional",
      "networkofferingdisplaytext": "customer internal networks",
      "networkofferingid": "817b1cd2-da17-4ab9-9fd0-58df5ec72976",
      "networkofferingname": "VPCPrivateNoLB",
      "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
      "related": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
      "restartrequired": false,
      "service": [
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "SupportedProtocols",
              "value": "tcp,udp,icmp"
            }
          ],
          "name": "NetworkACL"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "SupportedVpnTypes",
              "value": "pptp,l2tp,ipsec"
            },
            {
              "canchooseservicecapability": false,
              "name": "VpnTypes",
              "value": "s2svpn"
            }
          ],
          "name": "Vpn"
        },
        {
          "name": "UserData"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "RedundantRouter",
              "value": "false"
            },
            {
              "canchooseservicecapability": false,
              "name": "SupportedSourceNatTypes",
              "value": "peraccount"
            }
          ],
          "name": "SourceNat"
        },
        {
          "name": "PortForwarding"
        },
        {
          "name": "Dhcp"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "AllowDnsSuffixModification",
              "value": "true"
            }
          ],
          "name": "Dns"
        },
        {
          "name": "StaticNat"
        }
      ],
      "specifyipranges": false,
      "state": "Allocated",
      "tags": [
      ],
      "traffictype": "Guest",
      "type": "Isolated",
      "vpcid": "24a919a6-cb42-4473-8780-7edc71eb8aa8",
      "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zonename": "US-UTAH1-TEST"
    }
Destroy a network associated with an account.
method
DELETE
URL
/v1/accounts/{api_id}/networks/{network_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID of the job responsible for destroying the network
examples
  1. {"job_id":"76d8dd98-0636-4254-9c59-786f50eeddb3"}
List network ACL rules by account
method
GET
URL
/v1/accounts/{api_id}/network-acl-rules
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/network-acl-rules
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of network acls in this response
  • network-acl-rules: list of network ACL rules
examples
(none)
Destroy an ACL rule for a given network
method
DELETE
URL
/v1/accounts/{api_id}/networks/{network_id}/acl-rules/{acl_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/7470ac7-08ee-44f7-9fc8-3091152729710/acl-rules/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID of the job responsible for destroying the network ACL rule
examples
  1. {"job_id":"76d8dd98-0636-4254-9c59-786f50eeddb3"}
Create a network.
method
POST
URL
/v1/accounts/{api_id}/networks
query parameters
(none)
body parameters
  • name: name of the network
  • display_text: brief description of the network
  • network_offering_id: UUID of the network offering to derive the network from
  • zone_id: UUID of the zone to create the network in
  • vpc_id: UUID of the VPC this network belongs to
  • gateway: gateway IP address for this network
  • netmask: netmask for this network
  • (optional)network_domain: the domain for this network; only permitted for standalone networks (not part of any virtual data center)
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks
    
    {"name":"Test Network 70828","network_offering_id":"817b1cd2-da17-4ab9-9fd0-58df5ec72976","zone_id":"63d968ee-34ec-4bd6-9ba1-a8ad9769b415","gateway":"10.128.0.1","net mask":"255.255.255.0","vpc_id":"24a919a6-cb42-4473-8780-7edc71eb8aa8","display_text":"network of awesomeness"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • id: UUID of the new network
  • job_id: UUID identifying the job responsible for creating the network
examples
  1. {
      "account": "joe@schmoe.org",
      "acltype": "Account",
      "broadcastdomaintype": "Vlan",
      "canusefordeploy": true,
      "cidr": "10.128.0.0/24",
      "displaytext": "network of awesomeness",
      "dns1": "8.8.8.8",
      "dns2": "8.8.4.4",
      "domain": "API-Test",
      "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
      "gateway": "10.128.0.1",
      "id": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
      "issystem": false,
      "name": "api-test-net-73538",
      "netmask": "255.255.255.0",
      "networkdomain": "US-UTAH1-TEST.cs-zones",
      "networkofferingavailability": "Optional",
      "networkofferingdisplaytext": "customer internal networks",
      "networkofferingid": "817b1cd2-da17-4ab9-9fd0-58df5ec72976",
      "networkofferingname": "VPCPrivateNoLB",
      "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
      "related": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
      "restartrequired": false,
      "service": [
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "SupportedProtocols",
              "value": "tcp,udp,icmp"
            }
          ],
          "name": "NetworkACL"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "SupportedVpnTypes",
              "value": "pptp,l2tp,ipsec"
            },
            {
              "canchooseservicecapability": false,
              "name": "VpnTypes",
              "value": "s2svpn"
            }
          ],
          "name": "Vpn"
        },
        {
          "name": "UserData"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "RedundantRouter",
              "value": "false"
            },
            {
              "canchooseservicecapability": false,
              "name": "SupportedSourceNatTypes",
              "value": "peraccount"
            }
          ],
          "name": "SourceNat"
        },
        {
          "name": "PortForwarding"
        },
        {
          "name": "Dhcp"
        },
        {
          "capability": [
            {
              "canchooseservicecapability": false,
              "name": "AllowDnsSuffixModification",
              "value": "true"
            }
          ],
          "name": "Dns"
        },
        {
          "name": "StaticNat"
        }
      ],
      "specifyipranges": false,
      "state": "Allocated",
      "tags": [
      ],
      "traffictype": "Guest",
      "type": "Isolated",
      "vpcid": "24a919a6-cb42-4473-8780-7edc71eb8aa8",
      "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zonename": "US-UTAH1-TEST"
    }

other responses

status-code reason-phrase description
503 Service Unavailable The router of the VPC has not been created yet or is still starting.
Update a network.
method
PATCH
URL
/v1/accounts/{api_id}/networks/{network_id}
query parameters
(none)
body parameters
  • name: name of the network
  • display_text: brief description of the network
examples
  1. PATCH /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/1862f53f-91a0-449c-894e-4089266980c2
    
    {"name":"Newer Network 70828","display_text":"network of bits"}
HTTP Response
status-code
202
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for updating the network
examples
  1. {"job_id":"76d8dd98-0636-4254-9c59-786f50eeddb3"}
List networks by account.
method
GET
URL
/v1/accounts/{api_id}/networks
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • networks: list of networks
examples
  1. {
      "count": 1,
      "networks": [
        {
          "account": "joe@schmoe.org",
          "acltype": "Account",
          "assigned_ips": [
            {
              "assigned": "2013-06-16 19:33:53",
              "instance_uuid": "161db57f-51d7-4cfa-b04a-757a9442de7a",
              "ip": "255.55.0.32",
              "network_uuid": "e0a5ba9c-a843-4975-becb-cc0de61da23a",
              "status": "assigned"
            }
          ],
          "assigned_ip_count": 1,
          "broadcastdomaintype": "Vlan",
          "canusefordeploy": true,
          "cidr": "10.128.0.0/24",
          "displaytext": "network of awesomeness",
          "dns1": "8.8.8.8",
          "dns2": "8.8.4.4",
          "domain": "API-Test",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "gateway": "10.128.0.1",
          "id": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "issystem": false,
          "name": "api-test-net-73538",
          "netmask": "255.255.255.0",
          "networkdomain": "US-UTAH1-TEST.cs-zones",
          "networkofferingavailability": "Optional",
          "networkofferingdisplaytext": "customer internal networks",
          "networkofferingid": "817b1cd2-da17-4ab9-9fd0-58df5ec72976",
          "networkofferingname": "VPCPrivateNoLB",
          "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
          "related": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "restartrequired": false,
          "service": [
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedProtocols",
                  "value": "tcp,udp,icmp"
                }
              ],
              "name": "NetworkACL"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedVpnTypes",
                  "value": "pptp,l2tp,ipsec"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "VpnTypes",
                  "value": "s2svpn"
                }
              ],
              "name": "Vpn"
            },
            {
              "name": "UserData"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "RedundantRouter",
                  "value": "false"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedSourceNatTypes",
                  "value": "peraccount"
                }
              ],
              "name": "SourceNat"
            },
            {
              "name": "PortForwarding"
            },
            {
              "name": "Dhcp"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "AllowDnsSuffixModification",
                  "value": "true"
                }
              ],
              "name": "Dns"
            },
            {
              "name": "StaticNat"
            }
          ],
          "specifyipranges": false,
          "state": "Allocated",
          "tags": [
          ],
          "traffictype": "Guest",
          "type": "Isolated",
          "vpcid": "24a919a6-cb42-4473-8780-7edc71eb8aa8",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
List networks associated with this account matching the specified criteria. This resource also accepts the page and range (page, pagesize, begin, end, order_by,desc`) arguments of the list resource
method
GET
URL
/v1/accounts/{api_id}/networks/search
query parameters
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/networks/search?query=displaytext%3dnetwork%20of%20awesomeness
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • networks: list of networks
examples
  1. {
      "count": 3,
      "networks": [
        {
          "account": "joe@schmoe.org",
          "acltype": "Account",
          "broadcastdomaintype": "Vlan",
          "canusefordeploy": true,
          "cidr": "10.128.0.0/24",
          "displaytext": "network of awesomeness",
          "dns1": "8.8.8.8",
          "dns2": "8.8.4.4",
          "domain": "API-Test",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "gateway": "10.128.0.1",
          "id": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "issystem": false,
          "name": "api-test-net-73538",
          "netmask": "255.255.255.0",
          "networkdomain": "US-UTAH1-TEST.cs-zones",
          "networkofferingavailability": "Optional",
          "networkofferingdisplaytext": "customer internal networks",
          "networkofferingid": "817b1cd2-da17-4ab9-9fd0-58df5ec72976",
          "networkofferingname": "VPCPrivateNoLB",
          "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
          "related": "ea3c906b-5364-47c9-a0ad-7778b8e4842c",
          "restartrequired": false,
          "service": [
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedProtocols",
                  "value": "tcp,udp,icmp"
                }
              ],
              "name": "NetworkACL"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedVpnTypes",
                  "value": "pptp,l2tp,ipsec"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "VpnTypes",
                  "value": "s2svpn"
                }
              ],
              "name": "Vpn"
            },
            {
              "name": "UserData"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "RedundantRouter",
                  "value": "false"
                },
                {
                  "canchooseservicecapability": false,
                  "name": "SupportedSourceNatTypes",
                  "value": "peraccount"
                }
              ],
              "name": "SourceNat"
            },
            {
              "name": "PortForwarding"
            },
            {
              "name": "Dhcp"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "AllowDnsSuffixModification",
                  "value": "true"
                }
              ],
              "name": "Dns"
            },
            {
              "name": "StaticNat"
            }
          ],
          "specifyipranges": false,
          "state": "Allocated",
          "tags": [
          ],
          "traffictype": "Guest",
          "type": "Isolated",
          "vpcid": "24a919a6-cb42-4473-8780-7edc71eb8aa8",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        },
        {
          "acltype": "Domain",
          "broadcastdomaintype": "Vlan",
          "broadcasturi": "vlan://462",
          "canusefordeploy": true,
          "cidr": "69.27.171.64/26",
          "displaytext": "shared network for public access",
          "dns1": "8.8.8.8",
          "dns2": "8.8.4.4",
          "domain": "ROOT",
          "domainid": "623620f9-be23-4f68-9e84-406e85bd7cca",
          "gateway": "69.27.171.65",
          "id": "4d5a9aaa-5af7-42d5-af79-d52d33b4165b",
          "issystem": false,
          "name": "PublicNetwork0",
          "netmask": "255.255.255.192",
          "networkdomain": "US-UTAH1-TEST.cs-zones",
          "networkofferingavailability": "Optional",
          "networkofferingdisplaytext": "for guest direct-connect networks",
          "networkofferingid": "8788a2f8-d7bd-41df-89aa-5767127e34d1",
          "networkofferingname": "PublicSharedNetworks",
          "physicalnetworkid": "fc3bd9c0-f3dd-4121-9914-041e2a52379c",
          "related": "4d5a9aaa-5af7-42d5-af79-d52d33b4165b",
          "restartrequired": false,
          "service": [
            {
              "name": "UserData"
            },
            {
              "name": "Dhcp"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "AllowDnsSuffixModification",
                  "value": "true"
                }
              ],
              "name": "Dns"
            }
          ],
          "specifyipranges": true,
          "state": "Setup",
          "subdomainaccess": true,
          "tags": [
          ],
          "traffictype": "Guest",
          "type": "Shared",
          "vlan": "462",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        },
        {
          "acltype": "Domain",
          "broadcastdomaintype": "Vlan",
          "broadcasturi": "vlan://400",
          "canusefordeploy": true,
          "cidr": "172.20.0.0/20",
          "displaytext": "shared network for private access",
          "dns1": "8.8.8.8",
          "dns2": "8.8.4.4",
          "domain": "ROOT",
          "domainid": "623620f9-be23-4f68-9e84-406e85bd7cca",
          "gateway": "172.20.0.1",
          "id": "5ed51b11-1205-4c0c-873a-216068b37e74",
          "issystem": false,
          "name": "PrivateNetwork0",
          "netmask": "255.255.240.0",
          "networkdomain": "US-UTAH1-TEST.cs-zones",
          "networkofferingavailability": "Optional",
          "networkofferingdisplaytext": "internal vm-to-vm",
          "networkofferingid": "0cd78627-d19c-43f3-a9c1-388d8c53c4af",
          "networkofferingname": "PrivateSharedNetworks",
          "physicalnetworkid": "144be069-1bed-4521-93f1-e26bf0e1dd0f",
          "related": "5ed51b11-1205-4c0c-873a-216068b37e74",
          "restartrequired": false,
          "service": [
            {
              "name": "UserData"
            },
            {
              "name": "Dhcp"
            },
            {
              "capability": [
                {
                  "canchooseservicecapability": false,
                  "name": "AllowDnsSuffixModification",
                  "value": "true"
                }
              ],
              "name": "Dns"
            }
          ],
          "specifyipranges": true,
          "state": "Setup",
          "subdomainaccess": true,
          "tags": [
          ],
          "traffictype": "Guest",
          "type": "Shared",
          "vlan": "400",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
Destroy a network acl rule associated with an account.
method
DELETE
URL
/v1/accounts/{api_id}/network-acl-rules/{rule_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/network-acl-rules/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID of the job responsible for destroying the network acl rule
examples
  1. {"job_id":"76d8dd98-0636-4254-9c59-786f50eeddb3"}
Create an ACL rule for a given network.
method
POST
URL
/v1/accounts/{api_id}/networks/{network_id}/acl-rules
query parameters
(none)
body parameters
  • protocol: tcp, udp, icmp, or all
  • (optional)cidr_list: list of network address to allow from/to (e.g., 0.0.0.0/0)
  • (optional)start_port: The start port of the acl
  • (optional)end_port: The end port of the acl
  • (optional)icmp_code: icmpcode
  • (optional)icmp_type: icmptype
  • traffic_type: ingress or egress
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/network_acls
    
    {"protocol":"TCP"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID of the new network acl
  • job_id: UUID identifying the job responsible for creating the network acl
examples
(none)

A NIC is a network interface for a virtual machine instance. Instances may have more than one NIC; one (and only one) NIC must be designated as the default NIC. You may not remove the default NIC, but you may change which NIC is the default.

View a NIC on an instance.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/nics/{nic_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/59D1AA0A-CE27-11E2-B861-7D86C2706323/instances/6e4f4923-d99f-4418-9f44-a230fd716808/nics/d4339851-aa94-4452-9917-72fc1d330763
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of nics in this response
  • total: total number of nics on this instance
  • nics: list of nics
examples
  1. {
      "gateway": "10.99.222.1",
      "id": "50be8346-e201-4af3-9eb7-f7e4545a2509",
      "ip_address": "10.99.222.2",
      "is_default": true,
      "mac_address": "02:00:52:04:00:01",
      "netmask": "255.255.255.224",
      "network_id": "53177210-098f-4bc3-b1a6-ef73a70fb93a",
      "network_name": "scott-32593.api-test-network-1/27",
      "type": "Isolated"
    }
List NICs on an instance.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/nics
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/59D1AA0A-CE27-11E2-B861-7D86C2706323/instances/6e4f4923-d99f-4418-9f44-a230fd716808/nics
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of nics in this response
  • total: total number of nics on this instance
  • nics: list of nics
examples
  1. {
      "count": 2,
      "nics": [
        {
          "gateway": "10.99.222.1",
          "id": "50be8346-e201-4af3-9eb7-f7e4545a2509",
          "ip_address": "10.99.222.2",
          "is_default": true,
          "mac_address": "02:00:52:04:00:01",
          "netmask": "255.255.255.224",
          "network_id": "53177210-098f-4bc3-b1a6-ef73a70fb93a",
          "network_name": "scott-32593.api-test-network-1/27",
          "type": "Isolated"
        },
        {
          "gateway": "10.99.222.33",
          "id": "709c836c-e9f5-44c9-ac3c-455526419818",
          "ip_address": "10.99.222.46",
          "is_default": false,
          "mac_address": "02:00:4d:41:00:04",
          "netmask": "255.255.255.224",
          "network_id": "af4ce2ad-3d91-4175-91b1-9286162eff08",
          "network_name": "scott-32593.api-test-network-32/27",
          "type": "Isolated"
        }
      ],
      "total": 2
    }
Update a NIC on an instance.
method
PATCH
URL
/v1/accounts/{api_id}/instances/{instance_id}/nics/{nic_id}
query parameters
(none)
body parameters
  • default: a true (boolean) value to make this NIC the default
examples
  1. PATCH /v1/accounts/59D1AA0A-CE27-11E2-B861-7D86C2706323/instances/6e4f4923-d99f-4418-9f44-a230fd716808/nics/709c836c-e9f5-44c9-ac3c-455526419818
    
    {"default":true}
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: the job id responsible for updating the NIC
examples
  1. {"job_id":"327f9267-e29e-4885-b39a-d398061087cc"}
Create a new NIC on an instance.
method
POST
URL
/v1/accounts/{api_id}/instances/{instance_id}/nics
query parameters
(none)
body parameters
  • network_id: the network id to attach this NIC to
examples
  1. POST /v1/accounts/59D1AA0A-CE27-11E2-B861-7D86C2706323/instances/6e4f4923-d99f-4418-9f44-a230fd716808/nics/709c836c-e9f5-44c9-ac3c-455526419818
    
    {"network_id":"F8BD2CAE-CE2A-11E2-BE90-8086C2706323"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: the job id responsible for updating the NIC
examples
  1. {"job_id":"327f9267-e29e-4885-b39a-d398061087cc"}
Remove a NIC from an instance.
method
DELETE
URL
/v1/accounts/{api_id}/instances/{instance_id}/nics/{nic_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/59D1AA0A-CE27-11E2-B861-7D86C2706323/instances/6e4f4923-d99f-4418-9f44-a230fd716808/nics/709c836c-e9f5-44c9-ac3c-455526419818
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: the job id responsible for removing the NIC
examples
  1. {"job_id":"327f9267-e29e-4885-b39a-d398061087cc"}

Messages sent to you from the system will be stored here, you can acknowledge these messages and delete them

Mark a notification as deleted so it longer shows up as read or unread
method
DELETE
URL
/v1/accounts/{api_id}/notifications/{notification_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/notifications/91234ABD-1251-1239-AB92C18521412
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: Informational message telling you the result of your request
examples
  1. {
     	"message" : "Notification deleted"
    }
Update the status of a notification to read
method
POST
URL
/v1/accounts/{api_id}/notifications/{notification_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/notifications/91234ABD-1251-1239-AB92C18521412
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: Informational message telling you the result of your request
examples
  1. {
     	"message" : "Notification marked as read"
    }
List all notifications for your api_id
method
GET
URL
/v1/accounts/{api_id}/notifications/:state
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/notifications/read
  2. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/notifications/unread
  3. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/notifications/all
HTTP Response
status-code
200
reason-phrase
OK
body
  • api_id: The api_id the message was addressed to if it was
  • auth_type: The auth_type the message was addressed to if it was
  • origin: The sender of this message
  • subject: The subject of this message
  • message: The contents of the message
examples
  1. {
     	"api_id" : "e988752b-aebf-11e2-8150-9cd9fc753a98", "auth_type" : "ABCDEF", "origin" : "admin", "subject" : "Hello", "message" : "Your systems are running great!" 
    }

A plan is a pre-defined set of resources you or your customers can use for creating new instances.

List all plans available to an account.
method
GET
URL
/v1/accounts/{api_id}/plans
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/26135998-1CA2-11E2-8C60-5CA9E6D04373/plans
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of plans returned in this response
  • plans: list of plans
examples
  1. {
      "count": 2,
      "plans": [
        {
          "auth_type": "HostingCo",
          "disk_offering_id": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
          "hypervisor": "KVM",
          "name": "Plan A",
          "plan_id": "26F622DC-1CA2-11E2-8C60-5CA9E6D04373",
          "service_offering_id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
          "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
        },
        {
          "auth_type": "HostingCo",
          "disk_offering_id": "",
          "hypervisor": "KVM",
          "name": "Plan Sparse",
          "plan_id": "26FEE462-1CA2-11E2-8C60-5CA9E6D04373",
          "service_offering_id": "",
          "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
        }
      ]
    }
/v1/plans
List all plans.
This method is available only to admin accounts.
method
GET
URL
/v1/plans
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/plans
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of plans returned in this response
  • plans: list of plans
examples
  1. {
      "count": 2,
      "plans": [
        {
          "auth_type": "HostingCo",
          "disk_offering_id": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
          "hypervisor": "KVM",
          "name": "Plan A",
          "plan_id": "26F622DC-1CA2-11E2-8C60-5CA9E6D04373",
          "service_offering_id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
          "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
        },
        {
          "auth_type": "HostingCo",
          "disk_offering_id": "",
          "hypervisor": "KVM",
          "name": "Plan Sparse",
          "plan_id": "26FEE462-1CA2-11E2-8C60-5CA9E6D04373",
          "service_offering_id": "",
          "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
        }
      ]
    }
/v1/plans
Create a new plan.
This method is available only to admin accounts.
method
POST
URL
/v1/plans
query parameters
(none)
body parameters
  • name: the name of the plan
  • disk_offering_id: UUID of the disk offering
  • hypervisor: hypervisor
  • service_offering_id: UUID of the service offering
  • template_id: UUID of the template
  • zone_id: UUID of the zone
examples
  1. POST /v1/plans
    
    {
      "name": "Plan A",
      "disk_offering_id": "14229deb-8ee6-4ddd-b0b0-7d1039889c7a",
      "hypervisor": "KVM",
      "service_offering_id": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
      "template_id": "87db0e18-ff23-43a2-916d-66601bfb5fb0",
      "zone_id": "be2e2453-fe37-4058-92d7-b5c829ac7967"
    }
HTTP Response
status-code
200
reason-phrase
OK
body
  • plan_id: a UUID identifying this new plan
  • name: the name of the plan
  • disk_offering_id: UUID identifying the disk offering
  • hypervisor: the hypervisor
  • service_offering_id: UUID identifying the service offering
  • template_id: UUID identifying the template
  • zone_id: UUID identifying the zone
examples
  1. {
      "plan_id": "061BE452-D0FD-11E1-8A34-5E6C1D9586CD",
      "name": "Plan A",
      "disk_offering_id": "14229deb-8ee6-4ddd-b0b0-7d1039889c7a",
      "hypervisor": "KVM",
      "service_offering_id": "2c330408-2f99-4d22-8b1d-b109ea39a7fd",
      "template_id": "268dff28-7854-4643-a81f-670757d50b5a",
      "zone_id": "be2e2453-fe37-4058-92d7-b5c829ac7967"
    }
Delete a plan.
This method is available only to admin accounts.
method
DELETE
URL
/v1/plans/{plan_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/plans/26F622DC-1CA2-11E2-8C60-5CA9E6D04373
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message describing the results of the operation
examples
  1. {"message":"Plan 26F622DC-1CA2-11E2-8C60-5CA9E6D04373 deleted"}
View a plan available to an account.
method
GET
URL
/v1/accounts/{api_id}/plans/{plan_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/26135998-1CA2-11E2-8C60-5CA9E6D04373/plans/26F622DC-1CA2-11E2-8C60-5CA9E6D04373
HTTP Response
status-code
200
reason-phrase
OK
body
  • auth_type: authorization type
  • disk_offering_id: UUID of the disk offering
  • hypervisor: hypervisor
  • name: name of the plan
  • plan_id: UUID of the plan
  • service_offering_id: UUID of the service offering
  • template_id: UUID of the template
  • zone_id: UUID of the zone
examples
  1. {
      "auth_type": "HostingCo",
      "disk_offering_id": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
      "hypervisor": "KVM",
      "name": "Plan A",
      "plan_id": "26F622DC-1CA2-11E2-8C60-5CA9E6D04373",
      "service_offering_id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
      "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }
Update a plan.
This method is available only to admin accounts.
method
PATCH
URL
/v1/plans/{plan_id}
query parameters
(none)
body parameters
  • disk_offering_id: UUID of the disk offering
  • hypervisor: hypervisor
  • name: the name of the plan
  • service_offering_id: UUID of the service offering
  • template_id: UUID of the template
  • zone_id: UUID of the zone
examples
  1. PATCH /v1/plans/26F622DC-1CA2-11E2-8C60-5CA9E6D04373
    
    {"name":"Plan B","template_id":"42F350DE-1D3F-11E2-92B0-5CA9E6D04373"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message describing the effect of the method.
examples
  1. {
      "message": "Plan 26F622DC-1CA2-11E2-8C60-5CA9E6D04373 updated"
    }
View a plan's details.
This method is available only to admin accounts.
method
GET
URL
/v1/plans/{plan_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/plans/26F622DC-1CA2-11E2-8C60-5CA9E6D04373
HTTP Response
status-code
200
reason-phrase
OK
body
  • auth_type: authorization type
  • disk_offering_id: UUID of the disk offering
  • hypervisor: hypervisor
  • name: name of the plan
  • plan_id: UUID of the plan
  • service_offering_id: UUID of the service offering
  • template_id: UUID of the template
  • zone_id: UUID of the zone
examples
  1. {
      "auth_type": "HostingCo",
      "disk_offering_id": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
      "hypervisor": "KVM",
      "name": "Plan A",
      "plan_id": "26F622DC-1CA2-11E2-8C60-5CA9E6D04373",
      "service_offering_id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
      "template_id": "a04c9d80-4c09-4ec8-9106-35ee4c288c59",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }

These resources are the building blocks of your VM instances, networks, and accounts.

List hypervisors.
method
GET
URL
/v1/accounts/{api_id}/hypervisors
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/hypervisors
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of hypervisors in this response
  • hypervisors: list of hypervisors
examples
  1. {
      "count": 5,
      "hypervisors": [
        {
          "name": "KVM"
        },
        {
          "name": "XenServer"
        },
        {
          "name": "VMware"
        },
        {
          "name": "BareMetal"
        },
        {
          "name": "Ovm"
        }
      ]
    }
List network offerings.
method
GET
URL
/v1/accounts/{api_id}/networkofferings
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/networkofferings
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of network offerings in this response
  • networkofferings: list of network offerings
examples
  1. {
      "count": 2,
      "networkofferings": [
        {
          "availability": "Optional",
          "conservemode": false,
          "displaytext": "for guest direct-connect networks",
          "forvpc": false,
          "guestiptype": "Shared",
          "id": "8788a2f8-d7bd-41df-89aa-5767127e34d1",
          "isdefault": false,
          "name": "PublicSharedNetworks",
          "networkrate": 2000,
          "service": [
            {
              "name": "Dns",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            },
            {
              "name": "Dhcp",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            },
            {
              "name": "UserData",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            }
          ],
          "serviceofferingid": "eed57f22-0be8-4670-b6a6-29dc5754c2bd",
          "specifyipranges": true,
          "specifyvlan": true,
          "state": "Enabled",
          "traffictype": "Guest"
        },
        {
          "availability": "Optional",
          "conservemode": true,
          "displaytext": "internal vm-to-vm",
          "forvpc": false,
          "guestiptype": "Shared",
          "id": "0cd78627-d19c-43f3-a9c1-388d8c53c4af",
          "isdefault": false,
          "name": "PrivateSharedNetworks",
          "networkrate": 1000,
          "service": [
            {
              "name": "Dns",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            },
            {
              "name": "Dhcp",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            },
            {
              "name": "UserData",
              "provider": [
                {
                  "name": "VirtualRouter"
                }
              ]
            }
          ],
          "serviceofferingid": "eed57f22-0be8-4670-b6a6-29dc5754c2bd",
          "specifyipranges": true,
          "specifyvlan": true,
          "state": "Enabled",
          "tags": "sharedpriv",
          "traffictype": "Guest"
        }
      ]
    }
List os_types.
method
GET
URL
/v1/accounts/{api_id}/os_types
query parameters
  • (optional)list: restrict types to a particular list; accepted values is basic
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/os_types?list=basic
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of os_types in this response
  • os_types: list of os_types
examples
  1. {
      "count": 6,
      "os_types": [
        {
          "description": "CentOS 6.0 (64-bit)",
          "id": "d1e55243-f803-483b-b399-9a976fd28e73",
          "os_category_id": "8dd1d322-6583-4c84-b7ea-96bad7d6c0d7"
        },
        {
          "description": "Debian GNU/Linux 6(64-bit)",
          "id": "f8d493ec-cbc2-4c8e-afcd-7d9ff0bf73e6",
          "os_category_id": "9e1d8622-41aa-4fd5-940f-d0e11cd17e9f"
        },
        {
          "description": "FreeBSD (64-bit)",
          "id": "c9c99ab1-b691-4d30-a782-080f11e26b80",
          "os_category_id": "da3439e9-dafd-4cc7-8062-7236efa9d436"
        },
        {
          "description": "SUSE Linux Enterprise Server 11 SP1 (64-bit)",
          "id": "2cb896dc-09a3-43c1-8c69-fed8041faf6c",
          "os_category_id": "f9f9b869-6bbc-4ea1-919a-f219536ca249"
        },
        {
          "description": "Ubuntu 10.10 (64-bit)",
          "id": "422c7b56-87e9-4061-873b-35441373ba70",
          "os_category_id": "b4edffae-9a57-4e4d-a858-baec97c3978f"
        },
        {
          "description": "Windows XP SP3 (32-bit)",
          "id": "fb5709f3-343c-47db-970f-ec4f78206ee7",
          "os_category_id": "1e393b8b-8622-4e69-8512-2477a87427d6"
        }
      ]
    }
List VPC offerings.
method
GET
URL
/v1/accounts/{api_id}/vpcofferings
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/vpcofferings
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of disk offerings in this response
  • vpcofferings: list of VPC offerings
examples
  1. {
      "count":2,
      "vpcofferings": [
        {
          "is_default":true,
          "name":"Default VPC offering",
          "display_text":"Default VPC offering",
          "id":"5112d100-692b-41f9-95a8-9bd13cafc4cc",
          "service": [
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"PortForwarding"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Dns"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Vpn"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"UserData"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"NetworkACL"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"StaticNat"
            },
            {
              "provider": [
               {
                  "name":"VpcVirtualRouter"
                 }
              ],
              "name":"SourceNat"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Dhcp"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Lb"
            }
          ],
          "state":"Enabled"
        },
        {
          "is_default":false,
          "name":"Default VPC  offering with Netscaler",
          "display_text":"Default VPC  offering with Netscaler",
          "id":"1f4a711d-5a35-45f5-9c9f-8cd707972841",
          "service": [
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"PortForwarding"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Dns"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Vpn"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"UserData"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"NetworkACL"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"StaticNat"
            },
            {
              "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"SourceNat"
            },{
            "provider": [
                {
                  "name":"VpcVirtualRouter"
                }
              ],
              "name":"Dhcp"
            },
            {
               "provider": [
                {
                  "name":"Netscaler"
                }
              ],
              "name":"Lb"
            }
          ],
          "state":"Enabled"
        }
      ]
    }
List disk offerings.
method
GET
URL
/v1/accounts/{api_id}/diskofferings
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/diskofferings
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of disk offerings in this response
  • diskofferings: list of disk offerings
examples
  1. {
      "count": 4,
      "diskofferings": [
        {
          "created": "2012-09-19T13:30:04-0600",
          "disksize": 5,
          "displaytext": "Small Disk, 5 GB",
          "id": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
          "iscustomized": false,
          "name": "Small",
          "storagetype": "shared"
        },
        {
          "created": "2012-09-19T13:30:04-0600",
          "disksize": 20,
          "displaytext": "Medium Disk, 20 GB",
          "id": "7c68f7cb-e377-45a7-8ab1-7215e865f2d0",
          "iscustomized": false,
          "name": "Medium",
          "storagetype": "shared"
        },
        {
          "created": "2012-09-19T13:30:04-0600",
          "disksize": 100,
          "displaytext": "Large Disk, 100 GB",
          "id": "dab60ed7-793e-4f11-bb32-9cf21e6c1798",
          "iscustomized": false,
          "name": "Large",
          "storagetype": "shared"
        },
        {
          "created": "2012-09-19T13:30:04-0600",
          "disksize": 0,
          "displaytext": "Custom Disk",
          "id": "5999bdff-3c67-4427-874d-dcd0f5300cbe",
          "iscustomized": true,
          "name": "Custom",
          "storagetype": "shared"
        }
      ]
    }
List zones.
method
GET
URL
/v1/accounts/{api_id}/zones
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/zones
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of zones in this response
  • zones: list of zones
examples
  1. {
      "count": 1,
      "zones": [
        {
          "id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "name": "US-UTAH1-TEST",
          "default_storage_location_id": "53be94ab-2838-4530-80f2-e0e84a8a33f3"
        }
      ]
    }

Set up recurring times when backups will be executed

For an account, list all backups for scheduled for all volumes
method
GET
URL
/v1/accounts/{api_id}/backup_schedule
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/backup_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "full", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, delete a schedule of when to run incremental backups
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/incremental_backup_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/incremental_backup_schedule/14F6E0B4-CF8B-11E1-A175-422A1D9586C3
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: A confirmation of the schedule to be deleted
examples
  1. {
     "message" : "Schedule 93BEE70C-BCF6-11E2-A506-806642F52D07 deleted" 
    }
For a volume, list all scheduled full backups
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/full_backup_schedule
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/full_backup_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "full", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, create a schedule of when to run full backups
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/full_backup_schedule
query parameters
(none)
body parameters
  • schedule: An iCal data element describing the schedule of when to run the backup example: FREQ=DAILY;INTERVAL=2;COUNT=6
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/full_backup_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • schedule_id: The UUID of the schedule created
examples
  1. {
     "schedule_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07" 
    }
Get details of a specific schedule for a snapshot for a specific volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshot_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/snapshot_schedule/1234578ABC-12312512-ABC121298712123
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "snapshot", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, list all scheduled incremental backups
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/incremental_backup_schedule
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/incremental_backup_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "incremental", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
Get details of a specific schedule for a full backup for a specific volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/full_backup_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/full_backup_schedule/1234578ABC-12312512-ABC121298712123
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "full", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, list all scheduled snapshots
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshot_schedule
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/snapshot_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "snapshot", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
Get details of a specific schedule for a incremental backup for a specific volume
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}/incremental_backup_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volume/1234ABB4-CF8B-11E1-A175-422A1D9586CD/incremental_backup_schedule/1234578ABC-12312512-ABC121298712123
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "incremental", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, delete a schedule of when to run full backups
method
DELETE
URL
/v1/accounts/{api_id}/volumes/{volume_id}/full_backup_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/full_backup_schedule/14F6E0B4-CF8B-11E1-A175-422A1D9586C3
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: A confirmation of the schedule to be deleted
examples
  1. {
     "message" : "Schedule 93BEE70C-BCF6-11E2-A506-806642F52D07 deleted" 
    }
For a volume, create a schedule of when to create snapshots
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshot_schedule
query parameters
(none)
body parameters
  • schedule: An iCal data element describing the schedule of when to run the backup example: FREQ=DAILY;INTERVAL=2;COUNT=6
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/snapshot_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • schedule_id: The UUID of the schedule created
examples
  1. {
     "schedule_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07" 
    }
For an account, list all snapshots for scheduled for all volumes
method
GET
URL
/v1/accounts/{api_id}/snapshot_schedule
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/snapshot_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of schedules returned
  • schedules: An array of schedule objects
examples
  1. {
     "count" : "1", "schedules" : [ { "backup_type" : "snapshot", "api_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07", "auth_type" : "API-Test", "volume_id" : "88DF95B0-BCF6-11E2-9985-E129F0700925", "schedule_id" : "88E68D3E-BCF6-11E2-89A3-AC5204648A96", "schedule" : "ABCDEFG" } ] 
    }
For a volume, create a schedule of when to run incremental backups
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/incremental_backup_schedule
query parameters
(none)
body parameters
  • schedule: An iCal data element describing the schedule of when to run the backup example: FREQ=DAILY;INTERVAL=2;COUNT=6
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/incremental_backup_schedule
HTTP Response
status-code
200
reason-phrase
OK
body
  • schedule_id: The UUID of the schedule created
examples
  1. {
     "schedule_id" : "88BEE70C-BCF6-11E2-A506-806642F52D07" 
    }
For a volume, delete a schedule of when to run snapshots
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}/snapshot_schedule/{schedule_id}
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/volumes/44F6E0B4-CF8B-11E1-A175-422A1D9586C3/snapshot_schedule/14F6E0B4-CF8B-11E1-A175-422A1D9586C3
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: A confirmation of the schedule to be deleted
examples
  1. {
     "message" : "Schedule 93BEE70C-BCF6-11E2-A506-806642F52D07 deleted" 
    }

The searches resource allows you to save, retrieve, and delete search strings; search strings can be used on search resources, such as /v1/accounts/{api_id}/instances/search.

List all searches available to an account.
method
GET
URL
/v1/accounts/{api_id}/searches
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/26135998-1CA2-11E2-8C60-5CA9E6D04373/searches
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of searches returned in this response
  • searches: list of searches
examples
  1. {
      "count": 2,
      "searches": [
        {
          "search_id": "5CA9E6D0-1CA2-11E2-8C60-261359983222",
          "name": "Search A",
          "search": "id:26F622DC-1CA2-11E2-8C60-5CA9E6D04373"
        },
         {
          "search_id": "C5A96E0D-1CA2-11E2-8C60-621539893270",
          "name": "Search B",
          "search": "ipaddress:192.168"
        }
      ]
    }

An server is a virtual machine associated with a customer account. Customers with their own API keys may manage their servers using the API. Changes to customer accounts are automatically reflected in the reseller billing information available in the BetterServers billing area.

The servers resource supersedes the instances resource; the servers resource should be preferred.

List all servers associated with this account matching the specified criteria; if no criteria are given, list all servers.
method
GET
URL
/v1/accounts/{api_id}/servers
query parameters
  • (optional)id: UUID of an server
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/servers
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of servers in this response
  • servers: a list of server records
examples
  1. {
      "count": 2,
      "servers": [
        {
          "assigned_ips": [
          ],
          "cpu_number": 1,
          "cpu_speed": 1000,
          "cpu_used": "",
          "created": "2014-01-07T09:33:46-0700",
          "display_name": "API-Test 73037",
          "hostname": "",
          "hypervisor": "KVM",
          "id": "5d19bc4d-a997-490c-aab2-9c37f30995e4",
          "iso_id": "e9e72e10-f8b9-4ede-be3d-98fbfe8b2c84",
          "iso_name": "centos65x64",
          "memory": 2048,
          "name": "api-test-73037",
          "network_kbs_read": "",
          "network_kbs_write": "",
          "nic": [
            {
              "gateway": "10.99.222.1",
              "id": "853a3f2d-8d2c-402f-aeb0-038a68157ed5",
              "ip_address": "10.99.222.21",
              "is_default": true,
              "mac_address": "02:00:01:d1:00:02",
              "netmask": "255.255.255.224",
              "network_id": "2c2c87b9-e9d7-43b5-bd2b-294dd29f08d3",
              "network_name": "scott-73037.api-test-network-1/27",
              "traffic_type": "Guest",
              "type": "Isolated"
            }
          ],
          "object_type": "server",
          "root_device_id": 0,
          "server_name": "",
          "service_offering_id": "76102490-2d3f-42ba-8507-6f3df540c5cd",
          "service_offering_name": "test-1x1GHz-2Gb",
          "state": "Starting",
          "tags": [
            {
              "account": "biff2@api-test",
              "domain": "TEFA96DA",
              "domain_id": "31e2f4d6-a676-457e-8029-a8659d7c80d5",
              "key": "_widgetapikey",
              "resource_id": "5d19bc4d-a997-490c-aab2-9c37f30995e4",
              "resource_type": "UserVm",
              "value": "5B036530-77B9-11E3-86E8-D27354953A74"
            }
          ],
          "template_display_text": "centos65x64",
          "template_id": "e9e72e10-f8b9-4ede-be3d-98fbfe8b2c84",
          "template_name": "centos65x64",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        },
        {
          "assigned_ips": [
          ],
          "cpu_number": 1,
          "cpu_speed": 1000,
          "cpu_used": "",
          "created": "2014-01-07T09:33:46-0700",
          "display_name": "API-Test",
          "hostname": "",
          "hypervisor": "KVM",
          "id": "5d19bc4d-a997-490c-aab2-9c37f30995e4",
          "iso_id": "e9e72e10-f8b9-4ede-be3d-98fbfe8b2c84",
          "iso_name": "centos65x64",
          "memory": 2048,
          "name": "api-test",
          "network_kbs_read": "",
          "network_kbs_write": "",
          "nic": [
            {
              "gateway": "10.99.222.1",
              "id": "853a3f2d-8d2c-402f-aeb0-038a68157ed5",
              "ip_address": "10.99.222.21",
              "is_default": true,
              "mac_address": "02:00:01:d1:00:02",
              "netmask": "255.255.255.224",
              "network_id": "2c2c87b9-e9d7-43b5-bd2b-294dd29f08d3",
              "network_name": "scott-73037.api-test-network-1/27",
              "traffic_type": "Guest",
              "type": "Isolated"
            }
          ],
          "object_type": "server",
          "root_device_id": 0,
          "server_name": "",
          "service_offering_id": "76102490-2d3f-42ba-8507-6f3df540c5cd",
          "service_offering_name": "test-1x1GHz-2Gb",
          "state": "Starting",
          "tags": [
            {
              "account": "biff@api-test",
              "domain": "TEFA96DA",
              "domain_id": "31e2f4d6-a676-457e-8029-a8659d7c80d5",
              "key": "_widgetapikey",
              "resource_id": "5d19bc4d-a997-490c-aab2-9c37f30995e4",
              "resource_type": "UserVm",
              "value": "5B036530-77B9-11E3-86E8-D27354953A74"
            }
          ],
          "template_display_text": "centos65x64",
          "template_id": "e9e72e10-f8b9-4ede-be3d-98fbfe8b2c84",
          "template_name": "centos65x64",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        }
      ]
    }
View details of a server.
method
GET
URL
/v1/accounts/{api_id}/servers/{server_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/servers/b627b88e-9959-4703-b139-7df96e19e069
HTTP Response
status-code
200
reason-phrase
OK
body
  • assigned_ips: an array of IP addresses assigned to this server
  • cpu_number: number of cores
  • cpu_speed: CPU speed
  • cpu_used: current CPU usage
  • created: date server was created
  • display_name: description of server
  • hostname: server hostname
  • hypervisor: hypervisor this server is running under
  • id: UUID of this server
  • iso_id: UUI of attached ISO, if any
  • iso_name: name of attached ISO, if any
  • lock: lock on this server, if any
  • memory: memory in Gb
  • name: name of the server
  • network_kbs_read: network reads in Kbs
  • network_kbs_write: network writes in Kbs
  • nic: an array of network interfaces on this server
  • object_type: server
  • root_device_id: id of the root device
  • server_name: name of the server
  • service_offering_id: UUID of the service offering this server is running
  • service_offering_name: name of the service offering this server is running
  • state: state of the server: Running, Starting, Stopping, Stopped, Error
  • tags: an array of tags on this server
  • template_display_text: description of the template this server is derived from
  • template_id: UUID of the template this server is derived from
  • template_name: name of the template this server is derived from
  • zone_id: UUID of zone
  • zone_name: name of zone
examples
  1. {
      "assigned_ips": [
      ],
      "cpu_number": 1,
      "cpu_speed": 2000,
      "cpu_used": "0.05%",
      "created": "2013-12-30T15:47:45-0700",
      "display_name": "test-131230b",
      "hostname": "test-131230b",
      "hypervisor": "KVM",
      "id": "e2fac41b-6ee1-4137-b03d-bb5d4c863fb5",
      "iso_id": "",
      "iso_name": "",
      "lock": null,
      "memory": 1024,
      "name": "e2fac41b-6ee1-4137-b03d-bb5d4c863fb5",
      "network_kbs_read": 24,
      "network_kbs_write": 97,
      "nic": [
        {
          "gateway": "10.75.0.1",
          "id": "151b99e6-58d9-435a-b7f9-871f0a9100cc",
          "ip_address": "10.75.0.204",
          "is_default": true,
          "mac_address": "02:00:61:b3:00:11",
          "netmask": "255.255.252.0",
          "network_id": "ef5eb63b-615d-4ffa-8dab-c5bce801c5e8",
          "network_name": "Network 1",
          "traffic_type": "Guest",
          "type": "Isolated"
        }
      ],
      "object_type": "server",
      "root_device_id": 0,
      "server_name": "",
      "service_offering_id": "3fa8ad79-32c9-4d6c-8024-05d03b58d503",
      "service_offering_name": "1 Core, 1024MB RAM",
      "state": "Stopped",
      "tags": [
      ],
      "template_display_text": "20131217, Created by publishTemplate",
      "template_id": "554727fb-0feb-48e3-890d-18311f1befdf",
      "template_name": "CentOS 6 Standard (64-Bit)-OLD",
      "zone_id": "f4546981-59a9-48f1-962e-cb6d44f7a7ce",
      "zone_name": "US-UTAH1"
    }

A service offering is a group of CPU and memory settings used to create virtual machine instances. Administrators can create and remove their own service offerings.

List all service offerings available to this auth type.
This method is available only to admin accounts.
method
GET
URL
/v1/serviceofferings
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/serviceofferings
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of service offerings in this response
  • serviceofferings: list of service offerings
examples
  1. {
      "count": 2,
      "serviceofferings": [
        {
          "cpunumber": 1,
          "cpuspeed": 500,
          "created": "2012-09-19T13:30:04-0600",
          "defaultuse": false,
          "displaytext": "Small Instance",
          "id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
          "issystem": false,
          "limitcpuuse": false,
          "memory": 512,
          "name": "Small Instance",
          "offerha": false,
          "storagetype": "shared"
        },
        {
          "cpunumber": 1,
          "cpuspeed": 1000,
          "created": "2012-09-19T13:30:04-0600",
          "defaultuse": false,
          "displaytext": "Medium Instance",
          "id": "bfcd8902-8da1-400d-afe2-ec5c8f796039",
          "issystem": false,
          "limitcpuuse": false,
          "memory": 1024,
          "name": "Medium Instance",
          "offerha": false,
          "storagetype": "shared"
        }
      ]
    }
List service offerings.
method
GET
URL
/v1/accounts/{api_id}/service-offerings
query parameters
  • (optional)keyword: search by keyword
body parameters
(none)
examples
  1. GET /v1/accounts/6F00C27A-1D43-11E2-B788-58A9E6D04373/service-offerings
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of service offerings in this response
  • serviceofferings: list of service offerings
examples
  1. {
      "count": 2,
      "serviceofferings": [
        {
          "cpunumber": 1,
          "cpuspeed": 500,
          "created": "2012-09-19T13:30:04-0600",
          "defaultuse": false,
          "displaytext": "Small Instance",
          "id": "802dfb1d-a579-4876-b870-cd92d3f3cc9e",
          "issystem": false,
          "limitcpuuse": false,
          "memory": 512,
          "name": "Small Instance",
          "offerha": false,
          "storagetype": "shared"
        },
        {
          "cpunumber": 1,
          "cpuspeed": 1000,
          "created": "2012-09-19T13:30:04-0600",
          "defaultuse": false,
          "displaytext": "Medium Instance",
          "id": "bfcd8902-8da1-400d-afe2-ec5c8f796039",
          "issystem": false,
          "limitcpuuse": false,
          "memory": 1024,
          "name": "Medium Instance",
          "offerha": false,
          "storagetype": "shared"
        }
      ]
    }
Create a service offering.
This method is available only to admin accounts.
method
POST
URL
/v1/serviceofferings
query parameters
(none)
body parameters
  • name: name of the service offering
  • display_text: brief description of the service offering
  • cpu_number: number of CPUs
  • cpu_speed: speed of CPUs in Mhz; defaults to 2000
  • memory: memory in megabytes
  • (optional)offer_ha: if true, this service offering is marked as high availability; default is false
examples
  1. POST /v1/serviceofferings
    
    {"memory":1024,"cpu_number":2,"name":"2x1GHz1Gb","display_text":"2 x 1GHz, 1024 Mb","cpu_speed":1000,"offer_ha":true}
HTTP Response
status-code
200
reason-phrase
OK
body
  • id: UUID of the new service offering
  • cpunumber: number of CPUs
  • cpuspeed: speed of CPUs
  • created: date service offering was created
  • displaytext: the display text of the offering
  • domain: the domain (or auth_type) of the offering
  • limitcpuuse: true if CPU limited
  • memory: amount of memory in Gb
  • name: name of the service offering
  • offerha: true if this offering is set to high availability
  • storagetype: always 'shared'
examples
  1. {
      "cpunumber": 2,
      "cpuspeed": 1000,
      "created": "2012-11-14T12:27:55-0700",
      "defaultuse": false,
      "displaytext": "2 x 1GHz, 1024 Mb",
      "domain": "HostingCo",
      "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
      "id": "06ee456e-edca-40ed-b9bf-0cf553fd719b",
      "issystem": false,
      "limitcpuuse": false,
      "memory": 1024,
      "name": "2x1GHz1Gb",
      "offerha": false,
      "storagetype": "shared"
    }
Destroy a service offering.
This method is available only to admin accounts.
method
DELETE
URL
/v1/serviceofferings/{service_offering_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/serviceofferings/f933cb15-8cba-462c-8de8-b5f65e0ee3bf
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating whether the offering was deleted
examples
  1. {"message":"service offering deleted"}

Arbitrary key/value storage. This resource allows you to create a store, which you can think of as a bucket or directory. You add, remove, and list key/value pairs in the store. For example, you may wish to create a store called customers. You may then add a key for each customer (some unique identifier, such as an email address or a UUID) with an associated data value (for example, a simple string, or a JSON document up to 65k in length).

Remove data associated with one store/key pair. When the last key is removed from a store, the store is also automatically removed.
method
GET
URL
/v1/accounts/{api_id}/stores/{store}/{key}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/stores/blog%20entries/2014-01-15
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the success of the operation
examples
  1. {
      "message": "key successfully deleted"
    }
List data associated with one store/key pair.
method
GET
URL
/v1/accounts/{api_id}/stores/{store}/{key}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/stores/blog%20entries/2014-01-15
HTTP Response
status-code
200
reason-phrase
OK
body
  • data: the data value
  • updated: a timestamp when this record was last updated
examples
  1. {
      "data": "This is my first blog entry! How do you like it?",
      "updated": "2014-01-16 18:51:04"
    }
List all stores associated with an account.
method
GET
URL
/v1/accounts/{api_id}/stores
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/stores
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: the number of store/key/data tuples in this response
  • stores: a list of store/key/data tuples (see List store key)
examples
  1. {
      "count": 3,
      "stores": [
        {
          "data": "zone-1, zone-2, etc.",
          "key": "some{\"crazy}\".store!",
          "store": "backup_zone_ids",
          "updated": "2014-01-16 18:51:04"
        },
        {
          "data": "This is my first blog entry! Yay!",
          "key": "2014-01-16",
          "store": "blog entries",
          "updated": "2014-01-16 18:51:04"
        },
        {
          "data": "My second blog entry--I'm famous now.",
          "key": "2014-01-17",
          "store": "blog entries",
          "updated": "2014-01-16 18:51:04"
        }
      ]
    }
List one stores associated with an account.
method
GET
URL
/v1/accounts/{api_id}/stores/{store_name}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/stores/blog%20entries
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: the number of key/data tuples in this store
  • {store-name}: a list of key/data tuples in the specified store
examples
  1. {
      "count": 2,
      "stores": [
        {
          "data": "This is my first blog entry! Yay!",
          "key": "2014-01-16",
          "updated": "2014-01-16 18:51:04"
        },
        {
          "data": "My second blog entry--I'm famous now.",
          "key": "2014-01-17",
          "updated": "2014-01-16 18:51:04"
        }
      ]
    }
Create or update a key/value pair in a store. Stores and keys may be named anything up to 255 characters long. Data values may be any textual utf-8 or ascii data up to 65k. No separate operation is needed to create a store--the store is automatically created if it doesn't exist simply by referencing it in the URL along with the key you wish to store.
method
PUT
URL
/v1/accounts/{api_id}/stores/{store_name}/{key}
query parameters
(none)
body parameters
  • data: arbitrary textual data (up to 65k)
examples
  1. PUT /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/my-store/my-key
    
    {"data":"my-value"}
HTTP Response
status-code
201
reason-phrase
Created
body
  • message: a brief message indicating the store has been created.
examples
  1. {"message":"Data successfully stored"}

other responses

status-code reason-phrase description
200 OK a brief message indicating the store has been updated.

Templates are installable OS images. You can create templates from a URL, list templates, delete templates, etc.

View a template.
method
GET
URL
/v1/accounts/{api_id}/templates/{template_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/templates/c4dc9c1d-44bb-4a77-adc3-3f118657cc12
HTTP Response
status-code
200
reason-phrase
OK
body
  • account: owner of the template
  • created: date template was created
  • display_text: description of the template
  • format: usually qcow2
  • hypervisor: hypervisor of the template
  • id: UUID of the template
  • is_extractable: this template is capable of creating VM instances
  • is_ready: is the template ready to use
  • name: name of the template
  • os_type_id: generic operating system type
  • password_enabled: the template supports hypervisor password changes
  • ssh_key_enabled: template supports hypervisor ssh key updates
  • status: state of the template
  • zone_id: zone of the template
examples
  1. {
      "account": "api-test3-user@example.com",
      "created": "2013-06-11T21:26:26-0600",
      "crossZones": false,
      "display_text": "scott-84307-test-url-template",
      "format": "QCOW2",
      "hypervisor": "KVM",
      "id": "c4dc9c1d-44bb-4a77-adc3-3f118657cc12",
      "is_extractable": false,
      "is_public": false,
      "is_ready": false,
      "name": "84307-test-url-template",
      "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
      "os_type_name": "Other PV (64-bit)",
      "password_enabled": false,
      "ssh_key_enabled": false,
      "status": "ready",
      "tags": [
      ],
      "template_type": "USER",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_name": "US-UTAH1-TEST"
    }
Delete a template.
method
DELETE
URL
/v1/accounts/{api_id}/templates/{template_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/templates/c4dc9c1d-44bb-4a77-adc3-3f118657cc12
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a job id you may use to query the status of the deletion
examples
  1. {"job_id":"c4dc9c1d-44bb-4a77-adc3-3f118657cc12"}
Create a new template from a URL.
method
POST
URL
/v1/accounts/{api_id}/templates
query parameters
(none)
body parameters
  • display_text: a description of the template
  • name: the name of the template
  • format: format of URL image: raw (for URLs ending in .raw, .raw.gz, .raw.bz2, .raw.zip, .img, .img.gz, etc.), qcow2 (for URLs ending in .qcow2, .qcow2.gz, .qcow2.bz2, .qcow2.zip, etc.), vmdk (for URLs ending in .vmdk, .vmdk.gz, etc.), or vhd (for URLs ending in .vhd, .vhd.gz, .vhd.bz2, etc.)
  • os_type_id: an ID identifying an OS type (see list OS types)
  • url: the URL of the image
  • zone_id: the UUID of the zone
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/templates
    
    {
      "display_text": "69278-test-url-template",
      "format": "raw",
      "hypervisor": "kvm",
      "name": "69278-test-url-template",
      "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
      "url": "http://example.com/d88130962a4c456cbc494333e6539d77.img",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID of the new template
  • job_id: UUID identifying the job responsible for creating the template
examples
  1. {
      "id": "27470ac7-08ee-44f7-9fc8-309115272970",
      "job_id": "2c339000-6d36-4ef0-8645-a980d756774f"
    }
Update template information.
method
PATCH
URL
/v1/accounts/{api_id}/templates/{template_id}
query parameters
(none)
body parameters
  • (optional)display_text: the new description of the template
  • (optional)bootable: boolean; set true if template is bootable
  • (optional)format: template format (qcow2, iso, etc.)
  • (optional)name: name of the template
  • (optional)os_type_id: the OS type id
  • (optional)password_enabled: boolean; set true if template supports password changes
examples
  1. PATCH /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/templates/c4dc9c1d-44bb-4a77-adc3-3f118657cc12
    
    {"display_text":"new template"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • account: owner of the template
  • created: date template was created
  • display_text: description of the template
  • format: usually qcow2
  • hypervisor: hypervisor of the template
  • id: UUID of the template
  • is_extractable: this template is capable of creating VM instances
  • is_ready: is the template ready to use
  • name: name of the template
  • os_type_id: generic operating system type
  • password_enabled: the template supports hypervisor password changes
  • ssh_key_enabled: template supports hypervisor ssh key updates
  • status: state of the template
  • zone_id: zone of the template
examples
  1. {
      "account": "api-test3-user@example.com",
      "created": "2013-06-11T21:26:26-0600",
      "crossZones": false,
      "display_text": "scott-84307-test-url-template",
      "format": "QCOW2",
      "hypervisor": "KVM",
      "id": "c4dc9c1d-44bb-4a77-adc3-3f118657cc12",
      "is_extractable": false,
      "is_public": false,
      "is_ready": false,
      "name": "84307-test-url-template",
      "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
      "os_type_name": "Other PV (64-bit)",
      "password_enabled": false,
      "ssh_key_enabled": false,
      "status": "ready",
      "tags": [
      ],
      "template_type": "USER",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_name": "US-UTAH1-TEST"
    }
List templates available to this account.
method
GET
URL
/v1/accounts/{api_id}/templates
query parameters
  • (optional)owner: public or self; if present, only public or self templates will be listed. All public templates are also executable.
  • (optional)template_type: qcow2, iso, etc.
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/templates?owner=self
HTTP Response
status-code
200
reason-phrase
OK
body
  • total: total number of templates available
  • count: number of templates in this response
  • templates: list of templates
examples
  1. {
      "count": 2,
      "templates": [
        {
          "account": "api-test3-user@example.com",
          "created": "2013-06-11T20:17:40-0600",
          "crossZones": false,
          "display_text": "scott-83424-test-url-template",
          "domain": "API-Test3",
          "domain_id": "ef6f97da-93e0-4d63-84e3-4450e1f6a665",
          "format": "QCOW2",
          "hypervisor": "KVM",
          "id": "4450770b-88a7-4329-863c-28a51cad8987",
          "is_extractable": false,
          "is_public": false,
          "is_ready": false,
          "name": "83424-test-url-template",
          "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
          "os_type_name": "Other PV (64-bit)",
          "password_enabled": false,
          "ssh_key_enabled": false,
          "status": "Connection timed out",
          "tags": [
          ],
          "template_type": "USER",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        },
        {
          "account": "api-test3-user@example.com",
          "created": "2013-06-11T21:26:26-0600",
          "crossZones": false,
          "display_text": "scott-84307-test-url-template",
          "domain": "API-Test3",
          "domain_id": "ef6f97da-93e0-4d63-84e3-4450e1f6a665",
          "format": "QCOW2",
          "hypervisor": "KVM",
          "id": "c4dc9c1d-44bb-4a77-adc3-3f118657cc12",
          "is_extractable": false,
          "is_public": false,
          "is_ready": false,
          "name": "84307-test-url-template",
          "os_type_id": "1b0971e3-7c64-42d5-a5ec-b1b0a4858c32",
          "os_type_name": "Other PV (64-bit)",
          "password_enabled": false,
          "ssh_key_enabled": false,
          "status": "ready",
          "tags": [
          ],
          "template_type": "USER",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        }
      ]
    }

Every VM must have at least one disk volume. Volumes can be created, attached to an instance, detached from an instance, destroyed, listed, etc.

Create a new volume from a disk offering or an existing snapshot.
method
POST
URL
/v1/accounts/{api_id}/volumes
query parameters
(none)
body parameters
  • name: name of the volume
  • disk_offering_id: UUID of the disk offering to derive the volume from; mutually exclusive with snapshot_id
  • zone_id: UUID of the zone to create the volume in
  • (optional)size: size of the new volume, if disk offering specifies a custom size
  • snapshot_id: UUID of a snapshot to derive the volume from; mutually exclusive with disk_offering_id
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes
    
    {"name":"Test Volume 70828","disk_offering_id":"3ffd583c-1ab6-4a73-8087-af6102aae8ed","zone_id":"63d968ee-34ec-4bd6-9ba1-a8ad9769b415"}
  2. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes
    
    {"name":"Volume from snapshot 87081","snapshot_id":"fa1e50ab-fc7f-4b07-b3ed-171f4a47ecc2"}
HTTP Response
status-code
202
reason-phrase
OK
body
  • id: UUID of the new volume
  • job_id: UUID identifying the job responsible for creating the volume
examples
  1. {
      "id": "27470ac7-08ee-44f7-9fc8-309115272970",
      "job_id": "2c339000-6d36-4ef0-8645-a980d756774f"
    }
Migrate volume to a storage type, either 'SSD' or 'spindle'.
This method is available only to admin accounts.
method
PATCH
URL
/v1/accounts/{account_id}/volumes/{volume_id}
query parameters
(none)
body parameters
  • storage_type: the new storage type. 'SSD' or 'spindle'
examples
  1. /v1/accounts/FA3F8002-2F5D-11E2-8E5D-65DAE6D04373/volumes/2204e87c-fb2d-45a3-9d16-05a023428f6d
    
    {"storage_type":"SSD"}
HTTP Response
status-code
202
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for migrating the volume
examples
  1. {
      "job_id": "e75fd0f3-52ff-440d-ba75-1ce224d2d681"
    }
Destroy a volume by id. If the volume is in ready state, a job will be created to destroy the volume. Otherwise the volume will be destroyed immediately.
This method is available only to admin accounts.
method
DELETE
URL
/v1/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: id of the job responsible for destroying the volume
examples
  1. {
      "job_id": "2fa330e9-0ace-4162-9766-f041d438d645"
    }

other responses

status-code reason-phrase description
200 OK A brief message indicating success or failure.
List volumes across all accounts.
This method is available only to admin accounts.
method
GET
URL
/v1/volumes
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/volumes
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of volumes in this response
  • volumes: list of volumes
examples
  1. {
      "count": 2,
      "total": 2,
      "volumes": [
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:23-0700",
          "destroyed": false,
          "device_id": null,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": true,
          "id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
          "is_extractable": true,
          "name": "Accounting Extra Space",
          "server_display_name": null,
          "server_id": null,
          "server_name": null,
          "server_state": null,
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 10737418240,
          "state": "Allocated",
          "storage": null,
          "storage_id": null,
          "tags": [
            {
              "auth_type": "HAXA49FE",
              "key": "_geo_redundant",
              "resource_id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
              "resource_type": "Volume",
              "value": "true"
            }
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        },
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:19-0700",
          "destroyed": false,
          "device_id": 1,
          "deviceid": 1,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": false,
          "domain": "HAXA49FE",
          "id": "620c5e3c-596c-489b-9800-3ae19750ec70",
          "is_extractable": true,
          "name": "DATA-15113",
          "server_display_name": "Accounting Server 1",
          "server_id": "e6be3c87-68d7-4296-a7a7-9eff44d75b61",
          "server_name": "accounting",
          "server_state": "Running",
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 7516192768,
          "state": "Ready",
          "storage": null,
          "storage_id": null,
          "tags": [
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        }
      ]
    }
Migrate any volume to a storage type, either 'SSD' or 'spindle'.
This method is available only to admin accounts.
method
PATCH
URL
/v1/volumes/{volume_id}
query parameters
(none)
body parameters
  • storage_type: the new storage type. 'SSD' or 'spindle'
examples
  1. /v1/volumes/2204e87c-fb2d-45a3-9d16-05a023428f6d
    
    {"storage_type":"SSD"}
HTTP Response
status-code
202
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for migrating the volume
examples
  1. {
      "job_id": "e75fd0f3-52ff-440d-ba75-1ce224d2d681"
    }
View a volume's details.
method
GET
URL
/v1/accounts/{api_id}/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
200
reason-phrase
OK
body
  • attached: date when this volume was attached (if attached)
  • auth_type: auth type of volume owner
  • backup_storage_ids: a list of backup storage ids
  • created: date volume was created
  • destroyed: (boolean) is the volume destroyed
  • device_id: device id of volume (if attached)
  • disk_offering_display_text: display text of the disk offering
  • disk_offering_id: UUID of the disk offering
  • disk_offering_name: disk offering name
  • display_volume: (boolean) should volume be displayed
  • id: UUID of the volume
  • is_extractable: (boolean)
  • lock: if present, describes the nature of the lock on this volume
  • name: name of the volume
  • server_display_name: display name of server volume is attached to
  • server_id: UUID of server volume is attached to
  • server_name: name of server volume is attached to
  • server_state: state of server volume is attached to
  • service_offering_display_text: display text of volume service offering
  • service_offering_id: id of volume service offering
  • service_offering_name: name of volume service offering
  • size: volume size in bytes
  • state: current state of the volume
  • storage:
  • storagetype:
  • tags: list of tags
  • type: volume type (ROOT or DATADISK)
  • virtualmachineid: id of virtual machine (if attached)
  • vmstate: state of attached VM
  • zone_id: UUID of the zone this volume belongs to
  • zone_name: name of the zone this volume belongs to
examples
  1. {
      "auth_type": "HAXA49FE",
      "backup_storage_ids": [],
      "created": "2014-01-06T11:32:23-0700",
      "destroyed": false,
      "device_id": null,
      "disk_offering_display_text": "creative name for custom disk offering",
      "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
      "disk_offering_name": "Custom 2",
      "display_volume": true,
      "id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
      "is_extractable": true,
      "lock": {
        "action": "create volume",
        "expires": "0",
        "location": "127.0.0.1",
        "locktime": "2014-02-03 18:49:29"
      },
      "name": "Accounting Extra Space",
      "server_display_name": null,
      "server_id": null,
      "server_name": null,
      "server_state": null,
      "service_offering_display_text": null,
      "service_offering_id": null,
      "service_offering_name": null,
      "size": 10737418240,
      "state": "Allocated",
      "storage": null,
      "storage_id": null,
      "tags": [
        {
          "auth_type": "HAXA49FE",
          "key": "_geo_redundant",
          "resource_id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
          "resource_type": "Volume",
          "value": "true"
        }
      ],
      "type": "DATADISK",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_name": "US-UTAH1-TEST"
    }
Resize a volume. If the volume is based on a disk offering with custom size, then the disk_offering_id is optional; otherwise, specify a new disk offering (including a disk offering with custom size). Shrinking volumes is supported. The volume is truncated at the end of the volume; any data at the end of the volume may be lost.
method
PATCH
URL
/v1/accounts/{api_id}/volumes/{volume_id}
query parameters
(none)
body parameters
  • size: the new size of the volume in GB
  • (optional)disk_offering_id: UUID of the disk offering to derive the new size from
  • (optional)shrink: a boolean (0 or 1) value authorizing the volume to shrink if necessary; data may be lost--use with caution
examples
  1. /v1/accounts/FA3F8002-2F5D-11E2-8E5D-65DAE6D04373/volumes/2204e87c-fb2d-45a3-9d16-05a023428f6d
    
    {"size":20}
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for resizing the volume
examples
  1. {
      "job_id": "e75fd0f3-52ff-440d-ba75-1ce224d2d681"
    }
List volumes by account.
method
GET
URL
/v1/accounts/{api_id}/volumes
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of volumes in this response
  • volumes: list of volumes
examples
  1. {
      "count": 2,
      "total": 2,
      "volumes": [
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:23-0700",
          "destroyed": false,
          "device_id": null,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": true,
          "id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
          "is_extractable": true,
          "name": "Accounting Extra Space",
          "server_display_name": null,
          "server_id": null,
          "server_name": null,
          "server_state": null,
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 10737418240,
          "state": "Allocated",
          "storage": null,
          "storage_id": null,
          "tags": [
            {
              "auth_type": "HAXA49FE",
              "key": "_geo_redundant",
              "resource_id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
              "resource_type": "Volume",
              "value": "true"
            }
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        },
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:19-0700",
          "destroyed": false,
          "device_id": 1,
          "deviceid": 1,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": false,
          "domain": "HAXA49FE",
          "id": "620c5e3c-596c-489b-9800-3ae19750ec70",
          "is_extractable": true,
          "name": "DATA-15113",
          "server_display_name": "Accounting Server 1",
          "server_id": "e6be3c87-68d7-4296-a7a7-9eff44d75b61",
          "server_name": "accounting",
          "server_state": "Running",
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 7516192768,
          "state": "Ready",
          "storage": null,
          "storage_id": null,
          "tags": [
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        }
      ]
    }
Clone an existing volume, thereby creating a new volume with a new name
method
POST
URL
/v1/accounts/{api_id}/volumes/{volume_id}
query parameters
(none)
body parameters
  • name: name of the new volume
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes
    
    {"name":"Test Volume 70828""}
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for cloning the volume
examples
  1. {
      "job_id": "e75fd0f3-52ff-440d-ba75-1ce224d2d681"
    }
List volumes attached to an instance.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/volumes
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/instances/23d65fba-0995-4235-8dbd-d5cd86d1cefc/volumes
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of volumes in this response
  • volumes: list of volumes
examples
  1. {
      "count": 2,
      "total": 2,
      "volumes": [
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:23-0700",
          "destroyed": false,
          "device_id": null,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": true,
          "id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
          "is_extractable": true,
          "name": "Accounting Extra Space",
          "server_display_name": null,
          "server_id": null,
          "server_name": null,
          "server_state": null,
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 10737418240,
          "state": "Allocated",
          "storage": null,
          "storage_id": null,
          "tags": [
            {
              "auth_type": "HAXA49FE",
              "key": "_geo_redundant",
              "resource_id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
              "resource_type": "Volume",
              "value": "true"
            }
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        },
        {
          "auth_type": "HAXA49FE",
          "created": "2014-01-06T11:32:19-0700",
          "destroyed": false,
          "device_id": 1,
          "deviceid": 1,
          "disk_offering_display_text": "creative name for custom disk offering",
          "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
          "disk_offering_name": "Custom 2",
          "display_volume": false,
          "domain": "HAXA49FE",
          "id": "620c5e3c-596c-489b-9800-3ae19750ec70",
          "is_extractable": true,
          "name": "DATA-15113",
          "server_display_name": "Accounting Server 1",
          "server_id": "e6be3c87-68d7-4296-a7a7-9eff44d75b61",
          "server_name": "accounting",
          "server_state": "Running",
          "service_offering_display_text": null,
          "service_offering_id": null,
          "service_offering_name": null,
          "size": 7516192768,
          "state": "Ready",
          "storage": null,
          "storage_id": null,
          "tags": [
          ],
          "type": "DATADISK",
          "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zone_name": "US-UTAH1-TEST"
        }
      ]
    }
View an instance volume's details.
method
GET
URL
/v1/accounts/{api_id}/instances/{instance_id}/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/instances/23d65fba-0995-4235-8dbd-d5cd86d1cefc/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
200
reason-phrase
OK
body
  • auth_type: auth type of volume owner
  • backup_storage_ids: a list of backup storage ids
  • created: date volume was created
  • destroyed: (boolean) is the volume destroyed
  • device_id: device id of volume (if attached)
  • disk_offering_display_text: display text of the disk offering
  • disk_offering_id: UUID of the disk offering
  • disk_offering_name: disk offering name
  • display_volume: (boolean) should volume be displayed
  • id: UUID of the volume
  • is_extractable: (boolean)
  • lock: if present, describes the nature of the lock on this volume
  • name: name of the volume
  • server_display_name: display name of server volume is attached to
  • server_id: UUID of server volume is attached to
  • server_name: name of server volume is attached to
  • server_state: state of server volume is attached to
  • service_offering_display_text: display text of volume service offering
  • service_offering_id: id of volume service offering
  • service_offering_name: name of volume service offering
  • size: volume size in bytes
  • state: current state of the volume
  • storage:
  • storagetype:
  • tags: list of tags
  • type: volume type (ROOT or DATADISK)
  • virtualmachineid: id of virtual machine (if attached)
  • vmstate: state of attached VM
  • zone_id: UUID of the zone this volume belongs to
  • zone_name: name of the zone this volume belongs to
examples
  1. {
      "auth_type": "HAXA49FE",
      "backup_storage_ids": [],
      "created": "2014-01-06T11:32:23-0700",
      "destroyed": false,
      "device_id": null,
      "disk_offering_display_text": "creative name for custom disk offering",
      "disk_offering_id": "51e37a55-90fb-4470-84cc-0f44df13c47e",
      "disk_offering_name": "Custom 2",
      "display_volume": true,
      "id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
      "is_extractable": true,
      "lock": {
        "action": "create volume",
        "expires": "0",
        "location": "127.0.0.1",
        "locktime": "2014-02-03 18:49:29"
      },
      "name": "Accounting Extra Space",
      "server_display_name": null,
      "server_id": null,
      "server_name": null,
      "server_state": null,
      "service_offering_display_text": null,
      "service_offering_id": null,
      "service_offering_name": null,
      "size": 10737418240,
      "state": "Allocated",
      "storage": null,
      "storage_id": null,
      "tags": [
        {
          "auth_type": "HAXA49FE",
          "key": "_geo_redundant",
          "resource_id": "4a26cbd6-e19a-4505-9e4c-34f0f1822948",
          "resource_type": "Volume",
          "value": "true"
        }
      ],
      "type": "DATADISK",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_name": "US-UTAH1-TEST"
    }
Resize any volume. If the volume is based on a disk offering with custom size, then the disk_offering_id is optional; otherwise, specify a new disk offering (including a disk offering with custom size). Shrinking volumes is supported. The volume is truncated at the end of the volume; any data at the end of the volume may be lost.
This method is available only to admin accounts.
method
PATCH
URL
/v1/volumes/{volume_id}
query parameters
(none)
body parameters
  • size: the new size of the volume in GB
  • (optional)disk_offering_id: UUID of the disk offering to derive the new size from
  • (optional)shrink: a boolean (0 or 1) value authorizing the volume to shrink if necessary; data may be lost--use with caution
examples
  1. /v1/accounts/FA3F8002-2F5D-11E2-8E5D-65DAE6D04373/volumes/2204e87c-fb2d-45a3-9d16-05a023428f6d
    
    {"size":20}
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: UUID identifying the job responsible for resizing the volume
examples
  1. {
      "job_id": "e75fd0f3-52ff-440d-ba75-1ce224d2d681"
    }
List volumes associated with this account matching the specified criteria. This resource also accepts the page and range (page, pagesize, begin, end, order_by,desc`) arguments of the list resource
method
GET
URL
/v1/accounts/{api_id}/volumes/search
query parameters
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes/search?query=size%3e%3d5000000000
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of volumes in this response
  • volumes: list of volumes
examples
  1. {
      "count": 2,
      "volumes": [
        {
          "account": "joe@schmoe.org",
          "created": "2012-10-23T13:28:25-0600",
          "destroyed": false,
          "deviceid": 0,
          "domain": "HostingCo",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "id": "5c4aeb74-6db2-4d65-86ff-2ad357efec35",
          "isextractable": true,
          "name": "ROOT-402",
          "serviceofferingdisplaytext": "Small Disk, 5 GB",
          "serviceofferingid": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
          "serviceofferingname": "Small",
          "size": 5368709120,
          "state": "Ready",
          "storage": "UTAH1-cluster0-vg2",
          "storagetype": "shared",
          "tags": [
          ],
          "type": "ROOT",
          "virtualmachineid": "f97aaec1-3d95-45ad-836e-8382e2f310f7",
          "vmdisplayname": "HostingCo Joe 1 70828",
          "vmname": "f97aaec1-3d95-45ad-836e-8382e2f310f7",
          "vmstate": "Running",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        },
        {
          "account": "joe@schmoe.org",
          "created": "2012-10-23T13:28:25-0600",
          "destroyed": false,
          "deviceid": 0,
          "domain": "HostingCo",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "id": "43b26b7f-f540-4bdf-b469-3cd8267b48d7",
          "isextractable": true,
          "name": "ROOT-403",
          "serviceofferingdisplaytext": "Small Disk, 5 GB",
          "serviceofferingid": "3ffd583c-1ab6-4a73-8087-af6102aae8ed",
          "serviceofferingname": "Small",
          "size": 5368709120,
          "state": "Ready",
          "storage": "UTAH1-cluster0-vg2",
          "storagetype": "shared",
          "tags": [
          ],
          "type": "ROOT",
          "virtualmachineid": "23d65fba-0995-4235-8dbd-d5cd86d1cefc",
          "vmdisplayname": "HostingCo Joe 2 70828",
          "vmname": "23d65fba-0995-4235-8dbd-d5cd86d1cefc",
          "vmstate": "Running",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
Destroy a volume associated with an account. If the volume is in ready state, a job will be created to destroy the volume. Otherwise the volume will be destroyed immediately.
method
DELETE
URL
/v1/accounts/{api_id}/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: id of the job responsible for destroying the volume
examples
  1. {
      "job_id": "2fa330e9-0ace-4162-9766-f041d438d645"
    }

other responses

status-code reason-phrase description
200 OK A brief message indicating success or failure.
Detach a volume from an instance. The volume is not destroyed.
method
DELETE
URL
/v1/accounts/{api_id}/instances/{instance_id}/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/instances/f97aaec1-3d95-45ad-836e-8382e2f310f7/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: UUID of the job responsible for detaching the volume
examples
  1. {
      "job_id": "2fa330e9-0ace-4162-9766-f041d438d645"
    }
Attach a volume to an instance.
method
PUT
URL
/v1/accounts/{api_id}/instances/{instance_id}/volumes/{volume_id}
query parameters
(none)
body parameters
(none)
examples
  1. PUT /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/instances/f97aaec1-3d95-45ad-836e-8382e2f310f7/volumes/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
200
reason-phrase
OK
body
  • job_id: UUID of the job responsible for attaching the volume
examples
  1. {
      "job_id": "2fa330e9-0ace-4162-9766-f041d438d645"
    }

A VPC (also known as 'datacenter' or 'virtual private cloud') enables you to route IP blocks to your networks.

Update a virtual private cloud (aka datacenter).
method
PATCH
URL
/v1/accounts/{api_id}/vpcs/{vpc_id}
query parameters
(none)
body parameters
  • (optional)name: name of the VPC
  • (optional)display_text: brief description of the VPC
examples
  1. PATCH /v1/accounts/EE47635E-39C7-11E2-BED9-1D5E3E42E918/vpcs/63d968ee-34ec-4bd6-9ba1-a8ad9769b415
    
    {"display_text":"new-name"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID of the new VPC
  • job_id: UUID identifying the job responsible for creating the VPC
examples
  1. {"job_id":"e60b0285-0a2f-4c54-8f6d-fa484cd9baa1"}
List routers by account.
method
GET
URL
/v1/accounts/{api_id}/routers
query parameters
  • (optional)vpc_id: limit the routers to those attached to this particular VPC
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/routers
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • routers: list of routers
examples
  1. {
      "account": "joe-user@48686.api-test",
      "created": "2014-01-03T15:37:29-0700",
      "dns1": "8.8.8.8",
      "dns2": "8.8.4.4",
      "domain": "WESE65FE",
      "domainid": "419b542f-a4c1-4887-a702-fd741eed3c71",
      "gateway": "69.27.171.129",
      "id": "6ee40871-e1af-4bce-8776-88f4841d54f2",
      "isredundantrouter": false,
      "jobid": "f465f841-c548-414f-b20e-f597f22461b4",
      "jobstatus": 0,
      "name": "r-15084-VM",
      "nic": [
        {
          "broadcasturi": "vlan://untagged",
          "gateway": "69.27.171.129",
          "id": "1e90deb8-796e-455d-91a3-4c34da6b72a2",
          "ipaddress": "69.27.171.170",
          "isdefault": true,
          "isolationuri": "vlan://untagged",
          "macaddress": "06:b3:88:00:00:3e",
          "netmask": "255.255.255.128",
          "networkid": "a4f7a454-b3c7-4cd6-b3f4-5a4b5556249e",
          "traffictype": "Public"
        }
      ],
      "publicip": "12.23.56.78",
      "publicmacaddress": "60:3b:88:5d:30:e3",
      "publicnetmask": "255.255.255.128",
      "publicnetworkid": "a4f7a454-b3c7-4cd6-b3f4-5a4b5556249e",
      "redundantstate": "UNKNOWN",
      "role": "VIRTUAL_ROUTER",
      "serviceofferingid": "eed57f22-0be8-4670-b6a6-29dc5754c2bd",
      "serviceofferingname": "System Offering For Software Router",
      "state": "Starting",
      "templateid": "17a94dcc-c936-4762-8ee5-50d36f487e4a",
      "vpcid": "030fe20b-49da-439f-b58e-a02fa2aef210",
      "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zonename": "US-UTAH1-TEST"
    }
Destroy a VPC associated with an account.
method
DELETE
URL
/v1/accounts/{api_id}/vpcs/{vpc_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpcs/27470ac7-08ee-44f7-9fc8-309115272970
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID of the job responsible for destroying the VPC
examples
  1. {"job_id":"76d8dd98-0636-4254-9c59-786f50eeddb3"}
List VPCs by account.
method
GET
URL
/v1/accounts/{api_id}/vpcs
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpcs
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • vpcs: list of vpcs
examples
  1. {
      "count": 1,
      "vpcs": [
        {
          "account": "biff@i.net",
          "cidr": "10.128.0.0/16",
          "displaytext": "api-test-48597",
          "domain": "HostingCo",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "id": "2672878b-cc62-4074-ab87-938e8447b7e2",
          "name": "api-test-vpc-48597",
          "network": [
          ],
          "networkdomain": "schmoe.org",
          "restartrequired": false,
          "service": [
            {
              "name": "Vpn",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "UserData",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dhcp",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dns",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "NetworkACL",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "PortForwarding",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "SourceNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Lb",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "StaticNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            }
          ],
          "state": "Enabled",
          "tags": [
          ],
          "vpcofferingid": "fe7aa774-4329-45e3-8e32-c19d6f6d4da9",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
Reboot a router.
method
POST
URL
/v1/accounts/{api_id}/routers/{router_id}/runstate
query parameters
(none)
body parameters
  • action: must be reboot
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/routers/b627b88e-9959-4703-b139-7df96e19e069/runstate
    
    {"action":"reboot"}
HTTP Response
status-code
200
reason-phrase
OK
body
  • message: a brief message indicating the result
examples
  1. {"message" : "router rebooted"}
Restart a VPC.
method
POST
URL
/v1/accounts/{api_id}/vpcs/{vpc_id}/runstate
query parameters
(none)
body parameters
  • action: must be restart
examples
  1. POST /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/vpcs/b627b88e-9959-4703-b139-7df96e19e069/runstate
    
    {"action":"restart"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: a UUID referencing the job responsible for changing the run-state of the VPC
examples
  1. {"job_id" : "b952b203-1c0f-4ec8-9c13-c0d28387269c"}
List VPCs associated with this account matching the specified criteria. This resource also accepts the page and range (page, pagesize, begin, end, order_by,desc`) arguments of the list resource
method
GET
URL
/v1/accounts/{api_id}/vpcs/search
query parameters
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpcs/search?query=cidr%3d10.128.0.0%2f16
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of VPCs in this response
  • vpcs: list of VPCs
examples
  1. {
      "count": 1,
      "vpcs": [
        {
          "account": "biff@i.net",
          "cidr": "10.128.0.0/16",
          "displaytext": "api-test-48597",
          "domain": "HostingCo",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "id": "2672878b-cc62-4074-ab87-938e8447b7e2",
          "name": "api-test-vpc-48597",
          "network": [
          ],
          "networkdomain": "schmoe.org",
          "restartrequired": false,
          "service": [
            {
              "name": "Vpn",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "UserData",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dhcp",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dns",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "NetworkACL",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "PortForwarding",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "SourceNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Lb",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "StaticNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            }
          ],
          "state": "Enabled",
          "tags": [
          ],
          "vpcofferingid": "fe7aa774-4329-45e3-8e32-c19d6f6d4da9",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
/v1/vpcs
List VPCs across all accounts.
This method is available only to admin accounts.
method
GET
URL
/v1/vpcs
query parameters
  • (optional)page: for results pagination, the page of results to return (first page = 1)
  • (optional)pagesize: for results pagination, the number of results per page
  • (optional)begin: beginning record number
  • (optional)end: ending record number
  • (optional)order_by: a field name to order the results by
  • (optional)desc: return the results in descending order
body parameters
(none)
examples
  1. GET /v1/vpcs
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of networks in this response
  • vpcs: list of vpcs
examples
  1. {
      "count": 1,
      "vpcs": [
        {
          "account": "biff@i.net",
          "cidr": "10.128.0.0/16",
          "displaytext": "api-test-48597",
          "domain": "HostingCo",
          "domainid": "7d018903-b7ca-495d-8139-16b704e4d982",
          "id": "2672878b-cc62-4074-ab87-938e8447b7e2",
          "name": "api-test-vpc-48597",
          "network": [
          ],
          "networkdomain": "schmoe.org",
          "restartrequired": false,
          "service": [
            {
              "name": "Vpn",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "UserData",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dhcp",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Dns",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "NetworkACL",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "PortForwarding",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "SourceNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "Lb",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            },
            {
              "name": "StaticNat",
              "provider": [
                {
                  "name": "VpcVirtualRouter"
                }
              ]
            }
          ],
          "state": "Enabled",
          "tags": [
          ],
          "vpcofferingid": "fe7aa774-4329-45e3-8e32-c19d6f6d4da9",
          "zoneid": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
          "zonename": "US-UTAH1-TEST"
        }
      ]
    }
Create a virtual private cloud (aka datacenter).
method
POST
URL
/v1/accounts/{api_id}/vpcs
query parameters
(none)
body parameters
  • name: name of the VPC
  • display_text: brief description of the VPC
  • zone_id: UUID of the zone to create the network in
  • cidr: the starting IP and size of network in CIDR notation (i.e., w.x.y.z/c)
  • network_domain: the domain for this VPC
  • vpc_offering_id: UUID of the VPC offering to derive the VPC from
examples
  1. POST /v1/accounts/EE47635E-39C7-11E2-BED9-1D5E3E42E918/vpcs
    
    {
      "cidr": "10.128.0.0/16",
      "display_text": "api-test-34003",
      "name": "api-test-vpc-34003",
      "network_domain": "schmoe.org",
      "vpc_offering_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415",
      "zone_id": "63d968ee-34ec-4bd6-9ba1-a8ad9769b415"
    }
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID of the new VPC
  • job_id: UUID identifying the job responsible for creating the VPC
examples
  1. {"job_id":"e60b0285-0a2f-4c54-8f6d-fa484cd9baa1","id":"2672878b-cc62-4074-ab87-938e8447b7e2"}

A site-to-site VPN enables you to establish a secure connection between a VPC and another router accessible via the Internet.

To create a VPN between a VPC and another router:

  1. create a VPN gateway for the VPC
  2. create a remote VPN gateway to represent the router
  3. create a VPN connection between the two gateways

Remove a remote VPN gateway.
method
DELETE
URL
/v1/accounts/{api_id}/remote_vpn_gateways/{vpn_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/remote_vpn_gateways/63d968ee-34ec-4bd6-9ba1-a8ad9769b415
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for removing the remote VPN gateway from the VPC
examples
  1. {"job_id":"63d968ee-34ec-4bd6-9ba1-a8ad9769b415"}
Remove a VPN connection.
method
DELETE
URL
/v1/accounts/{api_id}/vpn_connections/{vpn_connection_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_connections/63d968ee-34ec-4bd6-9ba1-a8ad9769b415
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for removing the VPN connection
examples
  1. {"job_id":"63d968ee-34ec-4bd6-9ba1-a8ad9769b415"}
List remote VPN gateways. Remote VPN gateways represent a remote router you want to create a VPN connection to from a VPC.
method
GET
URL
/v1/accounts/{api_id}/remote_vpn_gateways
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/remote_vpn_gateways
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of remote VPN gateways in this response
  • remote_vpn_gateways: list of remote VPN gateways
examples
  1. {
      "count": 1,
      "remote_vpn_gateways": [
        {
          "account": "joe-api-user@hostingco.com",
          "cidr_list": "10.100.0.0/24",
          "dead_peer_detection": true,
          "auth_type": "GOVO73ME",
          "domain_id": "c552a913-d167-44a0-b7fc-c63f647689c5",
          "esp_lifetime": 300,
          "esp_policy": "3des-md5",
          "gateway": "21.43.65.87",
          "id": "80c24deb-95b0-401e-861f-5daebbe91e2b",
          "ike_lifetime": 600,
          "ike_policy": "3des-md5",
          "ipsec_psk": "secret_secret",
          "name": "test remote vpn gateway 90758"
        }
      ]
    }
List all VPN connections.
method
GET
URL
/v1/accounts/{api_id}/vpn_connections
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_connections
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of VPN connections in this response
  • vpn_connections: a list of VPN connections
examples
  1. {
      "count": 1,
      "vpn_connections": [
        {
          "account": "joe-api-user@hostinco.com",
          "auth_type": "GOVO73ME",
          "cidr_list": "10.100.0.0/24",
          "created": "2013-05-16T17:40:33-0600",
          "dead_peer_detection": false,
          "domain_id": "c552a913-d167-44a0-b7fc-c63f647689c5",
          "esp_lifetime": 300,
          "esp_policy": "3des-md5",
          "gateway": "23.45.67.89",
          "id": "f0ad6d4a-d398-4487-8bab-08510baa5f7d",
          "ike_lifetime": 600,
          "ike_policy": "3des-md5",
          "ipsec_psk": "secret_secret",
          "public_ip": "12.34.56.78",
          "remote_vpn_gateway_id": "80c24deb-95b0-401e-861f-5daebbe91e2b",
          "state": "Connected",
          "vpn_gateway_id": "dada4781-c4f9-4c56-91bb-9d1524167bc9"
        }
      ]
    }
Create a VPN connection between a VPC's VPN gateway and a remote VPN gateway.
method
POST
URL
/v1/accounts/{api_id}/vpn_connections
query parameters
(none)
body parameters
  • remote_vpn_gateway_id: ID of the remote VPN gateway
  • vpn_gateway_id: ID of the VPC's VPN gateway
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_connections
    
    {"remote_vpn_gateway_id":"f0ad6d4a-d398-4487-8bab-08510baa5f7d","vpn_gateway_id":"c552a913-d167-44a0-b7fc-c63f647689c5"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • id: UUID identifying the new VPN connection
  • job_id: UUID identifying the job responsible for creating the VPN connection
examples
  1. {"id":"0fa6d4ad-d398-4487-8bab-08510baa5f7d","job_id":"74b62a5b-44f5-434b-90a3-340a4a1e8dc9"}
Create a VPN gateway for a VPC. A VPC may have at most one VPN gateway.
method
POST
URL
/v1/accounts/{api_id}/vpn_gateways
query parameters
(none)
body parameters
  • vpc_id: ID of the VPC to create a VPN gateway for
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_gateways
    
    {"vpc_id":"817b1cd2-da17-4ab9-9fd0-58df5ec72976"}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for creating the VPN gateway
examples
  1. {"job_id":"ad7da481-c4f9-4c56-91bb-9d1524167bc9"}
Remove a VPN gateway.
method
DELETE
URL
/v1/accounts/{api_id}/vpn_gateways/{vpn_id}
query parameters
(none)
body parameters
(none)
examples
  1. DELETE /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_gateways/63d968ee-34ec-4bd6-9ba1-a8ad9769b415
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for removing the VPN gateway from the VPC
examples
  1. {"job_id":"74b62a5b-44f5-434b-90a3-340a4a1e8dc9"}
Create a remote VPN gateway. Remote VPN gateways represent a remote route you wish to establish a VPN connection to with a VPC.
method
POST
URL
/v1/accounts/{api_id}/remote_vpn_gateways
query parameters
(none)
body parameters
  • name: name of the remote VPN gateway
  • gateway: the public IP address of the remote gateway (the router which the VPN connection should attempt to connect to)
  • cidr_list: a list of guest remote subnets. Enter a CIDR or a comma-separated list of CIDRs. Ensure that a guest CIDR list is not overlapped with the VPC's CIDR, or another guest CIDR. The CIDR must be RFC1918-compliant.
  • ipsec_psk: IPsec preshared key. Preshared keying is a method where the endpoints of the VPN share a secret key. This key value is used to authenticate the customer gateway and the VPC VPN gateway to each other.
  • (optional)ike_policy: a concatenation of ike_encryption, ike_hash and ike_dh. If specified, you do not need to supply those fields
  • (optional)ike_encryption: UUID of the VPC this network belongs to
  • (optional)ike_hash: The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5
  • (optional)ike_dh: A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The 1536-bit Diffie-Hellman group is used within IKE to establish session keys. The supported options are None, Group-5 (1536-bit) and Group-2 (1024-bit).
  • (optional)ike_lifetime: The phase-1 lifetime of the security association in seconds. Default is 86400 seconds (1 day). Whenever the time expires, a new phase-1 exchange is performed.
  • (optional)esp_policy: a concatenation of esp_encryption, esp_hash, and perfect_forward_secrecy. If specified, you do not need to supply those fields
  • (optional)esp_encryption: Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
  • (optional)esp_hash: Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
  • (optional)perfect_forward_secrecy: Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. This property enforces a new Diffie-Hellman key exchange. It provides the keying material that has greater key material life and thereby greater resistance to cryptographic attacks. The available options are None, Group-5 (1536-bit) and Group-2 (1024-bit). The security of the key exchanges increase as the DH groups grow larger, as does the time of the exchanges.
  • (optional)esp_lifetime: The phase-2 lifetime of the security association in seconds. Default is 3600 seconds (1 hour). Whenever the value is exceeded, a re-key is initiated to provide a new IPsec encryption and authentication session keys.
  • (optional)dead_peer_detection: A method to detect an unavailable Internet Key Exchange (IKE) peer. Select this option if you want the virtual router to query the liveliness of its IKE peer at regular intervals. It's recommended to have the same configuration of DPD on both side of VPN connection.
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/remote_vpn_gateway
    
    {"name":"test remote vpn gateway","gateway":"199.58.198.234","cidr_list":"10.100.0.0/24","esp_policy":"3des-md5;modp1536","ike_policy":"3des-md5","ipsec_psk":"secret_secret","ike_lifetime":600,"esp_lifetime":300,"dead_peer_detection":true}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for creating the remote VPN gateway
examples
  1. {"job_id":"9b989d77-09cd-4c5b-8d18-cea34bdc0b31"}
List all VPN gateways.
method
GET
URL
/v1/accounts/{api_id}/vpn_gateways
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_gateways
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: number of VPN gateways in this response
  • vpn_gateways: a list of VPN gateways
examples
  1. {
      "count": 1,
      "vpn_gateways": [
        {
          "account": "joe-api-user@hostingco.com",
          "auth_type": "GOVO73ME",
          "id": "dada4781-c4f9-4c56-91bb-9d1524167bc9",
          "public_ip": "12.34.56.78",
          "vpc_id": "dada4781-c4f9-4c56-91bb-9d1524167bc9"
        }
      ]
    }
Update a remote VPN gateway settings. This behaves almost identically to creating a new remote VPN gateway.
method
PATCH
URL
/v1/accounts/{api_id}/remote_vpn_gateways/{vpn_id}
query parameters
(none)
body parameters
  • (optional)name: name of the remote VPN gateway
  • (optional)gateway: the public IP address of the remote gateway (the router which the VPN connection should attempt to connect to)
  • (optional)cidr_list: a list of guest remote subnets. Enter a CIDR or a comma-separated list of CIDRs. Ensure that a guest CIDR list is not overlapped with the VPC's CIDR, or another guest CIDR. The CIDR must be RFC1918-compliant.
  • (optional)ipsec_psk: IPsec preshared key. Preshared keying is a method where the endpoints of the VPN share a secret key. This key value is used to authenticate the customer gateway and the VPC VPN gateway to each other.
  • (optional)ike_policy: a concatenation of ike_encryption, ike_hash and ike_dh. If specified, you do not need to supply those fields
  • (optional)ike_encryption: The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. Authentication is accomplished through the Preshared Keys.
  • (optional)ike_hash: The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5
  • (optional)ike_dh: A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The 1536-bit Diffie-Hellman group is used within IKE to establish session keys. The supported options are None, Group-5 (1536-bit) and Group-2 (1024-bit).
  • (optional)ike_lifetime: The phase-1 lifetime of the security association in seconds. Default is 86400 seconds (1 day). Whenever the time expires, a new phase-1 exchange is performed.
  • (optional)esp_policy: a concatenation of esp_encryption, esp_hash, and perfect_forward_secrecy. If specified, you do not need to supply those fields
  • (optional)esp_encryption: Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
  • (optional)esp_hash: Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
  • (optional)perfect_forward_secrecy: Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. This property enforces a new Diffie-Hellman key exchange. It provides the keying material that has greater key material life and thereby greater resistance to cryptographic attacks. The available options are None, Group-5 (1536-bit) and Group-2 (1024-bit). The security of the key exchanges increase as the DH groups grow larger, as does the time of the exchanges.
  • (optional)esp_lifetime: The phase-2 lifetime of the security association in seconds. Default is 3600 seconds (1 hour). Whenever the value is exceeded, a re-key is initiated to provide a new IPsec encryption and authentication session keys.
  • (optional)dead_peer_detection: A method to detect an unavailable Internet Key Exchange (IKE) peer. Select this option if you want the virtual router to query the liveliness of its IKE peer at regular intervals. It's recommended to have the same configuration of DPD on both side of VPN connection.
examples
  1. PATCH /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/remote_vpn_gateway
    
    {"name":"new VPN","dead_peer_detection":false}
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for creating the remote VPN gateway
examples
  1. {"job_id":"9b989d77-09cd-4c5b-8d18-cea34bdc0b31"}
Reset a VPN connection.
method
POST
URL
/v1/accounts/{api_id}/vpn_connections/{vpn_connection_id}/reset
query parameters
(none)
body parameters
(none)
examples
  1. POST /v1/accounts/E3D47124-1D47-11E2-9E8D-55A9E6D04373/vpn_connections/63d968ee-34ec-4bd6-9ba1-a8ad9769b415/reset
HTTP Response
status-code
202
reason-phrase
Accepted
body
  • job_id: UUID identifying the job responsible for resetting the VPN connection
examples
  1. {"job_id":"63d968ee-34ec-4bd6-9ba1-a8ad9769b415"}

Widgets are data elements that act as statistics for components of your system. They are typically published to graphs or charts

Get all widget data for datacenter component. This could be the UUID of a VM, a volume: whatever you are generating statistics for.
method
GET
URL
/v1/accounts/{api_id}/widgets/{id}
query parameters
(none)
body parameters
(none)
examples
  1. GET /v1/accounts/D5F6E0B4-CF8B-11E1-A175-422A1D9586CD/widgets/91234ABD-1251-1239-AB92C18521412
HTTP Response
status-code
200
reason-phrase
OK
body
  • count: The number of widgets returned
  • widgets: An array of objects, one for each widget
examples
  1. { 
    	"count" : "1", 
    	"widgets" : [ {
    		"widget_type":"line",
    		"count":6,
    		"timestamp":"1368742847",
    		"name":"CPU %",
    		"values":[[{"value":10,"name":"system"},{"value":61,"name":"user"},{"value":29,"name":"idle"}],[{"value":16,"name":"system"},{"value":79,"name":"user"},{"value":5,"name":"idle"}],[{"value":44,"name":"system"},{"value":39,"name":"user"},{"value":17,"name":"idle"}],[{"value":21,"name":"system"},{"value":73,"name":"user"},{"value":6,"name":"idle"}],[{"value":9,"name":"system"},{"value":67,"name":"user"},{"value":24,"name":"idle"}]],
    		"state":"ON"
    	} ] 
    }
Documentation last built on Tue, 28 Oct 2014 15:50:23 MDT