Welcome to CloudSigma API documentation!

Release Notes

Silicon Release

Date Released: 2015-03-26

  • Allow resources to be shared and accessed between accounts Access Control Lists
  • Allow SSH keys to be imported and managed by the cloud and attached to servers SSH key pairs

Aluminium Release

Date Released: 2014-11-26

Magnesium Release

Date Released: 2014-09-08

  • Various stability and performance improvements.
  • Better explanation of storage types and explanation of default network restrictions.
  • Support for Juju simple streams.
  • Now it is possible to specify size for drive clone call, so that the new drive is bigger than the original.

Sodium Release

Date Released: 2014-05-20

Neon Release

Date Released: 2014-01-29

  • New drive parameter allowing changing the storage type.
  • Most API calls now support standardised filtering.
  • Asnychronous operations now are exposed via a jobs API.
  • Cloning drives and servers can now change the destinations’ names to differentiate between source and destination.
  • Added audit log documentation.

Fluorine Release

Date Released: 2013-12-10

  • Notification preferences functionality allowing multiple recipients. See Notification contacts.
  • Server runtime details now report I/O statistics for the attached drives in the drives/runtime/io object from the response. See Server Runtime and Server Details.
  • Capabilities call now includes the count allowed snapshots in the snapshots object from the response. See Capabilities.
  • API now returns all numbers as integer literals instead of string literals

Date Released: 2013-11-18

  • Global server context is a place to hold server context information, which is common to all user’s servers. See Global context.
  • A call for querying the account current usage Current usage.
  • Clarifications regarding drive resize Resizing (Update or Fail).
  • Section describing allowed names Permitted characters.
  • Fixed documentation of response status codes Servers / VMs, Snapshots, Cloning.
  • More flexible call for subscriptions auto-renew Autorenewing.
  • Login call returns a json object with the user UUID
  • Server firewall updates are applied every 30 seconds, as opposed to previous versions, when they were applied immediately on change.
  • We now support bursting on IP resources. After the IP subscription has expired, all servers that have the IP attached as static will continue to operate until the user runs out of money. All other servers, will block outgoing traffic originating from that IP - i.e. the IP will stop working on servers on which the user configured it manually.
  • Manually configuring an IP, given to the user via DHCP, to another server owned by the same user, is now prohibited.
  • Buying a new IP resource, will make the same available on all of the user’s servers without power-cycling them. The user can manually configure it on his public network interfaces and it will JUST work.

Oxygen Release

Date Released: 2013-10-07

  • Server context can be updated for a running server, by updating server or drive definition. See below.
  • It is possible to update name, meta, and tags on a running server or a drive mounted on a running server. See server edit and drive edit.
  • Added an action to update a drive, which will fail to update if the drive is mounted on a running serve. It is called resize because size is the only drive attribute which cannot be changed on a drive mounted on a running server. See Resizing (Update or Fail).
  • It is possible to create snapshots for a drive, and later clone the snapshot to a full drive. This makes it possible to restore from a point-in-time version of the snapshot. See Snapshots.
  • Added documentation for uploading drive images though simple HTTP POST. See Upload or Download Drive Images.

Nitrogen Release

Date Released: 2013-08-01

Carbon Release

Date Released: 2013-07-08

Date Released: 2013-05-22

  • Firewall functionality. The user can attach firewall policies to NICs. Each policy may have multiple rules for filtering traffic. See My Network -> policies in WebApp or check Firewall Policies section for API documentation.
  • Web VNC. Users can open VNC sessions directly in WebApp. The browser needs to support websockets. To open a Web VNC session go to server properties on a running server, open VNC tunnel, click on the VNC button and choose whether to open the session in the same browser window or in a new browser window/tab.
  • The old hdd resource is renamed to dssd (Distributed SSD). This is reflected in all areas of the API. The subscriptions API still accepts hdd as an alias, but returns dssd. The capabilities API returns dssd.
  • OAuth support for single sign-on in WebApp. Users can authenticate in WebApp with an existing account from Google, Twitter, LinkedIn, or Facebook. See Profile -> settings to connect you CloudSigma account with an existing OAuth provider.
  • Drive images licenses. Servers running with drives from drives library, which contain software that requires a license need a subscriptions in order to be started. Check Subscriptions -> Purchase -> Software licenses in WebApp to list or purchase software licenses. See Subscriptions for API docs on purchasing licenses, and Licenses list for listing purchased licenses.
  • NIC runtime information, when listing running servers, now is also added to the NIC definition, so that it is easier to access NIC runtime info from the NIC object itself rather than the server runtime. The old NIC runtime information in the server runtime is retained for backward compatibility.
  • Drives attached to stopped servers can now be deleted.

Boron Release

Date Released: 2013-03-19

API HTTP response status code changes

  • HTTP status for PUT (update) requests is changed from 202 Accepted to 200 OK.
  • HTTP status for creation of objects is changed from 202 Accepted to 201 Created. This affects Subscription, Servers, Drives, and Tags creation.
  • HTTP status for Subscriptions Calcultaor is changed from 202 Accepted to 200 OK.
  • HTTP status for actions with asynchronous results is changed from 200 to 202. This affects action calls on Servers (start, stop, clone, open_vnc, close_vnc) and Drives (clone).

Berilium Release

Date Released: 2013-01-16

General Notes

Introduction

API endpoint

Given a server running the CloudSigma API it will be available on the following base URL e.g.:

https://{loc}.cloudsigma.com/api/2.0/

Where {loc} is a subdomain for a specific location. In the rest of the documentation the URL’s will be given relative to that base.

Currently the following CloudSigma location endpoints are available:

Location Location Code API Endpoint
Honolulu, United States HNL https://hnl.cloudsigma.com/api/2.0/
San Jose, United States SJC https://sjc.cloudsigma.com/api/2.0/
Washington DC, United States WDC https://wdc.cloudsigma.com/api/2.0/
Zurich, Switzerland ZRH https://zrh.cloudsigma.com/api/2.0/

See also Locations API call for an automated way to get all currently available locations.

API Versions

The API version is embedded into the URL. The currently active one is ‘2.0’, e.g.

https://lvs.cloudsigma.com/api/2.0/

General URL Format

API URLs have the following general format:

https://{api_endpoint}/api/{api_version}/{resource}/{object_id}/action/?{get_request_parameters}

Here is a list of the possible URL formats relative to the base url (https://{api_endpoint}/api/{api_version}):

/{resource}/
These URLs usually point to a list of resources like /servers/ or /drives/. It may also point to a single resource object such as /profile/.
/{resource}/{object_id}/
These URLs point to a single resource from a list of resources, for example a single server URL can be: /servers/6e5ceaaa-0cf8-417a-bf47-53e56d4fcaaa/
/{resource}/{object_id}/action/?do={action_name}
Some objects have actions. The name of the action is specified in the ‘do=’ GET parameter. For example a server object has a start action which is called on the following URL: /servers/6e5ceaaa-0cf8-417a-bf47-53e56d4fcaaa/action/?do=start

Authentication

The API supports the following authentication methods :

  • HTTP Basic
  • HTTP Digest
  • Cookie based authentication for web/browser based clients.

HTTP Basic Auth

HTTP Basic Authentication is done with the Authorization header. The value of the header is Basic base64_encode({user email}:{password}). For example a user with email user.email@domain.tld with password pass123 results in a value of user.email@domain.tld:pass123, which when encoded in Base64 would result in the following header:

Authorization: Basic dXNlci5lbWFpbEBkb21haW4udGxkOnBhc3MxMjM=

See RFC 2617 for more detailed discussion of HTTP Basic Authentication.

Digest Access Authentication

In order to use digest authentication, clients should make the request without any authentication, which will result in a 401 Unauthorized response. The response will contain a challenge in the WWW-Authenticate header which looks like:

WWW-Authenticate: Digest nonce="1363185031.81:FCF2:443b657bfd1a7340a0841c704d93a579", realm="users", algorithm="MD5", opaque="d7d89a75f4f6e3044626c6c251456e6b401401e7", qop="auth"

Three hashes (we call them HA1 and HA2 and RESPONSE in the example) need to be calculated to generate the response to the challenge and authenticate. The API uses md5 hashing algorithm (algorithm=”MD5”) and “auth” quality of protection (qup=”auth”):

HA1 = MD5({username}:{realm}:{password})
HA2 = MD5({method}:{uri})
RESPONSE = MD5(HA1:{nonce}:{nc}:{cnonce}:{qop}:HA2)

The values for realm, nonce, and qop are given in the challenge header WWW-Authenticate. The client has to provide the username, password, cnonce, and nc. cnonce or client nonce is a random value generated by the client and nc or nonce counter is a hexadecimal counter which should be incremented with each subsequent request.

The client should send an Authorization header which contains all the values from the WWW-Authenticate response header, together with the following values username, uri, cnonce, nc, and response, which contains the calculated RESPONSE hash.

In the example above a user with an email user.email@domain.tld, and with password pass123 may send the following Authorization header in the next request:

Authorization: Digest username="user.email@domain.tld", realm="users", nonce="1363188235.48:54A3:135f43a8227a1ca54c91da95b0111802", uri="/api/2.0/servers/", cnonce="MDI4Nzcx", nc=00000001, qop=auth, response="06238b01fabaeea8d7923c502a037bb5", opaque="5f0604df80b0c2d09330e802ed47ba5288e5440c", algorithm="MD5"

For more information on Digest access authentication see RFC 2617 or the wikipedia article on Digest Access Authentication.

Data Format (Content Types)

The API supports both the JSON and XML data formats. By default JSON is used. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header. The response contains a Content-Type header specifying the data format returned. The following table summarizes the request and response headers concerning data format:

Header name Specified in Request Specified in Response
Content-Type applies to request body applies to response body
Accept applies to response body not applicable

The values which can be used for data format headers are:

Encoding Header value
JSON application/json or */*
XML application/xml

You can also use a URI parameter ?format=json or ?format=xml to specify the content type of the response, when sending a GET request. This is useful for querying the API manually (via web browser) and should not be used when sending requests programmatically. In case both the Content-Type and URI parameter are used, the URI parameter has precedence. In case there are conflicting URI parameters, the last specified parameter takes precedence. In case of both application/json and application/xml are specified in an Accept header, JSON is returned. If the Accept header contains both */* and application/xml or application/json, the */* is ignored and the more specific content type is used.

Content Compression

Response body data may be compressed with gzip compression in order to minimize the amount of data being transferred over the wire. To request response body compression use the Accept-Encoding header on the request. The response will contain a Content-Encoding header specifying the gzip compression algorithm.

Type Header Value
Request Accept-Encoding gzip
Response Content-Encoding gzip

Request Methods

The API uses different HTTP request methods for different types of operations. In order to list the available HTTP request methods on a URL use an OPTIONS method request on it.

Example:

Request:

OPTIONS /2.0/servers/ HTTP/1.1

Response:

HTTP/1.0 200 OK

GET,PUT,DELETE,POST

The following table specifies that meanings of HTTP methods, which can be used by API clients:

GET:Retrieve a resource or a list of resources.
PUT:Update an existing resource. PUT implies an idempotent action (a request, which when repeated with the same arguments will always yield the same result).
POST:Create a resources, or do an action on an object (like do start action on a server). POST is used for non-idempotent request (requests, which may have different results if repeated multiple times, even if the input data is the same).
DELETE:Delete a resource.
OPTIONS:Get a comma separated list of the supported HTTP methods on a URL.

Response Status Codes

The API uses the standard HTTP status code classes, where a code from 200 to 299 signifies success. Request errors have status codes between 400 and 499, and server side errors have codes between 500 and 599. The following status codes are returned by the API:

Success Status Codes:

200:OK. Successful request.
201:Object Created. This request is used for calls which create new objects, such as create drive or create server. The Location response header contains the URI of the newly created object.
202:Accepted. This header is used for long-running or asynchronous operations such as starting a server or cloning a drive. The header also implies that the request the request may not succeed and may be canceled
204:No Content. The request was successful an there is no content in response body. This status is used for successful DELETE requests. Clients should be aware to not parse the body as it is empty and is not a valid JSON or XML document.

API errors usally contain a body which describes the error. Check the Errors section for explanation of the error message format.

Request Error Status Codes:

400:Bad Request. This status means that there is an error in the request. The request error may be data format error (non-valid JSON or XML) or an invalid value.
401:Unauthorized. The provided credentials are incorrect or missing. This response status is normal part of digest authentication in which case, the response will contain WWW-Authenticate header with an authentication challenge.
402:Payment Required. This error means there are not enough funds in the account to complete action. It occurs when trying to buy subscription without having enough funds in the account, or when trying to start a server without having enough funds for burst usage of 5 days.
403:Forbidden. The provided credentials are correct but the user is not permitted to complete the action. This status is used for either “permission” or “operation not allowed” error.
404:Not Found. The requested object does not exist. This error occurs when requesting non-existing resource. The resource may have never been created, or it may be deleted.
405:Method Not Allowed. This error occurs, when using incorrect HTTP method on an URL. For example DELETE requests are not allowed on /profile/ URL, and will return a 405 status.
406:Not Acceptable. This error occurs when the content type requested through the Accept header is not supported by the API. The content types supported by the API are application/json, application/xml, and */*, which defaults to application/json. If the Accept header of the request does not contain any of this content types, a 406 status will be returned.

System Error Status Code

500:Internal Server Error. This status means a system error has occurred. Please contact support if you encounter such an error.
503:Service Unavailable. This status means that the system temporarily cannot fulfil request. This status is returned for concurrent updates, when the client makes multiple concurrent requests which try to update the same values, or when the system is out of capacity.

Rate Limits

The API server needs to impose call-rate limits to protect the infrastructure from being maliciously overloaded.

Verb URI RegEx Limit
POST .* 10000 / min
POST ^/servers/ 10000 / min
PUT .* 10000 / min
GET .* 10000 / min
DELETE .* 1000 / min

Note: these limits may change in future

Permitted characters

The API accepts Unicode characters, with the recommended charset being UTF-8. The only special case is \0, which terminates the string.

Filtering

The API allows filtering of returned resources through GET parameters. Specific filtering options are listed in the schema. There are two types of filters:

exact:Matches the exact value of the field
contains:Matches, case insensitive, a substring of the value.

The semantics of the filters are as follows:

AND:

Separate GET parameters are ANDed together:

Example:

?name=test&tag__name=test_tag

It will return resources that match: (name = test) AND (has a tag with name = test_tag)

Same filter applied twice is still ANDed:

Example:

?tag__name=test_tag1&tag__name=test_tag2

It will return resources that match: (has a tag with name = test_tag1) AND (has a tag with name = test_tag2)

OR:

Within one GET parameter, values are split by comma and ORed together:

Example:

?name=name1,name2

It will return resources that match (name = name1) OR (name = name2)

Commas can be escaped by a single backslash and they will be not be used to split and backslashes that precede a comma can be escaped in order to keep allow splitting by commas:

Example:

?name=name\,long\\,name2

It will return resources that match (name = name,long\) OR (name = name2)

Note

OR has a higher priority than AND.

Example:

?name=name1,name2&tag__name=test_tag

It will return resources that match ((name = name1) OR (name = name2)) AND (has a tag with name = test_tag)

Locations

Locations call provides a list of the currently available CloudSigma locations, and information on specific urls, such as the websockets and upload urls.

GET /locations/

Example request:

GET /api/2.0/locations/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "alternative_frontend_url": "https://wdc.cloudsigma.com/ui/",
            "api_endpoint": "https://wdc.cloudsigma.com/api/2.0/",
            "country_code": "US",
            "default_frontend_signup_url": "https://wdc.cloudsigma.com/ui/",
            "default_frontend_url": "https://wdc.cloudsigma.com/ui/",
            "display_name": "Washington DC, United States",
            "documentation_url": "https://cloudsigma-docs.readthedocs.org/en/2.11/",
            "id": "WDC",
            "upload_url": "https://direct.wdc.cloudsigma.com/api/2.0/",
            "websocket_url": "wss://direct.wdc.cloudsigma.com/websocket"
        },
        {
            "alternative_frontend_url": "https://hnl.cloudsigma.com/ui/",
            "api_endpoint": "https://hnl.cloudsigma.com/api/2.0/",
            "country_code": "US",
            "default_frontend_signup_url": "https://hnl.cloudsigma.com/ui/",
            "default_frontend_url": "https://hnl.cloudsigma.com/ui/",
            "display_name": "Honolulu, United States",
            "documentation_url": "https://cloudsigma-docs.readthedocs.org/en/2.11/",
            "id": "HNL",
            "upload_url": "https://direct.hnl.cloudsigma.com/api/2.0/",
            "websocket_url": "wss://direct.hnl.cloudsigma.com/websocket"
        },
        {
            "alternative_frontend_url": "https://sjc.cloudsigma.com/ui/",
            "api_endpoint": "https://sjc.cloudsigma.com/api/2.0/",
            "country_code": "US",
            "default_frontend_signup_url": "https://sjc.cloudsigma.com/ui/",
            "default_frontend_url": "https://sjc.cloudsigma.com/ui/",
            "display_name": "San Jose, United States",
            "documentation_url": "https://cloudsigma-docs.readthedocs.org/en/2.11/",
            "id": "SJC",
            "upload_url": "https://direct.sjc.cloudsigma.com/api/2.0/",
            "websocket_url": "wss://direct.sjc.cloudsigma.com/websocket"
        },
        {
            "alternative_frontend_url": "https://zrh.cloudsigma.com/ui/",
            "api_endpoint": "https://zrh.cloudsigma.com/api/2.0/",
            "country_code": "CH",
            "default_frontend_signup_url": "https://zrh.cloudsigma.com/ui/",
            "default_frontend_url": "https://zrh.cloudsigma.com/ui/",
            "display_name": "Zurich, Switzerland",
            "documentation_url": "https://cloudsigma-docs.readthedocs.org/en/2.11/",
            "id": "ZRH",
            "upload_url": "https://direct.zrh.cloudsigma.com/api/2.0/",
            "websocket_url": "wss://direct.zrh.cloudsigma.com/websocket"
        }
    ]
}

Errors

Format

When one or more errors occur, they are returned to the client in an object with three fields:

  • error_message: A description of the error that occurred.
  • error_point: The point at which the error occurred. Always present, but can sometimes be null.

Types

The types of errors:

  • validation: An error occurred while validating the submitted data. If the error is related to a particular field, it will set the error_point.
  • notexist: The object you are trying to access does not exist.
  • backend: There was a problem completing the request on the backend. Please contact the support department.
  • permission: You do not have permission to complete the operation. May set the error_point.
  • database: There was a database error.
  • concurrency: There was a concurrency error caused by two simultaneous conflicting operations (i.e. trying to start and delete a server at the same time). The operation should be retried.
  • billing: There was a billing problem.
  • payment: There was a problem processing your payment.

Example

POST /subscriptions/

Example request:

{
    "amount": "1",
    "from_time": "2012-03-28T14:10:15.948157",
    "period": "2 weeks"
}

Example response:

[
    {
        "error_message": "This field is required",
        "error_point": "resource",
        "error_type": "validation"
    }
]

Capabilities

Allowed HTTP methods

Method Description
GET get the capabilities object

Note

See RFC 2616 for more details on HTTP methods semantics

The capabilities API call is used to gather all the basic, sensible limits of the API, to prevent applying static limits inside the client application.

Bare in mind, that these capabilities are dynamic - they are based on the cloud usage, location, etc. For example a location might not support lssd, but support magnetic disk option, or vise versa. If a feature is not supported or is disabled, it will disappear from the result of this call. Most entries are obvious limits on the guest or drive properties.

hosts:

A list of available host types and their limitations.

cpu_per_smp:This gives a range of valid cpu values, per smp, for the given host type. For example, for AMD hosts, one CPU must be between 1000 and 2500MHz: a guest 2000MHz cpu and 2 smp has 1000MHz per smp and is valid, but a guest with 8000MHz cpu and 2 smp has a 4000MHz per smp is not.
hypervisors:A list of hypervisors and which hosts they are available on. More details on the hosts can be found in the in the hosts entry.
drives:A list of available drive types and their limitations. The values in max_size and min_size are deprecated and are identical to the nested ones in size.
snapshots:Information about the current and maximum number of snapshots allowed for the account. These are global, not per drive.
servers:This entry is deprecated and contains the same values for amd hosts.
GET /capabilities/
statuscode 200:no error

Example request:

GET /api/2.0/capabilities/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Response:

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

{
    "drives": {
        "dssd": {
            "max_size": 4971194891468,
            "min_size": 536870912,
            "size": {
                "max": 4971194891468,
                "min": 536870912
            }
        }
    },
    "hosts": {
        "amd": {
            "cpu": {
                "max": 40000,
                "min": 250
            },
            "cpu_per_smp": {
                "max": 2400,
                "min": 1000
            },
            "mem": {
                "max": 68719476736,
                "min": 268435456
            },
            "smp": {
                "max": 24,
                "min": 1
            }
        },
        "intel": {
            "cpu": {
                "max": 40000,
                "min": 250
            },
            "cpu_per_smp": {
                "max": 2400,
                "min": 1000
            },
            "mem": {
                "max": 68719476736,
                "min": 268435456
            },
            "smp": {
                "max": 48,
                "min": 1
            }
        }
    },
    "hypervisors": {
        "kvm": [
            "amd"
        ]
    },
    "servers": {
        "cpu": {
            "max": 40000,
            "min": 250
        },
        "cpu_per_smp": {
            "max": 2400,
            "min": 1000
        },
        "mem": {
            "max": 68719476736,
            "min": 268435456
        },
        "smp": {
            "max": 24,
            "min": 1
        }
    },
    "snapshots": {
        "current": 0,
        "max": 600
    }
}

Clone naming

When cloning drives or whole servers the paramater for the name of the cloned entity could be omitted. In that scenario clone naming strategy based on the profile settings is being invoked.

Clone naming strategies are kept on clone_naming property in the user profile object. Possible values for it:

  • NONE do not append anything to the cloned drive’s name. [default]
  • COUNTER appends a number at the end of the name or increase it in case there is a number already.
  • DATE appends the current date or try to update it in case there is one already.
  • TIMESTAMP appends the current timestamp or try to update it in case there is one already.

If the date/timestamp at the end is already up-to-date the clone naming strategy will fallback to COUNTER without stripping the date/timestamp before.

Example

Let’s say we have a drive named “test_drive_x” and we’re going to clone it. First we want to check out how the counter strategy is working and we’re going to set the clone_naming property to “COUNTER”.

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Example response:

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

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now we could clone the drive without bothering to make up a new name for it:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/3564c1c2-c498-40d8-b063-aa173e2ec0c5/",
                    "uuid": "3564c1c2-c498-40d8-b063-aa173e2ec0c5"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_x_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/86164dec-fe21-4590-b2d7-a5733c38b24f/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "86164dec-fe21-4590-b2d7-a5733c38b24f"
        }
    ]
}

Done. Our new drive is named “test_drive_x_1”. If you have never changed the clone_naming property it will be set to “COUNTER” by default. Let’s see how the other two strategies are working.

Starting with “DATE”... (responses below here are stripped for better readability)

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "DATE",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now cloning:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "name": "test_drive_x-2014-06-05"
}

Similary with “TIMESTAMP”...

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "",
    "api_https_only": false,
    "autotopup_amount": "200.0000000000000000",
    "autotopup_threshold": "200.0000000000000000",
    "bank_reference": "jdoe123",
    "clone_naming": "TIMESTAMP",
    "company": "",
    "country": "US",
    "currency": "USD",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "invoicing": false,
    "key_auth": false,
    "language": "en_US",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "",
    "nickname": "",
    "phone": "",
    "postcode": "",
    "reseller": "",
    "signup_time": "2013-11-04T11:30:20.860838+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Great. And now cloning:

Example request:

POST /api/2.0/drives/1455c968-3477-4504-a93d-d0a7dc961f00/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "name": "test_drive_x-2014-06-05 09:45:56"
}

Drives

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /drives/

Gets the list of drives to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request 1 - default list:

GET /api/2.0/drives/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response 1 - default list:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "status": "unmounted",
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "status": "unmounted",
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "status": "unmounted",
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "status": "unmounted",
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "status": "unmounted",
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

Example request 2 - just uuid and status fields:

GET /api/2.0/drives/?fields=uuid,status&limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response 2 - just uuid and status fields:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "status": "unmounted",
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "status": "unmounted",
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "status": "unmounted",
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "status": "unmounted",
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "status": "unmounted",
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

Detailed listing

GET /drives/detail/

Gets the detailed list of drives with additional information to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/drives/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 7
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        }
    ]
}

List single drive

GET /drives/{uuid}/

Gets detailed information for drive identified by drive_uuid.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Creating

POST /drives/

Creates a new drive or multiple drives.

Status Codes:
  • 201 – object created

Example request:

Create a drive

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "media": "disk", 
    "name": "test_drive_0", 
    "size": 1073741824
}

or create multiple drives

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_drive_0",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_1",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_2",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_3",
            "size": 1073741824
        },
        {
            "media": "disk",
            "name": "test_drive_4",
            "size": 1073741824
        }
    ]
}

or you can omit the {‘objects’: ... } and provide only the list:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

[
    {
        "media": "disk", 
        "name": "test_drive_0", 
        "size": 1073741824
    }, 
    {
        "media": "disk", 
        "name": "test_drive_1", 
        "size": 1073741824
    }, 
    {
        "media": "disk", 
        "name": "test_drive_2", 
        "size": 1073741824
    }, 
    {
        "media": "disk", 
        "name": "test_drive_3", 
        "size": 1073741824
    }, 
    {
        "media": "disk", 
        "name": "test_drive_4", 
        "size": 1073741824
    }
]

Example response

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b582ed29-0cab-4e40-bf91-40d4b4dcc964/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b582ed29-0cab-4e40-bf91-40d4b4dcc964"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cd9580ef-692c-4da2-b64d-59c88809c30b/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cd9580ef-692c-4da2-b64d-59c88809c30b"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ea31b27b-807a-4710-b37c-c092f64bf4f7/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "ea31b27b-807a-4710-b37c-c092f64bf4f7"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "e3898bfb-32d5-48d1-afd3-c28f4c8ef6d0"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b969d04b-b63f-4b67-9a92-c878d9d53232/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b969d04b-b63f-4b67-9a92-c878d9d53232"
        }
    ]
}

Editing

PUT /drives/{uuid}/

Edits a drive. Note that if the drive is mounted on a running server only the name, meta, tags, and allow_multimount can be changed. If other fields such as size or media are changed for a drive mounted on a running server these changes will be ignored. To make sure that the changes are either fully applied or an error is returned if impossible, use the resize action (Resizing (Update or Fail)). Note that changing drive size might be a slow operation, and the drive cannot be used during the resizing.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/drives/86468a1e-d622-4080-bb6d-8ec7b635db48/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "media": "cdrom",
    "name": "test_drive_y",
    "size": 1073741824
}

Example response:

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

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "cdrom",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_y",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/86468a1e-d622-4080-bb6d-8ec7b635db48/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "86468a1e-d622-4080-bb6d-8ec7b635db48"
}

Resizing (Update or Fail)

POST /drives/{uuid}/action/?do=resize

In order to make sure that drive changes take effect, one can use the resize action. It updates a drive definition, and returns an error if not possible to completely apply the new drive definition, which may happen if the drive is mounted on a running server. The name of the action is resize because only drive size cannot be changed for a drive mounted on a running server.

Note that the resize action is a full definition update (it can update even name and metadata), so a full definition should be provided to this call.

Example:

POST /api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/action/?do=resize HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/",
    "runtime": {
        "is_snapshotable": null,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 4294967296,
    "snapshots": [],
    "status": "creating",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "df170528-c34d-4009-a806-c7d85c78cad8"
}

Note that the drive in the response is with status resizing:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/df170528-c34d-4009-a806-c7d85c78cad8/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 2147483648,
            "snapshots": [],
            "status": "resizing",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "df170528-c34d-4009-a806-c7d85c78cad8"
        }
    ]
}

Meta

It is possible to add arbitrary key-value data to a drive definition. See Objects’ metadata field for more information.

Deleting

Single drive

DELETE /drives/{uuid}/

Deletes a single mounted or unmounted drive.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Multiple drives

DELETE /drives/

Deletes multiple mounted or unmounted drives specified by their UUID’s.

statuscode 204:No content, object deletion started.

Example request:

Request body

{"objects":
  [
    {
     "uuid":"b137e217-42b6-4ecf-8575-d72efc2d3dbd",
    },
    {
     "uuid":"e035a488-8587-4a15-ab25-9b7343236bc9",
    },
    {
     "uuid":"feded33c-106f-49fa-a1c4-be5c718ad1b5",
    }
  ]
}

Example response:

HTTP/1.0 204 NO CONTENT

Cloning

POST /drives/{uuid}/action/?do=clone

Clones a drive. Request body is optional and any or all of the key/value pairs from the drive definition can be omitted. Size of the cloned drive can only be bigger or the same.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/drives/5d537d3f-22ea-4967-9ec0-32e837a8b390/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "name": "test_drive_y",
    "size": 1207959631,
    "storage_type": "dssd"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/8b00acbb-889b-44a5-8a8d-dc3617a6145d/",
                    "uuid": "8b00acbb-889b-44a5-8a8d-dc3617a6145d"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_y",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/03cb7ca7-ca07-4380-9071-c19260fbec59/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1207975936,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "03cb7ca7-ca07-4380-9071-c19260fbec59"
        }
    ]
}

Note

If no name is specified in the clone call, the name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information.

Request schema

{
   "description":"Clone drive",
   "properties":{
          "name":{
                  "description": "Name of the cloned drive",
          }
          "media":{
                  "description": "Media of the cloned drive",
          }
          "affinities":{
                  "description": "Affinities of the cloned drive",
          }
   }
}

Availability Groups

It is possible to query which drives share common storage hosts. See Drives availability groups.

Creating or Cloning Drives to Different Infrastructure (avoid)

It is possible to hint the system which drives are preferred to be on separate physical storage host. See Creating Drives in a Different Availability Group (Create/Clone Avoid).

Licenses

Drives can have licenses attached to them. This means usage of the given drive on a running server requires either posession of subscriptions for the given licenses or additional payment. Typical such example are some drives in the drives library, see Licensed drive images and Licenses list

Storage Types

Every drive has a storage_type on which they live and cannot be changed after creation. New drives by default go to dssd, and clones go to the same medium as their origin, but this can be overridden by passing a storage_type parameter. Allowed storage types can be different per location, so you should refer to the drives section of the capabilities call response, where each storage type is specified alongside with the minimum and maximum size of a single drive.

Currently the following storage types are available:

dssd
The UI name for dssd is “Distributed SSD”. As the name implies, the storage uses high-performance SSD drives, which makes this storage type suitable for IO-sensitive applications.
zadara

The UI name for zadara is “Scale-out Magnetic”. Zadara storage is suitable for less IO sensitive applications, which require large amounts of storage, like hundreds of gigabytes or even terabytes. This storage is also cheaper per gigabyte than dssd.

New in version Neon.

Creating

Example request:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_zadara_drive",
            "size": 1073741824,
            "storage_type": "zadara"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/1c17d5ad-d345-4af1-9fc8-89dec02f0daf/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "creating",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "1c17d5ad-d345-4af1-9fc8-89dec02f0daf"
        }
    ]
}

Cloning to the same storage type

Example request:

POST /api/2.0/drives/1c17d5ad-d345-4af1-9fc8-89dec02f0daf/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/900f6128-7a0f-49c3-9394-aa4f261c1b25/",
                    "uuid": "900f6128-7a0f-49c3-9394-aa4f261c1b25"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/203cbccd-0736-42dc-b75a-2bdb4db46909/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "203cbccd-0736-42dc-b75a-2bdb4db46909"
        }
    ]
}

Cloning to another storage type

Example request:

POST /api/2.0/drives/3be001aa-16df-453a-a2ab-d13981d56589/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "storage_type": "zadara"
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/c360f719-f750-4dfe-bb23-99680179b3e0/",
                    "uuid": "c360f719-f750-4dfe-bb23-99680179b3e0"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_zadara_drive_for_clone",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/drives/50b5cfdf-b286-43e9-8815-dd2c9354644b/",
            "runtime": {
                "is_snapshotable": null,
                "snapshots_allocated_size": 0,
                "storage_type": "zadara"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "zadara",
            "tags": [],
            "uuid": "50b5cfdf-b286-43e9-8815-dd2c9354644b"
        }
    ]
}

Drive State Diagram

_images/DrivesStates.png

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "affinities": {
            "choices": [
                "ssd"
            ],
            "default": [],
            "help_text": "A list of affinities this drive should belong to",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "allow_multimount": {
            "default": false,
            "help_text": "Allow the drive to be mounted on multiple guests. Not taken into account when drive is cdrom.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "licenses": {
            "default": [],
            "fields": {
                "amount": {
                    "default": 1,
                    "help_text": "Number of licenses",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "license": {
                    "default": "No default provided.",
                    "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "user": {
                    "default": null,
                    "help_text": "Owner of the license",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "A list of licenses attached to this drive",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "media": {
            "choices": [
                "cdrom",
                "disk"
            ],
            "default": null,
            "help_text": "Media representation type",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "mounted_on": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the drive",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "runtime": {
            "default": "No default provided.",
            "fields": {
                "is_snapshotable": {
                    "default": "No default provided.",
                    "help_text": "Specifies if the drive supports snapshotting",
                    "readonly": true,
                    "required": true,
                    "type": "boolean"
                },
                "snapshots_allocated_size": {
                    "default": "No default provided.",
                    "help_text": "Sum of the allocated size of this drive's snapshots",
                    "readonly": true,
                    "required": false,
                    "type": "integer"
                },
                "storage_type": {
                    "default": "No default provided.",
                    "help_text": "Underlying storage",
                    "readonly": true,
                    "required": true,
                    "type": "string"
                }
            },
            "help_text": "Runtime information of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "size": {
            "default": null,
            "help_text": "Size of the drive in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "snapshots": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the drive.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "storage_type": {
            "choices": [
                "magnetic",
                "ssd",
                "dssd",
                "zadara",
                "solidfire"
            ],
            "default": null,
            "help_text": "Underlying storage",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the drive",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Snapshots

Snapshots are point-in-time versions of a drive. They can be cloned to a full drive, which makes it possible to restore an older version of a VM image.

Snapshots are billed based on their occupied size. Since only the difference from the current drive image is stored, a single snapshot’s size will be equal to the size of the data which was changed since the snapshot was taken. If no data was changed, the snapshot’s size will be zero.

Note that snapshots are billed as drive, so drive subscriptions should be bought in order not to burst on snapshots usage.

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /snapshots/

Gets the list of snapshot to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request - default list:

GET /api/2.0/snapshots/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response - default list:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 6
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_30",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/78db3f50-945d-4795-814b-cff122f6b11f/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:30.563748+00:00",
            "uuid": "78db3f50-945d-4795-814b-cff122f6b11f"
        },
        {
            "allocated_size": null,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_32",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1/",
            "status": "creating",
            "tags": [],
            "timestamp": "2014-06-05 09:53:32.186344+00:00",
            "uuid": "44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_29",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/33c0b447-d545-457f-a01c-156f674095c8/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:29.770356+00:00",
            "uuid": "33c0b447-d545-457f-a01c-156f674095c8"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:31.377681+00:00",
            "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

Detailed listing

GET /snapshots/detail/

Gets the detailed list of snapshots with additional information to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/snapshots/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 6
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_30",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/78db3f50-945d-4795-814b-cff122f6b11f/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:30.563748+00:00",
            "uuid": "78db3f50-945d-4795-814b-cff122f6b11f"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_32",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:32.186344+00:00",
            "uuid": "44b7f63a-7fb7-4ea4-b32c-ed7d4873a3f1"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/cb1e0fee-7666-4cb9-ab17-9f064adf6177/",
                "uuid": "cb1e0fee-7666-4cb9-ab17-9f064adf6177"
            },
            "grantees": [],
            "meta": {},
            "name": "cb1e0fee-7666-4cb9-ab17-9f064adf6177__2014-06-05__09_53_29",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/33c0b447-d545-457f-a01c-156f674095c8/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:29.770356+00:00",
            "uuid": "33c0b447-d545-457f-a01c-156f674095c8"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
                "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
            },
            "grantees": [],
            "meta": {},
            "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:31.377681+00:00",
            "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

List single snapshot

GET /snapshots/{uuid}/

Gets detailed information for snapshot identified by snapshot_uuid.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "allocated_size": null,
    "drive": {
        "resource_uri": "/api/2.0/drives/bb2b8f77-04ee-42c1-b142-47bc31c2824e/",
        "uuid": "bb2b8f77-04ee-42c1-b142-47bc31c2824e"
    },
    "grantees": [],
    "meta": {},
    "name": "bb2b8f77-04ee-42c1-b142-47bc31c2824e__2014-06-05__09_53_31",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/snapshots/62c600cf-7a25-4703-8003-b3c4445233af/",
    "status": "creating",
    "tags": [],
    "timestamp": "2014-06-05 09:53:31.377681+00:00",
    "uuid": "62c600cf-7a25-4703-8003-b3c4445233af"
}

Creating

POST /snapshots/

Creates a new snapshot or multiple snapshots.

Status Codes:
  • 201 – object created

Example request:

Create a snapshot

POST /api/2.0/snapshots/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "drive": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84", 
    "meta": {
        "key": "val"
    }, 
    "name": "first_snapshot"
}

Example response

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "allocated_size": null,
            "drive": {
                "resource_uri": "/api/2.0/drives/450357dc-cbe1-471d-b4cc-dbdfe5f28d84/",
                "uuid": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84"
            },
            "grantees": [],
            "meta": {
                "key": "val"
            },
            "name": "first_snapshot",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/",
            "status": "creating",
            "tags": [],
            "timestamp": "2014-06-05 09:52:53.896622+00:00",
            "uuid": "855ebdc8-ce4b-48d0-9d8d-306c9074be29"
        }
    ]
}

Editing

PUT /snapshots/{uuid}/

Edits a snapshot.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "drive": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84",
    "meta": {
        "key": "val_changed",
        "new_key": "new_key_value"
    },
    "name": "first_snapshot_renamed"
}

Example response:

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

{
    "allocated_size": 0,
    "drive": {
        "resource_uri": "/api/2.0/drives/450357dc-cbe1-471d-b4cc-dbdfe5f28d84/",
        "uuid": "450357dc-cbe1-471d-b4cc-dbdfe5f28d84"
    },
    "grantees": [],
    "meta": {
        "key": "val_changed",
        "new_key": "new_key_value"
    },
    "name": "first_snapshot_renamed",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/",
    "status": "available",
    "tags": [],
    "timestamp": "2014-06-05 09:52:53.896622+00:00",
    "uuid": "855ebdc8-ce4b-48d0-9d8d-306c9074be29"
}

Metadata

It is possible to add arbitrary key-value data to a snapshot definition. See Objects’ metadata field for more information.

Deleting

Single snapshot

DELETE /snapshots/{uuid}/

Deletes a single snapshot.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/snapshots/855ebdc8-ce4b-48d0-9d8d-306c9074be29/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Multiple snapshots

DELETE /snapshots/

Deletes multiple mounted or unmounted snapshots specified by their UUID’s.

statuscode 204:No content, object deletion started.

Example request:

Request body

{"objects":
  [
    {
     "uuid":"b137e217-42b6-4ecf-8575-d72efc2d3dbd",
    },
    {
     "uuid":"e035a488-8587-4a15-ab25-9b7343236bc9",
    },
    {
     "uuid":"feded33c-106f-49fa-a1c4-be5c718ad1b5",
    }
  ]
}

Example response:

HTTP/1.0 204 NO CONTENT

Cloning

POST /snapshots/{uuid}/action/?do=clone

Clones a snapshot to a drive. Request body is optional and any or all of the key/value pairs can be omitted.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/snapshots/c6368b7c-9d3d-4631-b008-83b73c05f1bd/action/?do=clone&avoid=d7da5038-ac2d-4776-9097-f60167d6e587 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response: The response is actually a drive definition

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [
        {
            "resource_uri": "/api/2.0/jobs/260512fc-e9ac-470f-880d-52b4dfcc2b72/",
            "uuid": "260512fc-e9ac-470f-880d-52b4dfcc2b72"
        }
    ],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "7fbfb2ac-5b21-4c5a-81cb-d4343fca71a1__2015-03-19__13_53_52",
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "resource_uri": {
        "resource_uri": "/api/2.0/drives/be62f52e-0b0f-480c-89b2-73e108dd2cef/",
        "uuid": "be62f52e-0b0f-480c-89b2-73e108dd2cef"
    },
    "runtime": {
        "is_snapshotable": null,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "cloning_dst",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "be62f52e-0b0f-480c-89b2-73e108dd2cef"
}

Note

The name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information

Listing drive snapshots

There are 2 ways of getting all snapshots of a drive

By filtering snapshots

You can apply drive filter to snapshots

GET /snapshots/{uuid}/?drive={drive_uuid}
GET /api/2.0/snapshots/detail/?limit=0&drive=b7cb6615-b6a5-4c31-b755-b86980c64d59 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.851859+00:00",
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        },
        {
            "allocated_size": 0,
            "drive": {
                "resource_uri": "/api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/",
                "uuid": "b7cb6615-b6a5-4c31-b755-b86980c64d59"
            },
            "grantees": [],
            "meta": {},
            "name": "b7cb6615-b6a5-4c31-b755-b86980c64d59__2014-06-05__09_53_28",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/",
            "status": "available",
            "tags": [],
            "timestamp": "2014-06-05 09:53:28.048803+00:00",
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

In drive definition

In the detailed drive definition there is “snapshots” field

GET /drives/{drive_uuid}/
GET /api/2.0/drives/b7cb6615-b6a5-4c31-b755-b86980c64d59/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "snapshots": [
        {
            "resource_uri": "/api/2.0/snapshots/f69d43df-092d-4fef-9766-668cb6469f31/", 
            "uuid": "f69d43df-092d-4fef-9766-668cb6469f31"
        }, 
        {
            "resource_uri": "/api/2.0/snapshots/3a057cc8-9b42-44f2-a8cb-c5561f2eddd3/", 
            "uuid": "3a057cc8-9b42-44f2-a8cb-c5561f2eddd3"
        }
    ]
}

Request schema

{
   "description":"Clone snapshot",
   "properties":{
          "name":{
                  "description": "Name of the cloned snapshot",
          }
          "media":{
                  "description": "Media of the cloned snapshot",
          }
          "affinities":{
                  "description": "Affinities of the cloned snapshot",
          }
   }
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "allocated_size": {
            "default": "No default provided.",
            "help_text": "Physical size of the snapshot",
            "readonly": true,
            "required": true,
            "type": "integer"
        },
        "drive": {
            "default": null,
            "help_text": "Drive UUID",
            "readonly": false,
            "required": true,
            "type": "related"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Optional human readable name of the snapshot",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the snapshot",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the snapshot.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "timestamp": {
            "default": null,
            "help_text": "Timestamp of the snapshot creation",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the snapshot",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Library Drives

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /libdrives/

Gets the list of library drives to which the authenticated user has access.

param fields:A set of field names specifying the returned fields
statuscode 200:no error

Example request:

GET /api/2.0/libdrives/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 158
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "webserver",
                "general",
                "dbserver"
            ],
            "description": "Ubuntu 12.04.4 Server - 64bit Pre-Installed English with VirtIO support, SSH and Python. Last update on 2014/06/4.",
            "distribution": "Ubuntu",
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n Username: cloudsigma \\n Password: cs2014!!! \\n \\n Detailed Installation Instructions: \\n 1. Clone the Image. \\n The image needs to be cloned and then attached to a server. \\n \\n 2. Connect to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 3. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by ubuntu.com: 1GB RAM and 1GHz CPU \\n \\n 4. Update your administrator password. \\n For security reasons the \"root\" login is disabled (including for ssh) \\n User \"cloudsigma\" is available for access instead. \\n Please be aware that on first login you will be asked to change the initial password. \\n To switch to \"root\" please use the command \"sudo su\" for example. \\n \\n 5. Setup your OS. \\n The timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in. \\n \\n 6. Configuring your Networking. \\n a) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings. \\n b) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n",
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Ubuntu 12.04.4 Server",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/d446038b-784d-4ae4-9a4d-46c7b51b403d/",
            "size": 10737418240,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "d446038b-784d-4ae4-9a4d-46c7b51b403d",
            "version": "12.04.4"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "webserver",
                "general",
                "dbserver"
            ],
            "description": "Ubuntu 12.04.4 - 64bit Pre-Installed English with VirtIO support and SSH. Last update on 2014/06/4",
            "distribution": "Ubuntu",
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n Username: cloudsigma \\n Password: cs2014!!! \\n \\n Detailed Installation Instructions: \\n 1. Clone the Image. \\n The image needs to be cloned and then attached to a server. \\n \\n 2. Connect to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 3. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by ubuntu.com: 1GB RAM and 1GHz CPU \\n \\n 4. Update your administrator password. \\n For security reasons the \"root\" login is disabled (including for ssh) \\n User \"cloudsigma\" is available for access instead. \\n Please be aware that on first login you will be asked to change the initial password. \\n To switch to \"root\" please use the command \"sudo su\" for example. \\n \\n 5. Setup your OS. \\n The timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in. \\n \\n 6. Configuring your Networking. \\n a) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings. \\n b) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n",
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Ubuntu 12.04.4 Desktop",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/0a06a5f5-a74e-4f1d-844e-b00d915cfd3c/",
            "size": 10737418240,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "0a06a5f5-a74e-4f1d-844e-b00d915cfd3c",
            "version": "12.04.4"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "other"
            ],
            "description": "VirtIO Drivers for Windows v.0.1-65",
            "distribution": null,
            "favourite": false,
            "image_type": "install",
            "install_notes": "1. Attach the CD. \\n Please be aware that the CD needs to be attached to the server to IDE.\\n \\n 2. Attach VirtIO devices.\\n \\n The CD image with the VirtIO drivers does not include setup application. You will need to attach additional disk (or CD ) and network interface (recommended private) \\n In order to force windows to detect the new hardware (VirtIO) and require drivers.\\n \\n 3. Drivers installation.\\n \\n You must be logged on as an administrator to perform these steps.\\n \\n Open Device Manager by clicking the Start button Picture of the Start button, clicking Control Panel, clicking System and Maintenance, and then clicking Device Manager.\u200c\\n Administrator permission required If you are prompted for an administrator password or confirmation, type the password or provide confirmation.\\n \\n In Device Manager, locate the device you want to install, and then double-click the device name.\\n \\n Click the Driver tab, and then click install Driver and follow the instructions.\\n \\n Basically you need to browse to the CD subfolders and make sure selecting drivers are compatible with your windows distribution i.e. Win7 for Windows 2008 R2 and Vista for Windows 2008 R1\\n \\n 4. Power cycle and reattach all existing non-VirtIO devices on VirtIO\\n \\n Once you have properly installed drives you can shutdown the server and re-attach the system disk and the network interface on VirtIO. You can also detach all unnecessary devices and power on the server.\\n \\n Please be aware, if you are trying to run windows with system disk attached on VirtIO without installed drivers for VirtIO. Windows will stuck at blue screen error and probably reboot.\\n",
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "VirtIO Drivers for Windows 0.1-65",
            "os": "windows",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/6626f7cd-6085-42a2-a0b4-42262c9c6036/",
            "size": 1000013824,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "",
            "uuid": "6626f7cd-6085-42a2-a0b4-42262c9c6036",
            "version": null
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "general"
            ],
            "description": "Oracle Solaris 11.1 Server - 64bit - Install CD",
            "distribution": null,
            "favourite": false,
            "image_type": "install",
            "install_notes": "1. Attach the CD. \\n Please be aware that the CD needs to be attached to the server as IDE. \\n \\n 2. Attach a Drive. \\n Please be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n \\n 3. Connecting to your server via VNC. \\n a) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n b) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n OR \\n c) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n d) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n \\n 4. Minimum Hardware Requirements. \\n The recommended minimum hardware requirements as published by oracle.com are: 0.5GB RAM and 0.5GHz CPU \\n \\n",
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "Oracle Solaris 11.1 Server",
            "os": "linux",
            "owner": null,
            "paid": false,
            "resource_uri": "/api/2.0/libdrives/07f3cc68-203e-4094-92c6-5d684ad609b1/",
            "size": 613695488,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "http://www.oracle.com/",
            "uuid": "07f3cc68-203e-4094-92c6-5d684ad609b1",
            "version": null
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "arch": "64",
            "category": [
                "dbserver"
            ],
            "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
            "distribution": null,
            "favourite": false,
            "image_type": "preinst",
            "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
            "jobs": [],
            "licenses": [
                {
                    "amount": 1,
                    "license": {
                        "burstable": true,
                        "long_name": "Windows Server",
                        "name": "msft_p73_04837_core",
                        "resource_uri": "/api/2.0/licenses/12/",
                        "type": "instance",
                        "user_metric": "smp"
                    },
                    "user": null
                },
                {
                    "amount": 1,
                    "license": {
                        "burstable": false,
                        "long_name": "SQL Server Standard Edition",
                        "name": "msft_7nq_00302",
                        "resource_uri": "/api/2.0/licenses/14/",
                        "type": "instance",
                        "user_metric": "smp"
                    },
                    "user": null
                }
            ],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
            "os": "windows",
            "owner": null,
            "paid": true,
            "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
            "size": 64424509440,
            "status": "unmounted",
            "storage_type": null,
            "tags": [],
            "url": "http://www.microsoft.com/",
            "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
            "version": null
        }
    ]
}

Detailed listing

Note

For consistency, we left /libdrives/detail/ url enabled, but it returns the same level of detail as the list call.

List single drive

GET /libdrives/{uuid}/

Gets detailed information for library drive identified by uuid.

statuscode 200:no error

Example request:

GET /api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "affinities": [],
    "allow_multimount": false,
    "arch": "64",
    "category": [
        "dbserver"
    ],
    "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
    "distribution": null,
    "favourite": false,
    "image_type": "preinst",
    "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "os": "windows",
    "owner": null,
    "paid": true,
    "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "size": 64424509440,
    "status": "unmounted",
    "storage_type": null,
    "tags": [],
    "url": "http://www.microsoft.com/",
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
    "version": null
}

Attaching library drive

If the library drive is a CDROM media, you can attach it directly to an owned server the same way you attach a regular drive - specifying the library drive uuid.

Cloning library drive

POST /libdrives/{uuid}/action/?do=clone

If a library drive is not a CDROM, you have to clone it in your account in order to use it. You can clone a library drive the same way you clone a regular drive.

Licensed drive images

Some drives in the library may require additional subscriptions or payment to be used. This is visible from the licenses field in the drive definition. When you clone such image from drives library to your account, the licenses remain bound to the cloned drive and can’t be altered upon drive edit. See also Licenses list regarding how to list all defined licenses.

Recognizing library drives

Note that library drives can be queried through regular drives API using /drives/{uuid}/. If the drive uuid happens to be the uuid of a library drive, the drive defintion will be retrieved. In order to differentiate between owned and library drive, one can check the owner attribute, which is null for library drives.

It is possible to get a library drive through the drives API, because there isn’t a way to know in advance whether an attached drive in a server definition is owned by the user or one from library.

Library drives are not listed in the list and detailed list for ordinary drives.

Example:

Get the drive from /drives/{uuid}/:

GET /api/2.0/drives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "owner": null,
    "permissions": [],
    "resource_uri": "/api/2.0/drives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 64424509440,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433"
}

Notice that there is no owner (it is null).

Get the same drive from /libdrives/{uuid}/:

GET /api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "arch": "64",
    "category": [
        "dbserver"
    ],
    "description": "Pre-installed SQL Server 2012 Standard Edition with SP1 64bit English with VirtIO and Python support. Last update on 2013/11/05.",
    "distribution": null,
    "favourite": false,
    "image_type": "preinst",
    "install_notes": "Initial Credentials: \\n\r\nUsername: Cloudsigma \\n\r\nPassword: cs2013! \\n\r\n\\n\r\nDetailed Installation Instructions: \\n\r\n1. Clone the Image \\n\r\nThe image needs to be cloned and then attached to a server. \\n\r\n \\n\r\n2. Buy a license \\n\r\nIn order to use CloudSigma's windows pre-installed image you need to buy a license from the UI: \\n\r\na) Click on Control Panel \\n\r\nb) Click on Subscriptions \\n\r\nC) Click on Purchase >> software licenses \\n\r\n \\n\r\n3. Connecting to your server via VNC \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI.  \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window.  \\n\r\n \\n\r\n4. Minimum Hardware Requirements \\n\r\nThe recommended minimum hardware requirements as published by Microsoft can be found through the following link: http://msdn.microsoft.com/en-us/windowsserver/cc196364.aspx .\r\nWe recommend specifying a higher level of RAM for a better user experience. \\n\r\n \\n\r\n5. Update your administrator password \\n\r\nFor security reasons the \"administrator\" login is disabled. \\n\r\nUser \"cloudsigma\" is available for access instead. \\n\r\nPlease be aware that on first login you will be asked to change the initial password.  \\n\r\n \\n\r\n6. Setup your Windows \\n\r\nThe timezone is set to the default one of the OS. So please change it to the desired one as soon as you are logged in.  \\n\r\n \\n\r\n7. Configuring your Networking \\n\r\na) IP networking can be left as DHCP. Even if you are using a static IP address with this server our management layer will apply the same IP address via DHCP. It is recommended to use DHCP which will ensure that there will be no issues receiving the correct networking settings.  \\n\r\nb) CloudSigma employs with an open networking infrastructure. All ports are opened for inbound and outbound traffic. Only for trial users port 25 (SMTP) is blocked. It is important that you secure the access to your server according to your needs. \\n\r\n\\n\r\n8. Expanding your drive \\n\r\nThe system is fully installed, but you will need to extend the disk partition to cover the whole of your drive. In order to do this please follow the steps below: \\n\r\na) Open the \"Computer Management\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) Select \"Storage\" then \"Disk Management\" in the left hand pane \\n\r\nc) Right-click on the 19.90 GB NTFS primary partition, and select \"Extend Volume\" \\n\r\nd) Enter the amount of disk space that you want to increase the Volume size by (the default will be the maximum available) \\n\r\nYou will need to repeat this procedure if you ever resize this drive in future. \\n\r\n \\n\r\n9. Enabling Remote Access \\n\r\nAfter logging in thought VNC for a first time to configure your new Windows server, we recommend that if you are logging in from a Windows Desktop that you enable Remote Desktop for better access performance. To do this, follow these instructions below: \\n\r\na) Select \"Start\" | \"Applications\" | \"Control Panel\" \\n\r\nb) Select \"System and Security\" \\n\r\nc) Under \"System\" select \"Allow Remote Access\" \\n\r\nd) Select the corresponding connection type according to your Security Configuration \\n\r\n \\n\r\n10. Pinging Service \\n\r\nThe Pinging service has been turned on by default, if you wish to disable it please follow the instructions below: \\n\r\na) Select the \"Windows Firewall with Advanced Security\" tool from \"Administrative Tools\" on the \"Start\" menu. \\n\r\nb) On the left hand pane, select \"Inbound Rules\" \\n\r\nc) On the middle pane, select the rules \"File and Printer Sharing (Echo Request - ICMPv4-In)\" and \"File and Printer Sharing (Echo Request - ICMPv6-In)\" \\n\r\nd) From the right-hand pane, select \"Disable Rules\" \\n\r\n",
    "jobs": [],
    "licenses": [
        {
            "amount": 1,
            "license": {
                "burstable": false,
                "long_name": "SQL Server Standard Edition",
                "name": "msft_7nq_00302",
                "resource_uri": "/api/2.0/licenses/14/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        },
        {
            "amount": 1,
            "license": {
                "burstable": true,
                "long_name": "Windows Server",
                "name": "msft_p73_04837_core",
                "resource_uri": "/api/2.0/licenses/12/",
                "type": "instance",
                "user_metric": "smp"
            },
            "user": null
        }
    ],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "Microsoft SQL Server 2012 Standard Edition with SP1",
    "os": "windows",
    "owner": null,
    "paid": true,
    "resource_uri": "/api/2.0/libdrives/c7105ec8-5d60-43a7-a11b-18dcfc1a4433/",
    "size": 64424509440,
    "status": "unmounted",
    "storage_type": null,
    "tags": [],
    "url": "http://www.microsoft.com/",
    "uuid": "c7105ec8-5d60-43a7-a11b-18dcfc1a4433",
    "version": null
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "affinities": {
            "choices": [
                "ssd"
            ],
            "default": [],
            "help_text": "A list of affinities this drive should belong to",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "allow_multimount": {
            "default": false,
            "help_text": "Allow the drive to be mounted on multiple guests. Not taken into account when drive is cdrom.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "arch": {
            "default": null,
            "help_text": "Operating system bit architecture the drive.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "category": {
            "default": [],
            "help_text": "Category of the drive.",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "description": {
            "default": null,
            "help_text": "Description of drive image.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "distribution": {
            "default": null,
            "help_text": "OS distribution of the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "favourite": {
            "default": null,
            "help_text": "Favourite drive image for user.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "image_type": {
            "default": null,
            "help_text": "Type of drive image.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "install_notes": {
            "default": null,
            "help_text": "Install notes for the drive image.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "licenses": {
            "default": [],
            "fields": {
                "amount": {
                    "default": 1,
                    "help_text": "Number of licenses",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "license": {
                    "default": "No default provided.",
                    "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "user": {
                    "default": null,
                    "help_text": "Owner of the license",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "A list of licenses attached to this drive",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "media": {
            "choices": [
                "cdrom",
                "disk"
            ],
            "default": null,
            "help_text": "Media representation type",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "mounted_on": {
            "default": "No default provided.",
            "help_text": "Servers on which this drive is mounted on",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the drive",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "os": {
            "default": null,
            "help_text": "Operating system of the drive.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the drive",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "paid": {
            "default": null,
            "help_text": "Paid or free.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "size": {
            "default": null,
            "help_text": "Size of the drive in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the drive.",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "storage_type": {
            "default": "No default provided.",
            "help_text": "Underlying storage",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "url": {
            "default": null,
            "help_text": "Operating system bit architecture the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the drive",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "version": {
            "default": null,
            "help_text": "OS version of the drive.",
            "readonly": false,
            "required": false,
            "type": "string"
        }
    },
    "filtering": {
        "arch": "exact",
        "category": "exact",
        "distribution": "exact",
        "image_type": "exact",
        "name": "exact",
        "name__icontains": "exact",
        "os": "exact",
        "uuid": "exact",
        "version": "exact"
    }
}

Upload or Download Drive Images

Uploading a drive image

POST https://direct.{loc}.cloudsigma.com/api/2.0/drives/upload/

A drive image can be uploaded by issuing a POST request with the image to /drive/upload/. Note that there is a different domain endpoint for uploads direct.{loc}.cloudsigma.com.

Currently only raw disk images are supported. The request body should contain the raw byte stream of disk a image and should specify correct content type (Content-Type: application/octet-stream) in the request headers. The drive upload API supports only Basic HTTP authentication.

It is very important that the Content-Length contains the correct size of the data to be sent, because it determines the size of the drive which will be created. Note that if the uploaded image is smaller than the minimum drive size (Check Capabilities), it will be resized automatically on upload completion.

It is possible to specify the file name in the path, i.e. to upload the image to /drive/upload/file_name path, but the file name is ignored. This makes it easier to use tools, such as curl, which usually upload to a path ending with the name of the file.

The returned response contains the UUID of the created drive.

Below is an example on how to upload a drive image using curl:

curl --request POST --user email@example.com:password \
     --header 'Content-Type: application/octet-stream' \
     --upload-file /path/to/file \
     https://direct.zrh.cloudsigma.com/api/2.0/drives/upload/

Note that in the above command specifying the Content-Type header also sets curl to not encode the body of the request and leave it as an octet-stream.

The command prints the UUID of the uploaded image. You may want to save it to a file with an output redirect by appending > uploaded_drive_uuid at the end of the command.

By default curl does not show upload progress. You may add –verbose (-v) option if you use curl on the command line to print the progress and speed of upload.

Downloading a drive image

GET https://direct.{loc}.cloudsigma.com/api/2.0/drives/{uuid}/download/

To download a drive image issue a GET request to /drives/{uuid}/download/. Note that there is a different domain endpoint for image download direct.{loc}.cloudsigma.com. The download client should handle HTTP redirects correctly. The resulting response contains an Content-Type: application/octet-stream file. The file name is set to the image UUID in the Content-Disposition header.

Below is an example on how to download a drive image using curl:

curl --location \
     --remote-name --remote-header-name \
     --user email@example.com:password \
     https://direct.zrh.cloudsigma.com/api/2.0/drives/ad64ded1-be81-454a-aa14-d7809cca93eb/download/

The –location option instructs curl to follow redirects. The client is expected to follow HTTP redirects.

The above command uses –remote-header-name to save the image into a file named as specified in Content-Disposition. The name in the content disposition is set to the drive UUID. It is possible to specify a different output name/path with the –output (-o) option. Note that –remote-header-name should always be used together with –remote-name.

Servers / VMs

Hypervisors

Servers have hypervisor and cpu_type parameters whose combination must match the one in the capabilities of the cloud. This page deals with generic server operations. There are specifics for each type of hypervisor:

The default hypervisor is kvm to maintain backwards compatibility and the default cpu_type is amd. If you specifiy a different hypervisor and no cpu_type, the API will still use amd.

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /servers/

Gets the list of servers to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/servers/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "name": "test_server_3",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/3ca429cc-b4f4-42a8-aaa8-3a6df700af06/",
            "runtime": null,
            "status": "stopped",
            "uuid": "3ca429cc-b4f4-42a8-aaa8-3a6df700af06"
        },
        {
            "name": "test_server_0",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/f50b672f-a963-4b8a-bf05-809b3ffd9a9f/",
            "runtime": null,
            "status": "stopped",
            "uuid": "f50b672f-a963-4b8a-bf05-809b3ffd9a9f"
        },
        {
            "name": "test_server_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888/",
            "runtime": null,
            "status": "stopped",
            "uuid": "5d5f22ea-68ae-4b83-9b19-7d7cdd2eb888"
        },
        {
            "name": "test_server_4",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/8d483469-faeb-4408-899b-a10df6bf3587/",
            "runtime": null,
            "status": "stopped",
            "uuid": "8d483469-faeb-4408-899b-a10df6bf3587"
        },
        {
            "name": "test_server_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/servers/514a790d-9798-4476-93e9-5cecb4b1c6a3/",
            "runtime": null,
            "status": "stopped",
            "uuid": "514a790d-9798-4476-93e9-5cecb4b1c6a3"
        }
    ]
}

Detailed listing

GET /servers/detail/

Gets the detailed list of servers to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/servers/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_2",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/83ec9545-b1c9-4430-90e4-91f7774a8e5d/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "83ec9545-b1c9-4430-90e4-91f7774a8e5d",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_0",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/e789b2eb-9529-4c34-a878-e7ccce97b94c/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "e789b2eb-9529-4c34-a878-e7ccce97b94c",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_1",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/ce076c1f-2cad-4e6b-9299-5a5f8e7991e5/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "ce076c1f-2cad-4e6b-9299-5a5f8e7991e5",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_4",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/8ffcc303-aa05-4e85-b0c6-80579e19a6b8/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "8ffcc303-aa05-4e85-b0c6-80579e19a6b8",
            "vnc_password": "testserver"
        },
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server_3",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/0faa63b3-dc71-4139-b535-507a6938e5ea/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "0faa63b3-dc71-4139-b535-507a6938e5ea",
            "vnc_password": "testserver"
        }
    ]
}

Creating

POST /servers/

Creates a new virtual server or multiple servers. The minimial amount of information you need to set is as follows

Status Codes:
  • 201 – object created

Example request:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "testServerAcc",
            "vnc_password": "testserver"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "testServerAcc",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/d0ae4a09-13d5-4af2-aa12-56935035adef/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "d0ae4a09-13d5-4af2-aa12-56935035adef",
            "vnc_password": "testserver"
        }
    ]
}

Editing

PUT /servers/{uuid}/

Edits a server. Used also for attaching NIC’s and drives to servers. Note that if a server is running, only name, meta, and tags fields can be changed, and all other changes to the definition of a running server will be ignored.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "cpu": 2000,
    "mem": 536870912,
    "name": "test_server_updated",
    "vnc_password": "updated_password"
}

Example response:

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

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

Attach a drive

PUT /servers/{uuid}/

Attaching a drive is just an edit server operation.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "cpu": 2000,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": "756f5728-2123-4381-bc7c-f73dc2a3f55f"
        }
    ],
    "mem": 536870912,
    "name": "test_server_updated",
    "vnc_password": "updated_password"
}

Example response:

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

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": {
                "resource_uri": "/api/2.0/drives/756f5728-2123-4381-bc7c-f73dc2a3f55f/",
                "uuid": "756f5728-2123-4381-bc7c-f73dc2a3f55f"
            },
            "runtime": null
        }
    ],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

Metadata

It is possible to add arbitrary key-value data to a server definition. See Objects’ metadata field for more information.

Deleting

Single server

DELETE /servers/{uuid}/

Deletes a single server.

Status Codes:
  • 204 – No content, object deletion started.

Example request:

DELETE /api/2.0/servers/d0ae4a09-13d5-4af2-aa12-56935035adef/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Delete Server together with attached drives (recursive delete)

DELETE /servers/{uuid}/?recurse={recurse_option}

It is possible to delete a server together with it’s drives (recursive delete). There are three options: delete all attached drives, delete only disks(non-cdrom drives), or delete only attached cdroms. To recursively delete drives, supply a recurse URL parameter with a value as described in the following table:

Recurse option Effect
all_drives All attached drives regardless of media type will be deleted
disks Only attached drives with media type disk will be deleted
cdroms Only attached drives with media type cdrom will be deleted

Example request to delete a server with all attached drives:

A server is created with a cdrom and disk drives:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [
                {
                    "boot_order": null,
                    "dev_channel": "0:0",
                    "device": "ide",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/3df825cb-9c1b-470d-acbd-03e1a966c046/",
                        "uuid": "3df825cb-9c1b-470d-acbd-03e1a966c046"
                    },
                    "runtime": null
                },
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/52f03c84-0397-494a-962b-2bf7b08e26d3/",
                        "uuid": "52f03c84-0397-494a-962b-2bf7b08e26d3"
                    },
                    "runtime": null
                }
            ],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 268435456,
            "meta": {
                "description": "A full server with description"
            },
            "name": "test_acc_full_server",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:20:d8:4d:24:ca",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/dc3a65b4-0e6f-4f4e-8e34-02cefb9f9eae/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "dc3a65b4-0e6f-4f4e-8e34-02cefb9f9eae",
            "vnc_password": "tester"
        }
    ]
}

The following drives are available in the account:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/f2af396d-6821-4d8d-87ea-8c967468e220/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "f2af396d-6821-4d8d-87ea-8c967468e220"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/f1888988-7754-4d89-a004-693fbf62e7a6/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "f1888988-7754-4d89-a004-693fbf62e7a6"
        }
    ]
}

The server is recursively deleted with all drives:

DELETE /api/2.0/servers/dc3a65b4-0e6f-4f4e-8e34-02cefb9f9eae/?recurse=all_drives HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

After DELETE of the server the, drives attached to the server are deleted:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        }
    ]
}

Example request to delete a server with attached disk drives and leave CDROMs:

A server is created with a cdrom and disk drives:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [
                {
                    "boot_order": null,
                    "dev_channel": "0:0",
                    "device": "ide",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/3df825cb-9c1b-470d-acbd-03e1a966c046/",
                        "uuid": "3df825cb-9c1b-470d-acbd-03e1a966c046"
                    },
                    "runtime": null
                },
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/52f03c84-0397-494a-962b-2bf7b08e26d3/",
                        "uuid": "52f03c84-0397-494a-962b-2bf7b08e26d3"
                    },
                    "runtime": null
                }
            ],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 268435456,
            "meta": {
                "description": "A full server with description"
            },
            "name": "test_acc_full_server",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:20:d8:4d:24:ca",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/dc3a65b4-0e6f-4f4e-8e34-02cefb9f9eae/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "dc3a65b4-0e6f-4f4e-8e34-02cefb9f9eae",
            "vnc_password": "tester"
        }
    ]
}

The following drives are available in the account:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/cf0af312-aeeb-4f3a-bf00-426d13126edf/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "cf0af312-aeeb-4f3a-bf00-426d13126edf"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "otom-0-take2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/e81fae7b-7966-46f6-917f-d366a799b550/",
                    "uuid": "e81fae7b-7966-46f6-917f-d366a799b550"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3a458646-73ea-4755-a398-953a33e8200d/",
                    "uuid": "3a458646-73ea-4755-a398-953a33e8200d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e048129a-7652-4ab8-a9c3-11c419954b93/",
                    "uuid": "e048129a-7652-4ab8-a9c3-11c419954b93"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95/",
                    "uuid": "ea3cc85a-3ab1-45dd-bea5-60ab6eda7d95"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4/",
                    "uuid": "1c3b2c65-84c1-4509-b4cf-c6bb40aa67f4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e222c128-02bc-4109-ab8c-e8eaec2deb84/",
                    "uuid": "e222c128-02bc-4109-ab8c-e8eaec2deb84"
                },
                {
                    "resource_uri": "/api/2.0/jobs/d73a977d-13e2-4af7-bb46-9f90a3cdb709/",
                    "uuid": "d73a977d-13e2-4af7-bb46-9f90a3cdb709"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9751e954-6272-4170-ace4-749234beda41/",
                    "uuid": "9751e954-6272-4170-ace4-749234beda41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d1914a9-ef59-4ca5-b0b9-94e5100e01f1/",
                    "uuid": "8d1914a9-ef59-4ca5-b0b9-94e5100e01f1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8882034b-8149-4381-8e3b-3d63df48a089/",
                    "uuid": "8882034b-8149-4381-8e3b-3d63df48a089"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8961f56a-009e-4d70-b39a-363c86e2797f/",
                    "uuid": "8961f56a-009e-4d70-b39a-363c86e2797f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
                    "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
                },
                {
                    "resource_uri": "/api/2.0/jobs/15e31b74-49bd-4d5f-b300-b1104dcebda2/",
                    "uuid": "15e31b74-49bd-4d5f-b300-b1104dcebda2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a/",
                    "uuid": "ca481dd7-f6ee-48aa-b8fe-7d2ba14da03a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0d8ae7db-72e3-4a9c-bc5e-20b767fefb46/",
                    "uuid": "0d8ae7db-72e3-4a9c-bc5e-20b767fefb46"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f9a362a3-1c0c-4672-857d-78533e8745a4/",
                    "uuid": "f9a362a3-1c0c-4672-857d-78533e8745a4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73/",
                    "uuid": "eeaf59bb-a3b4-4f07-9a5e-fac08a51bb73"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5c5e4b51-21b7-446e-8dc5-d2adba7a8b72/",
                    "uuid": "5c5e4b51-21b7-446e-8dc5-d2adba7a8b72"
                },
                {
                    "resource_uri": "/api/2.0/jobs/b65998cb-a061-4526-b9b8-8939e0caa726/",
                    "uuid": "b65998cb-a061-4526-b9b8-8939e0caa726"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2e11ce11-2016-47cd-a6cd-081961337692/",
                    "uuid": "2e11ce11-2016-47cd-a6cd-081961337692"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e05d7f4d-2982-47ac-aa2d-ce0cc72c2292/",
                    "uuid": "e05d7f4d-2982-47ac-aa2d-ce0cc72c2292"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a755c06f-0345-4233-b65b-55823e0224e7/",
                    "uuid": "a755c06f-0345-4233-b65b-55823e0224e7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a4d98424-b23e-40b9-af71-aa1c772100eb/",
                    "uuid": "a4d98424-b23e-40b9-af71-aa1c772100eb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/61dd578a-7f91-4259-ac18-3c95faab172b/",
                    "uuid": "61dd578a-7f91-4259-ac18-3c95faab172b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/86d899d3-940c-401e-bc26-d8394089f993/",
                    "uuid": "86d899d3-940c-401e-bc26-d8394089f993"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad920c1d-4efe-4ed4-87fd-d9d9da718667/",
                    "uuid": "ad920c1d-4efe-4ed4-87fd-d9d9da718667"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4d043d40-ebc4-4501-8386-9751ac19f9b9/",
                    "uuid": "4d043d40-ebc4-4501-8386-9751ac19f9b9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9c05f3a1-13a5-45af-8faf-6bb47a53e2d8/",
                    "uuid": "9c05f3a1-13a5-45af-8faf-6bb47a53e2d8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c7e7fe31-179b-4b38-a5fa-e3f399f683f2/",
                    "uuid": "c7e7fe31-179b-4b38-a5fa-e3f399f683f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c31b43f-55d8-426a-8124-02c71a0b3b4e/",
                    "uuid": "3c31b43f-55d8-426a-8124-02c71a0b3b4e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/08312509-d90a-44e9-9f07-280d2e2935ae/",
                    "uuid": "08312509-d90a-44e9-9f07-280d2e2935ae"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1cd69a16-5aee-45a9-99ec-698a1266c514/",
                    "uuid": "1cd69a16-5aee-45a9-99ec-698a1266c514"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f1f2db65-5681-4404-888a-46aa97df6d9a/",
                    "uuid": "f1f2db65-5681-4404-888a-46aa97df6d9a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/11f45314-d3c1-469c-aaa0-d30d3574a62b/",
                    "uuid": "11f45314-d3c1-469c-aaa0-d30d3574a62b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ac68490-9e85-4b41-a76d-754df657dbd1/",
                    "uuid": "9ac68490-9e85-4b41-a76d-754df657dbd1"
                },
                {
                    "resource_uri": "/api/2.0/jobs/93110b55-ad01-46e7-a71c-c10365e746b4/",
                    "uuid": "93110b55-ad01-46e7-a71c-c10365e746b4"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7e6036be-b47b-4b7a-86c8-50e9ed585404/",
                    "uuid": "7e6036be-b47b-4b7a-86c8-50e9ed585404"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5/",
                    "uuid": "e8d70c86-7ce2-4506-87ea-7c4a0d1eb9e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0b1280ae-b715-4dbc-a902-86c25603474d/",
                    "uuid": "0b1280ae-b715-4dbc-a902-86c25603474d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/401d7916-359a-4cca-8abd-f6f832c97983/",
                    "uuid": "401d7916-359a-4cca-8abd-f6f832c97983"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
                    "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bf3ff2b7-52b6-4ac8-921a-7d44b80711bb/",
                    "uuid": "bf3ff2b7-52b6-4ac8-921a-7d44b80711bb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ce2ce9d-587c-46f6-b3bd-991ebf26b121/",
                    "uuid": "9ce2ce9d-587c-46f6-b3bd-991ebf26b121"
                },
                {
                    "resource_uri": "/api/2.0/jobs/79aed1c7-570a-4191-897a-337476ebc074/",
                    "uuid": "79aed1c7-570a-4191-897a-337476ebc074"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1d630913-cef6-4e60-a472-125ded470400/",
                    "uuid": "1d630913-cef6-4e60-a472-125ded470400"
                },
                {
                    "resource_uri": "/api/2.0/jobs/51f61346-6d9b-48b7-8cf5-4f70acc1dd97/",
                    "uuid": "51f61346-6d9b-48b7-8cf5-4f70acc1dd97"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec58e294-0906-495f-86a2-4dd423fdd7b6/",
                    "uuid": "ec58e294-0906-495f-86a2-4dd423fdd7b6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ce301022-90ef-4b7d-819a-5b6172b942f2/",
                    "uuid": "ce301022-90ef-4b7d-819a-5b6172b942f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/09b4a45d-1b79-4116-bf01-96331f939d07/",
                    "uuid": "09b4a45d-1b79-4116-bf01-96331f939d07"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1287eee1-8b2c-443e-b177-0235a76a3ab3/",
                    "uuid": "1287eee1-8b2c-443e-b177-0235a76a3ab3"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7b71312d-fb1c-43c6-962b-6fd15e637ad9/",
                    "uuid": "7b71312d-fb1c-43c6-962b-6fd15e637ad9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4e5b16d-abca-41e0-8755-75fbb0d434c6/",
                    "uuid": "e4e5b16d-abca-41e0-8755-75fbb0d434c6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/dc7c4fca-6a66-4efb-87b8-db1d2dc9730a/",
                    "uuid": "dc7c4fca-6a66-4efb-87b8-db1d2dc9730a"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c61d1361-633f-4304-b80b-aff64785ac91/",
                    "uuid": "c61d1361-633f-4304-b80b-aff64785ac91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52/",
                    "uuid": "5ee1a46b-4e58-4ec0-9dae-e7b919ae6e52"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a2021f29-9f12-4443-87b3-0b2fdb9a76b5/",
                    "uuid": "a2021f29-9f12-4443-87b3-0b2fdb9a76b5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/38def946-1616-4215-b216-16035a1fb738/",
                    "uuid": "38def946-1616-4215-b216-16035a1fb738"
                },
                {
                    "resource_uri": "/api/2.0/jobs/02255a54-8b9f-43ec-b751-89a4afc18a90/",
                    "uuid": "02255a54-8b9f-43ec-b751-89a4afc18a90"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ec61caa4-2baf-45ec-8f59-61e5716395ca/",
                    "uuid": "ec61caa4-2baf-45ec-8f59-61e5716395ca"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f/",
                    "uuid": "ae8ecbcb-68e9-42b6-9c04-6ff9ffd7f88f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/1fbbcfcf-5027-4100-a93b-83ff73ff80cb/",
                    "uuid": "1fbbcfcf-5027-4100-a93b-83ff73ff80cb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f12e8cd7-d76e-4b8a-b692-f4c22266e792/",
                    "uuid": "f12e8cd7-d76e-4b8a-b692-f4c22266e792"
                },
                {
                    "resource_uri": "/api/2.0/jobs/728f1e12-2701-4618-a1ec-ff1a2cac63d0/",
                    "uuid": "728f1e12-2701-4618-a1ec-ff1a2cac63d0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/43f28ca1-e523-4481-966b-1c85fbb673fa/",
                    "uuid": "43f28ca1-e523-4481-966b-1c85fbb673fa"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9a1cc534-e426-4b68-b001-75f37119b353/",
                    "uuid": "9a1cc534-e426-4b68-b001-75f37119b353"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d18c709-1601-4a7f-af9d-530ab86ef825/",
                    "uuid": "3d18c709-1601-4a7f-af9d-530ab86ef825"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a93b3d0d-e294-4f02-bc44-3cfd36d24ddb/",
                    "uuid": "a93b3d0d-e294-4f02-bc44-3cfd36d24ddb"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f47b65e9-14ca-40f6-9b2a-60c27091a75f/",
                    "uuid": "f47b65e9-14ca-40f6-9b2a-60c27091a75f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/69713c13-b1bb-4f84-972c-eb7adf55a051/",
                    "uuid": "69713c13-b1bb-4f84-972c-eb7adf55a051"
                },
                {
                    "resource_uri": "/api/2.0/jobs/8d650bc8-80f9-4272-b190-11cd4b086d91/",
                    "uuid": "8d650bc8-80f9-4272-b190-11cd4b086d91"
                },
                {
                    "resource_uri": "/api/2.0/jobs/12684b6c-fc57-4edb-916f-efe78a0e3f51/",
                    "uuid": "12684b6c-fc57-4edb-916f-efe78a0e3f51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/564c53a1-69c0-45de-8836-f52b49baff18/",
                    "uuid": "564c53a1-69c0-45de-8836-f52b49baff18"
                },
                {
                    "resource_uri": "/api/2.0/jobs/26b24ab4-a89b-44d6-9194-e7324faa8922/",
                    "uuid": "26b24ab4-a89b-44d6-9194-e7324faa8922"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f/",
                    "uuid": "e24ed38b-1d3a-4f1d-8c91-2812f8c13c5f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/52a1d9da-ee39-4973-b047-9233ae4e09ed/",
                    "uuid": "52a1d9da-ee39-4973-b047-9233ae4e09ed"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7c7d954c-58d9-49cf-9d9b-645adeb072de/",
                    "uuid": "7c7d954c-58d9-49cf-9d9b-645adeb072de"
                },
                {
                    "resource_uri": "/api/2.0/jobs/6043d2cf-d1d3-4221-bc3a-6aa3c782e68d/",
                    "uuid": "6043d2cf-d1d3-4221-bc3a-6aa3c782e68d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/c718ce2d-0ba6-4964-be73-d35282a1024d/",
                    "uuid": "c718ce2d-0ba6-4964-be73-d35282a1024d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090/",
                    "uuid": "3c92ad0f-e5a8-40b8-8d15-5dbb37ab5090"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3e849dc8-f88e-4aa9-a7bb-5c245c892098/",
                    "uuid": "3e849dc8-f88e-4aa9-a7bb-5c245c892098"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fbc30ede-7ec5-4e11-8c51-6b729875bc41/",
                    "uuid": "fbc30ede-7ec5-4e11-8c51-6b729875bc41"
                },
                {
                    "resource_uri": "/api/2.0/jobs/243e1c08-3b5f-4a87-acee-ff6aefb1dcbd/",
                    "uuid": "243e1c08-3b5f-4a87-acee-ff6aefb1dcbd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/592437ff-0cb0-4f62-a62c-ac964f5e6d45/",
                    "uuid": "592437ff-0cb0-4f62-a62c-ac964f5e6d45"
                },
                {
                    "resource_uri": "/api/2.0/jobs/34502453-dba1-4530-bc75-7aadddbd6376/",
                    "uuid": "34502453-dba1-4530-bc75-7aadddbd6376"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3246e6e6-ea98-47cf-8e1c-174beec2b466/",
                    "uuid": "3246e6e6-ea98-47cf-8e1c-174beec2b466"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a7269f26-a630-4289-9195-322807e5d626/",
                    "uuid": "a7269f26-a630-4289-9195-322807e5d626"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9050f1d1-9ac3-4cfb-bd30-0d4b169cc873/",
                    "uuid": "9050f1d1-9ac3-4cfb-bd30-0d4b169cc873"
                },
                {
                    "resource_uri": "/api/2.0/jobs/0649e5fe-1a17-4b16-8473-fa847cabb603/",
                    "uuid": "0649e5fe-1a17-4b16-8473-fa847cabb603"
                },
                {
                    "resource_uri": "/api/2.0/jobs/db26bfbf-a615-4eb4-a631-9ba85140dc3b/",
                    "uuid": "db26bfbf-a615-4eb4-a631-9ba85140dc3b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4eb78262-9f34-4ed8-81de-00b9ac11bfd8/",
                    "uuid": "4eb78262-9f34-4ed8-81de-00b9ac11bfd8"
                },
                {
                    "resource_uri": "/api/2.0/jobs/2a3ac055-0133-4b6e-a999-1c9c197bd55c/",
                    "uuid": "2a3ac055-0133-4b6e-a999-1c9c197bd55c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16a02c3f-f5eb-48b6-a8da-8185a39f17a2/",
                    "uuid": "16a02c3f-f5eb-48b6-a8da-8185a39f17a2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/85ecfbc9-9857-49e4-909a-2c7cdcbc1adc/",
                    "uuid": "85ecfbc9-9857-49e4-909a-2c7cdcbc1adc"
                },
                {
                    "resource_uri": "/api/2.0/jobs/18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5/",
                    "uuid": "18d1b2ae-3f9b-4cae-b5f4-6086f868d5e5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/7879e9e0-de4b-4b85-b69f-b416243527d9/",
                    "uuid": "7879e9e0-de4b-4b85-b69f-b416243527d9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/13bfc35b-6374-480d-aed7-d06e9b69f52b/",
                    "uuid": "13bfc35b-6374-480d-aed7-d06e9b69f52b"
                },
                {
                    "resource_uri": "/api/2.0/jobs/fcc07794-94e0-4f6b-a9f0-32c52098b7f2/",
                    "uuid": "fcc07794-94e0-4f6b-a9f0-32c52098b7f2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bce778e4-5003-4cb0-b60b-e86717e11584/",
                    "uuid": "bce778e4-5003-4cb0-b60b-e86717e11584"
                },
                {
                    "resource_uri": "/api/2.0/jobs/3d7cf702-917a-4864-9a22-b8b1c0ddd0da/",
                    "uuid": "3d7cf702-917a-4864-9a22-b8b1c0ddd0da"
                },
                {
                    "resource_uri": "/api/2.0/jobs/002b43f6-f12e-4b4a-9566-3affc49cbff5/",
                    "uuid": "002b43f6-f12e-4b4a-9566-3affc49cbff5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
                    "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
                },
                {
                    "resource_uri": "/api/2.0/jobs/80498624-4b6a-4c23-8db3-0402b8bc61e0/",
                    "uuid": "80498624-4b6a-4c23-8db3-0402b8bc61e0"
                },
                {
                    "resource_uri": "/api/2.0/jobs/57cd32c3-8969-4286-b4f3-d8e4132648db/",
                    "uuid": "57cd32c3-8969-4286-b4f3-d8e4132648db"
                },
                {
                    "resource_uri": "/api/2.0/jobs/e4ff1f15-d0ee-4717-89a1-2c0ad024391c/",
                    "uuid": "e4ff1f15-d0ee-4717-89a1-2c0ad024391c"
                },
                {
                    "resource_uri": "/api/2.0/jobs/a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2/",
                    "uuid": "a3e72cd9-bcf3-4810-b2b8-40c0db8ba2d2"
                },
                {
                    "resource_uri": "/api/2.0/jobs/aa4a37ed-a657-4544-bcea-35c8b87f7382/",
                    "uuid": "aa4a37ed-a657-4544-bcea-35c8b87f7382"
                },
                {
                    "resource_uri": "/api/2.0/jobs/9ecbc462-7fae-4b23-aabb-5a6d05c8c106/",
                    "uuid": "9ecbc462-7fae-4b23-aabb-5a6d05c8c106"
                },
                {
                    "resource_uri": "/api/2.0/jobs/4b97a416-bef0-4d9c-ab19-715fb228f7f6/",
                    "uuid": "4b97a416-bef0-4d9c-ab19-715fb228f7f6"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ff128f6d-c51b-4d01-8932-14be8748f9dd/",
                    "uuid": "ff128f6d-c51b-4d01-8932-14be8748f9dd"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bd4b2465-09b7-4e12-8cfa-7d8779281ee7/",
                    "uuid": "bd4b2465-09b7-4e12-8cfa-7d8779281ee7"
                },
                {
                    "resource_uri": "/api/2.0/jobs/03ecdbd7-9799-48c8-aa71-06d072d04b3f/",
                    "uuid": "03ecdbd7-9799-48c8-aa71-06d072d04b3f"
                },
                {
                    "resource_uri": "/api/2.0/jobs/871aa701-cda8-47f6-b10b-df6d33f87cc9/",
                    "uuid": "871aa701-cda8-47f6-b10b-df6d33f87cc9"
                },
                {
                    "resource_uri": "/api/2.0/jobs/23f8bdc6-5ab4-477c-8f7c-7bdb5952b483/",
                    "uuid": "23f8bdc6-5ab4-477c-8f7c-7bdb5952b483"
                },
                {
                    "resource_uri": "/api/2.0/jobs/10f675b4-aff6-4158-98ab-16a285f8705e/",
                    "uuid": "10f675b4-aff6-4158-98ab-16a285f8705e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/bcc7eddf-cecd-455c-86e9-64425b26b39e/",
                    "uuid": "bcc7eddf-cecd-455c-86e9-64425b26b39e"
                },
                {
                    "resource_uri": "/api/2.0/jobs/16589be9-9bfb-4991-b75a-268a0f5c629d/",
                    "uuid": "16589be9-9bfb-4991-b75a-268a0f5c629d"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ad6b508e-882f-4554-962e-10df50a46e51/",
                    "uuid": "ad6b508e-882f-4554-962e-10df50a46e51"
                },
                {
                    "resource_uri": "/api/2.0/jobs/ebd647a3-6ad1-4ae9-8bfb-b618072f0545/",
                    "uuid": "ebd647a3-6ad1-4ae9-8bfb-b618072f0545"
                },
                {
                    "resource_uri": "/api/2.0/jobs/799c758f-2e68-44ab-9808-04271937331b/",
                    "uuid": "799c758f-2e68-44ab-9808-04271937331b"
                }
            ],
            "licenses": [],
            "media": "disk",
            "meta": {
                "description": "",
                "install_notes": ""
            },
            "mounted_on": [],
            "name": "atom-sol",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 12348030976,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        },
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_1",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/0d5ef2eb-93f2-44fe-99fa-f85279dffa2b/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1073741824,
            "snapshots": [],
            "status": "unmounted",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "0d5ef2eb-93f2-44fe-99fa-f85279dffa2b"
        }
    ]
}

The server is recursively deleted with all attached drives with media type disk:

DELETE /api/2.0/servers/efc6cc26-3706-4638-910e-e8b9ef45173f/?recurse=disks HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

After DELETE of the server, only drives with media type disk attached to the server are deleted. CDROMs are left intact:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 3
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/cf0af312-aeeb-4f3a-bf00-426d13126edf/",
            "status": "unmounted",
            "uuid": "cf0af312-aeeb-4f3a-bf00-426d13126edf"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/3d504199-6bac-4612-a19e-691c9c6c6728/",
            "status": "unmounted",
            "uuid": "3d504199-6bac-4612-a19e-691c9c6c6728"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/",
            "status": "unmounted",
            "uuid": "b9a2e66c-81d1-4de3-aac0-b6f2bde806f1"
        }
    ]
}

Server Runtime and Server Details

GET /servers/{uuid}/

Gets detailed information for server identified by server_uuid.

Status Codes:
  • 200 – no error

If the server is started the definition includes a runtime attribute. The runtime object contains information on, when the server was started, and runtime information about the server NICs, such as how much traffic went through the interface and what are the dynamic IPs assigned to the NIC. The NIC runtime is also available in the NIC definition of the running server.

Example request:

GET /api/2.0/servers/4e31777b-92b5-4633-9f31-c28443a63cfd/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [
        {
            "boot_order": 1,
            "dev_channel": "0:0",
            "device": "virtio",
            "drive": {
                "resource_uri": "/api/2.0/drives/39e4c24b-980a-49ce-968c-1f32b124b23f/",
                "uuid": "39e4c24b-980a-49ce-968c-1f32b124b23f"
            },
            "runtime": {
                "io": {
                    "bytes_read": 512,
                    "bytes_written": 0,
                    "count_flush": 0,
                    "count_read": 1,
                    "count_written": 0,
                    "total_time_ns_flush": 0,
                    "total_time_ns_read": 606050,
                    "total_time_ns_write": 0
                }
            }
        }
    ],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:b8:8c:17:fe:19",
            "model": "virtio",
            "runtime": {
                "interface_type": "public",
                "io": {
                    "bytes_recv": 0,
                    "bytes_sent": 0,
                    "packets_recv": 0,
                    "packets_sent": 0
                },
                "ip_v4": {
                    "resource_uri": "/api/2.0/ips/94.26.101.149/",
                    "uuid": "94.26.101.149"
                },
                "ip_v6": null
            },
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/4e31777b-92b5-4633-9f31-c28443a63cfd/",
    "runtime": {
        "active_since": "2015-03-19T13:52:51+00:00",
        "nics": [
            {
                "interface_type": "public",
                "io": {
                    "bytes_recv": 0,
                    "bytes_sent": 0,
                    "packets_recv": 0,
                    "packets_sent": 0
                },
                "ip_v4": {
                    "resource_uri": "/api/2.0/ips/94.26.101.149/",
                    "uuid": "94.26.101.149"
                },
                "ip_v6": null,
                "mac": "22:b8:8c:17:fe:19"
            }
        ]
    },
    "smp": 1,
    "status": "running",
    "tags": [],
    "uuid": "4e31777b-92b5-4633-9f31-c28443a63cfd",
    "vnc_password": "testserver"
}

Server Actions

Start

POST /servers/{uuid}/action/?do=start

Starts a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/d0ae4a09-13d5-4af2-aa12-56935035adef/action/?do=start HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "start",
    "result": "success",
    "uuid": "05221547-3036-44c4-9418-0f0239992459"
}

Warning

Servers have some default network restrictions, applied depending on your user state. Please refer to the default restrictions section the Firewall policies documentation

Stop

POST /servers/{uuid}/action/?do=stop

Stops a server with specific UUID. This action is equivalent to pulling the power cord of a physical server. For more graceful shutdown see ACPI Shutdown.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/d0ae4a09-13d5-4af2-aa12-56935035adef/action/?do=stop HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "stop",
    "result": "success",
    "uuid": "05221547-3036-44c4-9418-0f0239992459"
}

ACPI Shutdown

POST /servers/{uuid}/action/?do=shutdown

Sends an ACPI shutdowns to a server with specific UUID for a minute. If the VM OS handles ACPI shutdown events (equivalent to pressing the power button), it will shutdown gracefully. As some operating systems don’t always handle single ACPI event the shutdown is sent every second for a minute. While the shutdown is initiated, the server is put into status stopping to prevent interfering actions. If after a minute the server has not powered off during this minute the status is returned to running to allow the user to Stop it. If the server shuts down successfully during the one minute period it will be switched to stopped status.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/d79eeec6-9cc5-4131-9f04-36961c267a74/action/?do=shutdown HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "shutdown",
    "result": "success",
    "uuid": "d79eeec6-9cc5-4131-9f04-36961c267a74"
}

Start in a separate availability group

It is possible to hint the system which servers are preferred to run on separate hardware host. See Starting Servers in a Different Availability Group (Start Avoid).

Open Serial Console Connection

POST /servers/{uuid}/action/?do=open_console

Each server has a virtual serial device, which is tunneled to a TCP socket. The serial device is seen as /dev/ttyS0 or COM1 on most operating systems. If your OS supports it, you can configure a serial console on this virtual serial port, which might be more conviniet to use than VNC, as it generally uses less bandwidth and allows you to copy-paste in the virtual terminal.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/e27eacc3-0f20-4c1f-9f7d-eac705bf2d02/action/?do=open_console HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "open_console",
    "console_url": "csconsole://direct.wdc.cloudsigma.com:43835",
    "result": "success",
    "uuid": "7a3a67e0-93e4-46db-a4a2-c0f886987dc0"
}

The return object contains console_url formatted as csconsole://<cs-domain>:<port>. You can connect to it using telnet:

telnet direct.zrh.clousigma.com 12345

Before being connected to the actual serial console, the server’s vnc_password is required to prevent unauthorized access.

Most telnet clients start in line mode, which usually interferes with standard unix shells and programs, so they need to be set to character mode. It is advisable to enter your password in line mode and then change to character mode. Refer to your telnet client manual. On some clients that is done by pressing ctrl+] (^]) and then entering “mode character” at the prompt.

Close Serial Console Connection

POST /servers/{uuid}/action/?do=close_console

Closes a VNC tunnel to a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/e27eacc3-0f20-4c1f-9f7d-eac705bf2d02/action/?do=close_console HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "close_console",
    "result": "success",
    "uuid": "7a3a67e0-93e4-46db-a4a2-c0f886987dc0"
}

Cloning

POST /servers/{uuid}/action/?do=clone
statuscode 202:Action accepted, execution is proceeding.

Clones a server. Does cascading clone of server drives, i.e. all disk drives attached to the server are cloned and attached to the new server. CDROM drives attached to the clone source are attached to the clone. IPs of the cloned server are set to DHCP. All other properties of the clone are equal to the original.

The optional body can contain a name attribute, which will be the name of the newly-cloned server and/or random_vnc_password boolean attribute which if set will generate a new vnc password for the new server.

Example clone source server:

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/ee11b9d1-e837-4f27-91a4-d1ae4c621bd1/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "ee11b9d1-e837-4f27-91a4-d1ae4c621bd1",
    "vnc_password": "testserver"
}

Example clone request:

POST /api/2.0/servers/ee11b9d1-e837-4f27-91a4-d1ae4c621bd1/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "test_cloned_server_name",
    "random_vnc_password": true
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [
        {
            "resource_uri": "/api/2.0/jobs/559a2a76-df4a-4c0d-8449-979576b2c354/",
            "uuid": "559a2a76-df4a-4c0d-8449-979576b2c354"
        }
    ],
    "mem": 536870912,
    "meta": {},
    "name": "test_cloned_server_name",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/2d69b07c-c7a3-4e25-88d2-c7055217e1fb/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "2d69b07c-c7a3-4e25-88d2-c7055217e1fb",
    "vnc_password": "QR5coR4V"
}

Note

The name of the cloned drive will be changed using the clone naming strategy set in the profile. See Clone naming for more information

Cloning with Drives on Different Storage (Avoid)

It is possible to hint the system which drives are preferred to be on separate physical storage host. See Creating Drives in a Different Availability Group (Create/Clone Avoid). I

Server NIC Configurations

The network interfaces are configured in the “nics” attribute. For more information on configuring network interfaces check Server Network Interfaces section.

Here is an example of defining a network interface with a dynamically assigned IP (for brevity only the “nics” attribute of the definitions is shown):

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "nics": [
        {
            "vlan": "10619300-edda-42ba-91e0-7e3df0689d00"
        }
    ]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "nics": [
        {
            "boot_order": null, 
            "firewall_policy": null, 
            "ip_v4_conf": null, 
            "ip_v6_conf": null, 
            "mac": "22:39:8a:48:33:36", 
            "model": "virtio", 
            "runtime": null, 
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/", 
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        }
    ]
}

Availability groups

It is possible to query which servers share common hardware hosts. See Server availability groups.

Public keys

The pubkeys attribute contains a list of keypairs references. The attached pubkeys are available in the server context, and can be used by scripts inside the VM, such as cloudinit, to set the public keys automatically. See the attaching keys to a server section.

Server State Diagram

_images/ServerStates.png

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "context": {
            "default": true,
            "help_text": "Enable guest context serial device",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "cpu": {
            "default": null,
            "help_text": "Server's CPU Clock speed measured in MHz",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "cpu_model": {
            "choices": [
                "kvm64"
            ],
            "default": null,
            "help_text": "Choose the virtual CPU model, for mitigating compatibility issues between the guest operating system and the underlying host's CPU. If not specified, all of the hypervisor's CPU capabilities are passed directly to the virtual machine.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "cpu_type": {
            "choices": [
                "amd",
                "intel",
                "sparc_t4",
                "sparc_t5"
            ],
            "default": "amd",
            "help_text": "Specify the CPU type of the host on which this virtual server should run",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "cpus_instead_of_cores": {
            "default": false,
            "help_text": "Expose server SMPs as separate CPUs, instead of cores of a single CPU.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "drives": {
            "default": [],
            "fields": {
                "boot_order": {
                    "default": null,
                    "help_text": "Drive boot order",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "dev_channel": {
                    "default": null,
                    "help_text": "Device channel in format {controller:unit} ex. 0:1, 0:2, etc. Keep in mind that there are limits based on emulation type - for example ide can have up to 2 controllers, 2 units each.",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "device": {
                    "choices": [
                        "ide",
                        "virtio"
                    ],
                    "default": null,
                    "help_text": "Device emulation type",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "drive": {
                    "default": null,
                    "help_text": "Drive UUID",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                },
                "runtime": {
                    "default": "No default provided.",
                    "fields": {
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "bytes_written": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_flush": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "count_written": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_flush": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_read": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                },
                                "total_time_ns_write": {
                                    "default": 0,
                                    "help_text": "Integer data. Ex: 2673",
                                    "readonly": false,
                                    "required": true,
                                    "type": "integer"
                                }
                            },
                            "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Attached drive's runtime information",
                    "readonly": true,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "List of attached Drives to server",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "enable_numa": {
            "default": false,
            "help_text": "Expose NUMA topology to the server.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "hv_relaxed": {
            "default": false,
            "help_text": "Improve performance of Windows servers.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "hv_tsc": {
            "default": false,
            "help_text": "Improves performance of Windows servers with the trade off that the servers cannot be live migrated.",
            "readonly": false,
            "required": false,
            "type": "boolean"
        },
        "hypervisor": {
            "choices": [
                "kvm",
                "solaris-kz"
            ],
            "default": "kvm",
            "help_text": "Specify hypervisor on which this server should run",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "jobs": {
            "default": "No default provided.",
            "help_text": "Background jobs related to this resource",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "mem": {
            "default": null,
            "help_text": "Server's Random Access Memory measured in bytes",
            "readonly": false,
            "required": true,
            "type": "integer"
        },
        "meta": {
            "default": {},
            "help_text": "User assigned meta information for this server",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of server",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "nics": {
            "default": [],
            "fields": {
                "boot_order": {
                    "default": null,
                    "help_text": "Device boot order",
                    "readonly": false,
                    "required": false,
                    "type": "integer"
                },
                "firewall_policy": {
                    "default": null,
                    "help_text": "Firewall policy",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "ip_v4_conf": {
                    "default": null,
                    "fields": {
                        "conf": {
                            "choices": [
                                "dhcp",
                                "static",
                                "manual"
                            ],
                            "default": "dhcp",
                            "help_text": "Configuration type",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "ip": {
                            "default": null,
                            "help_text": "An IP address reference. Only used in 'static' IP configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Public IPv4 configuration",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "ip_v6_conf": {
                    "default": null,
                    "fields": {
                        "conf": {
                            "choices": [
                                "dhcp",
                                "static",
                                "manual"
                            ],
                            "default": "dhcp",
                            "help_text": "Configuration type",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "ip": {
                            "default": null,
                            "help_text": "An IP address reference. Only used in 'static' IP configuration type",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        }
                    },
                    "help_text": "Public IPv6 configuration",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                },
                "mac": {
                    "default": null,
                    "help_text": "MAC address of the server NIC",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "model": {
                    "choices": [
                        "ne2k_isa",
                        "i82551",
                        "i82557b",
                        "i82559er",
                        "ne2k_pci",
                        "pcnet",
                        "rtl8139",
                        "e1000",
                        "virtio"
                    ],
                    "default": null,
                    "help_text": "Model of NIC",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "runtime": {
                    "default": "No default provided.",
                    "fields": {
                        "interface_type": {
                            "choices": [
                                "public",
                                "private"
                            ],
                            "default": null,
                            "help_text": "Type of interface",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_recv": {
                                    "default": 0,
                                    "help_text": "Bytes received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "bytes_sent": {
                                    "default": 0,
                                    "help_text": "Packets received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_recv": {
                                    "default": 0,
                                    "help_text": "Bytes sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_sent": {
                                    "default": 0,
                                    "help_text": "Packets sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                }
                            },
                            "help_text": "NIC runtime Input and Output data",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v4": {
                            "default": null,
                            "help_text": "Public IPv4 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v6": {
                            "default": null,
                            "help_text": "Public IPv6 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        }
                    },
                    "help_text": "NIC runtime information",
                    "readonly": true,
                    "required": false,
                    "type": "related"
                },
                "vlan": {
                    "default": null,
                    "help_text": "UUID of the private VLAN",
                    "readonly": false,
                    "required": false,
                    "type": "related"
                }
            },
            "help_text": "The list of nics attached to this server",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "owner": {
            "default": null,
            "help_text": "UUID of the server owner",
            "readonly": true,
            "required": true,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "pubkeys": {
            "default": [],
            "help_text": "List of SSH keys for that server",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "requirements": {
            "default": [],
            "help_text": "A collection of special requirements for this server",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "runtime": {
            "default": "No default provided.",
            "fields": {
                "active_since": {
                    "default": "No default provided.",
                    "help_text": "Datetime object representing the exact time the guest was started.",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "nics": {
                    "default": [],
                    "fields": {
                        "interface_type": {
                            "choices": [
                                "public",
                                "private"
                            ],
                            "default": null,
                            "help_text": "Type of interface",
                            "readonly": false,
                            "required": true,
                            "type": "string"
                        },
                        "io": {
                            "default": null,
                            "fields": {
                                "bytes_recv": {
                                    "default": 0,
                                    "help_text": "Bytes received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "bytes_sent": {
                                    "default": 0,
                                    "help_text": "Packets received on this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_recv": {
                                    "default": 0,
                                    "help_text": "Bytes sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                },
                                "packets_sent": {
                                    "default": 0,
                                    "help_text": "Packets sent from this interface",
                                    "readonly": false,
                                    "required": false,
                                    "type": "integer"
                                }
                            },
                            "help_text": "NIC runtime Input and Output data",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v4": {
                            "default": null,
                            "help_text": "Public IPv4 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "related"
                        },
                        "ip_v6": {
                            "default": null,
                            "help_text": "Public IPv6 configuration",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        },
                        "mac": {
                            "default": null,
                            "help_text": "MAC address of this NIC",
                            "readonly": false,
                            "required": false,
                            "type": "string"
                        }
                    },
                    "help_text": "The list of this server's NICs runtime",
                    "readonly": false,
                    "required": true,
                    "type": "related"
                }
            },
            "help_text": "Runtime information of the guest",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "smp": {
            "default": null,
            "help_text": "Symmetric Multiprocessing (SMP) i.e. number of CPU cores",
            "readonly": false,
            "required": false,
            "type": "integer"
        },
        "status": {
            "default": "No default provided.",
            "help_text": "Status of the guest.",
            "readonly": true,
            "required": false,
            "type": "string"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of server",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "vnc_password": {
            "default": null,
            "help_text": "VNC Password to connect to server",
            "readonly": false,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

KVM Servers

Device channel

Device channel is used to specify the controller number and unit number for each attached drive. This is used so every time you reboot your virtual machine, the drive remains on the same place in your guest OS ( ex: /dev/sdc ) You specify the channel in the following format - {controller}:{unit} with the following limits for ide and virtio device types:

  • ide - 0:0, 0:1, 1:0, 1:1 ( total of 4 drives, max 2 units per controller, i.e 0-1)
  • virtio - 0:0, ..., 0:5, ..., 1:0, etc ( total of 1024 drives, max 6 units per controller i.e 0-5)

Open VNC Tunnel

POST /servers/{uuid}/action/?do=open_vnc

Server’s console (virtual keyboard, mouse, and display) is exposed to the user through the VNC protocol. The open_vnc call opens a VNC tunnel to the server. The returned object contains a vnc_url specifying the endpoint to which to connect the VNC client. The password for the VNC connection is specified in the vnc_password field on the server definition. Note that the tunnel is not closed until reboot, so if you prefer you can close is using the close_vnc action.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Note

VNC URL will be different each time you close/open the tunnel.

Example request:

POST /api/2.0/servers/42cb8991-a39a-4ed3-b549-efd6a1dedd48/action/?do=open_vnc HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "open_vnc",
    "result": "success",
    "uuid": "80751bc7-37cc-48c1-bb08-fd04b46090bf",
    "vnc_url": "vnc://direct.lvs.cloudsigma.com:42714"
}

Close VNC Tunnel

POST /servers/{uuid}/action/?do=close_vnc

Closes a VNC tunnel to a server with specific UUID.

Status Codes:
  • 202 – Action accepted, execution is proceeding.

Example request:

POST /api/2.0/servers/42cb8991-a39a-4ed3-b549-efd6a1dedd48/action/?do=close_vnc HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "close_vnc",
    "result": "success",
    "uuid": "80751bc7-37cc-48c1-bb08-fd04b46090bf"
}

Advanced settings

On every server configuration there are a few advanced options you can setup.

{
    "cpus_instead_of_cores": false, 
    "enable_numa": false, 
    "hv_relaxed": false, 
    "hv_tsc": false
}
  • cpus_instead_of_cores:
    • Type: true/false
    • Description: selects whether the SMP is exposed as cores of a single CPU or separate CPUs. This should be set to false for Windows, because there are license requirements for multiple CPUs.
  • enable_numa:
    • Type: true/false
    • Description: This option exposes the NUMA/CPU topology of the hypervisor to the virtual machine. It boosts performance for NUMA aware applications. The option should be set to true for servers with SMP bigger than 6, since this is the number of cores we have per NUMA node on the hypervisor. If set to true, cpus_instead_of_cores should also be set to true for Linux, because some Linux distributions do not support multiple NUMA nodes on multple CPU cores, but only on multiple CPUs.
  • hv_relaxed
    • Type: true/false
    • Description: Relax constraints on timers. This improves the behavior of VMs running Windows.
  • hv_tsc:
    • Type: true/false
    • Description: Enables more precise timers for Windows. This boost performance for timer specific code.

Warning

hv_relaxed and hv_tsc should be set to false for VMs running Linux

Solaris Kernel Zone Servers

Hypervisor specific notes

Solaris kernel zones require at least one bootable drive to be attached and it will only try to boot from drives that have a bootindex value. Additionally, they do not support booting over the network.

Due to their nature, they do not support different drivers for network interfaces or drives. Additionally, the drive channel is ignored and the order of drives in the definition is passsed to the guest.

Example

Example request:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "cpu_type": "intel",
            "drives": [
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": "4756666c-3755-4a55-9848-07f9bb403ba4"
                }
            ],
            "hypervisor": "solaris-kz",
            "mem": 1073741824,
            "name": "test_skzserver",
            "nics": [
                {
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "model": "virtio"
                }
            ],
            "vnc_password": "testskzserver"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "intel",
            "cpus_instead_of_cores": false,
            "drives": [
                {
                    "boot_order": 1,
                    "dev_channel": "0:0",
                    "device": "virtio",
                    "drive": {
                        "resource_uri": "/api/2.0/drives/4756666c-3755-4a55-9848-07f9bb403ba4/",
                        "uuid": "4756666c-3755-4a55-9848-07f9bb403ba4"
                    },
                    "runtime": null
                }
            ],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "solaris-kz",
            "jobs": [],
            "mem": 1073741824,
            "meta": {},
            "name": "test_skzserver",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:ec:5c:9b:18:e1",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/0dcd3592-702a-4fd0-9b69-0b2407f95222/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "0dcd3592-702a-4fd0-9b69-0b2407f95222",
            "vnc_password": "testskzserver"
        }
    ]
}

Keypairs (SSH keys)

The keypairs resource can be used to store ssh keys, for use with your servers. You have the choice whether to store only the public key or the full public-private key keypair. Keys attached to a server appear in the server context, and for OS images, which support cloudinit, they can also be automatically added to authorized_keys on a reboot. If you omit the public and private keys when creating a keypair, a new rsa keypair will be automatically generated for you. Having the private key in your profile will allow for using a web-based ssh client. It is also useful if your OS does not have key generation tools installed.

If the user has turned on two-factor authentication, the keypairs resource is protected with one time password. In order to make key management for servers easier (and not requiring OTP), there is pubkeys resource, which is a read-only version of the keypairs resource. The pubkeys objects are identical to keypairs except for the fact that they do not contain the private key, and have a has_private_key attribute instead of private_key, which indicates whether the private key was set.

Creating a keypair

POST /keypairs/

You have three choices when creating a keypair:

  • Provide both private and public key
  • Provide only a public key, in which case the private key will remain empty
  • Provide no public, neither private key, in which case a new pair will be generated for you

Here is an example of providing both pairs:

POST /api/2.0/keypairs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_pub",
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXwIBAAKCAIEAuU+9enw6UwtDPW+82mLpkEKitLn1drCWuLvWdhdeCfMUCVAL\nZAQiQZkzwyD6xxav2uRyzP3P7nLGuFD/bF+xqL6qq/7KvqzKb79SfLYEOLrpLAwB\n+8AXgNtLXZHEE0KTBIGpT9I/RKXfeWZAmQWSigTREjuuAOQcby7tb4IgoisCAwEA\nAQKCAIBl9QORUqxcaIP0V3gWx/kt0BvpR69QQFSNC3wxuSWaX82UWiAKRWP7p6kd\nIRYZV9glnS+0rakrzqabXqVKIVSDTbHT7SbP56t2pjfi/se/zTQeWYz65AGIfJV4\nNa8e3qN6ivMjTHHgvjbpFIjnFyO5O173deQFSWZXH+l9DuGGUQJBANQVYJqqqGn9\nNCzdLaEnA/+FIPI2jNXxvSqWUr8JolOXaBqxJYUJZNaVFq80NspYJuNHkCaddq1K\nTBe5CEk1FXcCQQDfrysb6prO9Caduozt2ms1R06bVw1i89mn48RFylOHRLNm8Xm/\n+bQErrzFbrPgln7pTmszeBZdpP5ejVOqzxXtAkEAy4ikiGqFbApa+z9cng7icGOk\nJa+iY2Q25dsUGFC3nz9r4knltxI32xODjKswdeo5j99LATQXA+GMuyuRPyiZqwJA\nOXMD32eh2wVZ5ajECVLPth9aUQtKpN98R2J4RnRwf41lhkr+ug+n7Iv0b8C+8i+0\n6Lb7UXzGQcbejeo+UuBdAQJBAMY5mf78YtmOW4i2kPYkS8wsjr9IE1ewUKezBSjj\nTHHog0pafFboifN/aFoO/jL1v7+8XLZ+uZwx5hPQ1L9fzO8=\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC5T716fDpTC0M9b7zaYumQQqK0ufV2sJa4u9Z2F14J8xQJUAtkBCJBmTPDIPrHFq/a5HLM/c/ucsa4UP9sX7Govqqr/sq+rMpvv1J8tgQ4uuksDAH7wBeA20tdkcQTQpMEgalP0j9Epd95ZkCZBZKKBNESO64A5BxvLu1vgiCiKw=="
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "fingerprint": "79:20:0b:49:72:11:b1:bc:df:73:94:09:3d:f8:90:71",
            "grantees": [],
            "meta": {},
            "name": "test_pub",
            "permissions": [],
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXwIBAAKCAIEAuU+9enw6UwtDPW+82mLpkEKitLn1drCWuLvWdhdeCfMUCVAL\nZAQiQZkzwyD6xxav2uRyzP3P7nLGuFD/bF+xqL6qq/7KvqzKb79SfLYEOLrpLAwB\n+8AXgNtLXZHEE0KTBIGpT9I/RKXfeWZAmQWSigTREjuuAOQcby7tb4IgoisCAwEA\nAQKCAIBl9QORUqxcaIP0V3gWx/kt0BvpR69QQFSNC3wxuSWaX82UWiAKRWP7p6kd\nIRYZV9glnS+0rakrzqabXqVKIVSDTbHT7SbP56t2pjfi/se/zTQeWYz65AGIfJV4\nNa8e3qN6ivMjTHHgvjbpFIjnFyO5O173deQFSWZXH+l9DuGGUQJBANQVYJqqqGn9\nNCzdLaEnA/+FIPI2jNXxvSqWUr8JolOXaBqxJYUJZNaVFq80NspYJuNHkCaddq1K\nTBe5CEk1FXcCQQDfrysb6prO9Caduozt2ms1R06bVw1i89mn48RFylOHRLNm8Xm/\n+bQErrzFbrPgln7pTmszeBZdpP5ejVOqzxXtAkEAy4ikiGqFbApa+z9cng7icGOk\nJa+iY2Q25dsUGFC3nz9r4knltxI32xODjKswdeo5j99LATQXA+GMuyuRPyiZqwJA\nOXMD32eh2wVZ5ajECVLPth9aUQtKpN98R2J4RnRwf41lhkr+ug+n7Iv0b8C+8i+0\n6Lb7UXzGQcbejeo+UuBdAQJBAMY5mf78YtmOW4i2kPYkS8wsjr9IE1ewUKezBSjj\nTHHog0pafFboifN/aFoO/jL1v7+8XLZ+uZwx5hPQ1L9fzO8=\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC5T716fDpTC0M9b7zaYumQQqK0ufV2sJa4u9Z2F14J8xQJUAtkBCJBmTPDIPrHFq/a5HLM/c/ucsa4UP9sX7Govqqr/sq+rMpvv1J8tgQ4uuksDAH7wBeA20tdkcQTQpMEgalP0j9Epd95ZkCZBZKKBNESO64A5BxvLu1vgiCiKw==",
            "resource_uri": "/api/2.0/keypairs/fdd6fbba-644b-49d8-9324-ff6589179da3/",
            "tags": [],
            "uuid": "fdd6fbba-644b-49d8-9324-ff6589179da3"
        }
    ]
}

Here is an example of providing only a public key:

POST /api/2.0/keypairs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_another_pub",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDFGtYDl+/Oua9uBXqwcbE84QUBBbDdMMzaZ6MAGg1Bmus9VEW0P8kK6npZ0SaUnB2xRrBNwCv0Q0uZBJ70UicgsrhBjCXIVa7K6yQYrFzMxfN8saNAjJvGDdWGSvcMxJdpYwXiOQhFan36eJCCwQjni7I538Ii9chPD8/tyJcBIw=="
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "fingerprint": "e8:ee:43:72:38:09:6d:1e:8e:46:9e:76:80:a3:0a:01",
            "grantees": [],
            "meta": {},
            "name": "test_another_pub",
            "permissions": [],
            "private_key": null,
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDFGtYDl+/Oua9uBXqwcbE84QUBBbDdMMzaZ6MAGg1Bmus9VEW0P8kK6npZ0SaUnB2xRrBNwCv0Q0uZBJ70UicgsrhBjCXIVa7K6yQYrFzMxfN8saNAjJvGDdWGSvcMxJdpYwXiOQhFan36eJCCwQjni7I538Ii9chPD8/tyJcBIw==",
            "resource_uri": "/api/2.0/keypairs/6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244/",
            "tags": [],
            "uuid": "6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244"
        }
    ]
}

Here is an example of creating an autogenerated pair:

POST /api/2.0/keypairs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_name"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
            "grantees": [],
            "meta": {},
            "name": "test_name",
            "permissions": [],
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
            "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
            "tags": [],
            "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
        }
    ]
}

Listing, Getting, Updating, Deleting

List keypairs:

GET /keypairs/
GET /api/2.0/keypairs/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "fingerprint": "8c:71:a2:f0:bc:a4:45:66:a8:59:77:6d:80:d5:a0:89",
            "grantees": [],
            "meta": {},
            "name": "ala",
            "permissions": [],
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEqQIBAAKCAQEAvROcpJ/0T5iZUzfRydsJI4zCbuQAfGH3Bl/biggPY1atLqzf\niz6lctY8wsz2sYts9OQomtCB/xtMPfUjHZpLg1EP4/hfP1NCWtsIbIiDYKrzNEFg\nApSO1AkqBZ8tVL2gpPUuSdaK5P3lPjkbt43dgnThIyMvNoi0g7ngC6L6s960JvBq\nuamOvd8wVaW/VpbyZrKqRwvmsMH1pGErhSAeErImOdwM8wtCddLS3O4nxfts06py\nEcGhupvH8lph9q+jKJxpg7whUkOJyZoMN1XgDvtRFbz9PvlxqP0SOecEHP+4yCOg\nDcJa69LSFFxmlSog9BitCv5qRFwrvKGsMYcesQIDAQABAoIBAQCYBufhend/dIx7\n3BsDuemMOwavEQbO/BoadwLX5okw76WKLRgFJxby0g3C9/i3Ywr1kWqQqGyOCY3x\nF2TnzYNAD/K985vqF/D3irwoQE+ab3njn1kqWfbJyKCQKp/RTjOXz0gruKSvYPJt\naI+/tALSfVX04bp5l8vFSrQ5xw7bhiiFifATuDStVLSzzmEli6Pbne4mcKIXiReu\nK1OlSKPF9SbCxCcEvEhUhQqs7U/N+sEYmUSQ/q8rNdolWQD0c/EGn2RF0siNolxp\nylo5c7E/LvwgTW6DLYaEZDgORnYHEwiaG7YxJAuFFPoQNFIjoGEF5wKOGL/kKtVr\npyriY/k9AoIAgQDRKEf+B+SLO/P/rPP7CCCIh4tR9uXl6hbnEp40sx5AomZmIwfy\nZGRp+iIN3YhM2XQ96fb47Lgc4AsDUHKt+9ASqJWWn0f06sbaaVsTfKpxVuI1kPsh\nGVpuOqwQCnXFyTvvirrdTlAw32hOzl1VVL0bL57MsAkpmjHnqsEqYTpIhwKCAIEA\n52wIL3RMT6bGjfx/PMsyTOa9AFSLzsjvoOt1HjyC0v7fhZ3vGfwJSnEQXf7R31um\njA0yoSjyX7uyXYRvUlL8aibqoKw19U0WmwAKj9VCOdf7IFnd6WqcisZACq4IjcZU\nTE6ev3MqxAbdmz4dVPvz4GvqseQ39bktmIHEVkH3hQcCggCAKOx/wZWbwx507GbT\nyh9Z9jzHJr9vViAKYSYEbH1LgwwDiyJ5kJTSDOZTOXFKFPdLRj38A9KVZ5jyrrBT\n7/TgTnZL5o+9zY8OX3fTySlQVCLS2fZHHL/QMNcsCWtyhcONBZ6YV2rWR+m+iATa\nwDJ3WdVkddpPwKMZ9qEzcG5bsAsCggCBANUJBDf7DUy9sEaAy/iA7ZsRRaeKLPF8\n0+sFFdlxxtTJP6bXDoaTF1Jp5rFApJ7C1fxTIeptsUEjnjysb3YPYsGtdYvXPAzG\nnCqvzQk/PinVgx3y3G/FbrnpaobqUoGAs5VTQpvnPtUZpOMGOSZEkepkLbb46fLQ\nNwMPYlgtfdf9AoIAgEEbKzsfgWN72TIdSO7ZsYCdpy4vq9EqNMIYyplY4ue1Ogn+\nGlN6UM60S/+MF0uu+KKa3KBjFD+kZCyM90IESw9rshzRceaXtEetk8Z5kOIKGznt\noyCsfrxJbKn3qbH+zM0HDVEfGCiMmIpB2l/DShQjCRGyPAL7OG0GEDw9uQI6\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC9E5ykn/RPmJlTN9HJ2wkjjMJu5AB8YfcGX9uKCA9jVq0urN+LPqVy1jzCzPaxi2z05Cia0IH/G0w99SMdmkuDUQ/j+F8/U0Ja2whsiINgqvM0QWAClI7UCSoFny1UvaCk9S5J1ork/eU+ORu3jd2CdOEjIy82iLSDueALovqz3rQm8Gq5qY693zBVpb9WlvJmsqpHC+awwfWkYSuFIB4SsiY53AzzC0J10tLc7ifF+2zTqnIRwaG6m8fyWmH2r6MonGmDvCFSQ4nJmgw3VeAO+1EVvP0++XGo/RI55wQc/7jII6ANwlrr0tIUXGaVKiD0GK0K/mpEXCu8oawxhx6x",
            "resource_uri": "/api/2.0/keypairs/186106ac-afb5-40e5-a0de-6f0feba5a3d5/",
            "tags": [],
            "uuid": "186106ac-afb5-40e5-a0de-6f0feba5a3d5"
        },
        {
            "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
            "grantees": [],
            "meta": {},
            "name": "test_name",
            "permissions": [],
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
            "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
            "tags": [],
            "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
        }
    ]
}

Get a single keypair:

GET /keypairs/{uuid}/
GET /api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
    "grantees": [],
    "meta": {},
    "name": "test_name",
    "permissions": [],
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
    "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
    "tags": [],
    "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
}

Update a kypair:

PUT /keypairs/{uuid}/
PUT /api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
    "grantees": [],
    "meta": {},
    "name": "new_name",
    "permissions": [],
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
    "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
    "tags": [],
    "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
    "grantees": [],
    "meta": {},
    "name": "new_name",
    "permissions": [],
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
    "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
    "tags": [],
    "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
}

Delete a keypair:

DELETE /keypairs/{uuid}/
DELETE /api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Pubkeys resource

In order to access just the public keys without the need for OTP, you can use the pubkeys resource. Instead of a private key it contains an attribute has_private_key which indicates whethre the private key was set.

For example creating an autogenerated keypair:

POST /api/2.0/keypairs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_name"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "fingerprint": "99:1e:71:ea:d1:43:80:55:14:ca:27:5c:64:69:3b:10",
            "grantees": [],
            "meta": {},
            "name": "test_name",
            "permissions": [],
            "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpwIBAAKCAQEAs4068mFSGTm025oanVSpityZji/2S3A0jRJW1ku47cd+pRBl\nj9k2c2zC4zPBL2EeY8RNMrN/RqLIBU0LsH9LZ6m7QeFVwg2H0SWdh4joFzzcLRkk\n8shvx54l26Ahac1Owh8yERnyum1mbo4VIpJjBUx2Xd6HukXDIvBbW/fxe3KO7rML\nNStkxACSuRmGX+UptMc1M0B3wdpHmGEsLiJn7Rs1CM8gQS6iI88Eywf+usdaHMzf\n8w2sjC7wmlKfYNKUwnQoUCMhwo646JCdE672584OXdmG+aqO9rNcxhbtiViojLrk\ncbLtsHIdn4lUvU5dOx/iUL+H5vRvdHwTpHZaYwIDAQABAoIBAAadFyTCbPG87GqC\nXKSa77vLsGRKY/oXYfgoSsaN93vas1GFLxiDWbwar3sK9vy1yRbHrkhF0FRbvp5j\nXiDcL3zcBafBkxUYxn3vssPBSTtB5KJMoM3IkEV8D8ztMw3goBwKZh+3Ive2++Tq\nmuCxH7CcRmfiwIEd/LgWvma+1UhEuisw2y9F+m9Xl4TRwt34utyyVcjKDPH146W9\ne2ZyFwAcvDOTA8oI+txgA57m284QqHo04YHZdbPN3ovPBNwpfKCpNjneab91fTXX\nX48RY7O1MpDdvbE4l3ELptJq/E74xRsmsZziwRVAV0X6Eb6B2s/0xvKG2/+eDZz7\n1c/gG/ECggCBAMx6111Xtptw93dNZpYBHGNoulh+jn9p8RLIrbpOCncZ0v7EMdV1\n8TYgEDQ0n5TuUx501jWKTNbvoXyTUsAUkvA7VyyH2o8UTtqPgRi8ShB+DePZmRt8\nCwHzjUo86N4BnD6rcfFlFvQMzHRcAmvLrkMtkImgQHFHHh/JjMDjweYdAoIAgQDg\nyn8qWgueIPphlLW6vP9oL+01dHKU3oDlhtUME6/cOwZtzex4tRmx3NbIN/lpfRS7\ndVczIjwcGwHbWi/yeS0bSTK8QEMZYBEi7Qqzzdr0uCF9OjKTDPhZTKFQdeZLjtU4\neFGQeBpjQzRYojEKZNYL3NJF4v7tNw5i28aEM6tafwKCAIB17RJvfrqNguT1JOpY\n8GMS4b82ciZ0TQD/OEUZAREAByCsVTH4TYDDGlK+COtP1PKSygcP8abG/oQ/eCdt\nJ3Bmo5Ju2BqwEaI4YjKttUlxoYEZOtEWDL+8bF27xsz13C/j5LRd51MJhKgVI0sy\nJ9FkZM7K0GTZ743r/yzxwWh98QKCAIBTQKv4M4E5/1y75yenEXhGTfm8YnRNTlrO\npzEgV+o51mJ7KFj8G5Z4mSGy5Ygp2XlkNAEnnvZEMnxtkOlRFC/wexufPO2c6Edw\nd/oOvZ7qI4fDqVoxvAv+hrL36bJxKWUulOEgcFrViH5KlUc0YkQkAJSf7YIcuNdL\nJbpQHBLKYQKCAIBj9rEmDdnGqoseRMLZPXduUHdv6bXhmsw9jVIlB088sg19ZSW/\nng4UvesHB3vSylZIEYhEdnIBqlc84XeXEMRSYVZ9x+RMDP5jJ44Uq52iGYarIhwg\nW8m4q0JmhnPM0M3fRQxbIXOaUQvDgjGuLlzDCY9JjiEfyTgMJATNKK2O4Q==\n-----END RSA PRIVATE KEY-----\n",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCzjTryYVIZObTbmhqdVKmK3JmOL/ZLcDSNElbWS7jtx36lEGWP2TZzbMLjM8EvYR5jxE0ys39GosgFTQuwf0tnqbtB4VXCDYfRJZ2HiOgXPNwtGSTyyG/HniXboCFpzU7CHzIRGfK6bWZujhUikmMFTHZd3oe6RcMi8Ftb9/F7co7usws1K2TEAJK5GYZf5Sm0xzUzQHfB2keYYSwuImftGzUIzyBBLqIjzwTLB/66x1oczN/zDayMLvCaUp9g0pTCdChQIyHCjrjokJ0Trvbnzg5d2Yb5qo72s1zGFu2JWKiMuuRxsu2wch2fiVS9Tl07H+JQv4fm9G90fBOkdlpj",
            "resource_uri": "/api/2.0/keypairs/b4fa47cf-f929-4dde-b77a-ea1d326862bd/",
            "tags": [],
            "uuid": "b4fa47cf-f929-4dde-b77a-ea1d326862bd"
        }
    ]
}

Results in a corresponding pubkeys object with hast_private_key, which is true:

GET /api/2.0/pubkeys/fdd6fbba-644b-49d8-9324-ff6589179da3/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "fingerprint": "79:20:0b:49:72:11:b1:bc:df:73:94:09:3d:f8:90:71",
    "grantees": [],
    "has_private_key": true,
    "meta": {},
    "name": "test_pub",
    "permissions": [],
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC5T716fDpTC0M9b7zaYumQQqK0ufV2sJa4u9Z2F14J8xQJUAtkBCJBmTPDIPrHFq/a5HLM/c/ucsa4UP9sX7Govqqr/sq+rMpvv1J8tgQ4uuksDAH7wBeA20tdkcQTQpMEgalP0j9Epd95ZkCZBZKKBNESO64A5BxvLu1vgiCiKw==",
    "resource_uri": "/api/2.0/pubkeys/fdd6fbba-644b-49d8-9324-ff6589179da3/",
    "tags": [],
    "uuid": "fdd6fbba-644b-49d8-9324-ff6589179da3"
}

Creating a keypair with only a public key:

POST /api/2.0/keypairs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_another_pub",
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDFGtYDl+/Oua9uBXqwcbE84QUBBbDdMMzaZ6MAGg1Bmus9VEW0P8kK6npZ0SaUnB2xRrBNwCv0Q0uZBJ70UicgsrhBjCXIVa7K6yQYrFzMxfN8saNAjJvGDdWGSvcMxJdpYwXiOQhFan36eJCCwQjni7I538Ii9chPD8/tyJcBIw=="
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "fingerprint": "e8:ee:43:72:38:09:6d:1e:8e:46:9e:76:80:a3:0a:01",
            "grantees": [],
            "meta": {},
            "name": "test_another_pub",
            "permissions": [],
            "private_key": null,
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDFGtYDl+/Oua9uBXqwcbE84QUBBbDdMMzaZ6MAGg1Bmus9VEW0P8kK6npZ0SaUnB2xRrBNwCv0Q0uZBJ70UicgsrhBjCXIVa7K6yQYrFzMxfN8saNAjJvGDdWGSvcMxJdpYwXiOQhFan36eJCCwQjni7I538Ii9chPD8/tyJcBIw==",
            "resource_uri": "/api/2.0/keypairs/6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244/",
            "tags": [],
            "uuid": "6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244"
        }
    ]
}

Results in a corresponding pubkeys object with hast_private_key, which is false:

GET /api/2.0/pubkeys/6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "fingerprint": "e8:ee:43:72:38:09:6d:1e:8e:46:9e:76:80:a3:0a:01",
    "grantees": [],
    "has_private_key": false,
    "meta": {},
    "name": "test_another_pub",
    "permissions": [],
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDFGtYDl+/Oua9uBXqwcbE84QUBBbDdMMzaZ6MAGg1Bmus9VEW0P8kK6npZ0SaUnB2xRrBNwCv0Q0uZBJ70UicgsrhBjCXIVa7K6yQYrFzMxfN8saNAjJvGDdWGSvcMxJdpYwXiOQhFan36eJCCwQjni7I538Ii9chPD8/tyJcBIw==",
    "resource_uri": "/api/2.0/pubkeys/6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244/",
    "tags": [],
    "uuid": "6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244"
}

Attaching pubkeys to a server

You can attach the keys to a server definition on the pubkeys attribute. They are made available to the VM OS via the server context.

Here is an example of doing that using the keys created in the above section:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "cpu_type": "amd",
            "drives": [],
            "hypervisor": "kvm",
            "mem": 1073741824,
            "name": "test_srv_test_pubkeys",
            "nics": [
                {
                    "ip_v4_conf": {
                        "conf": "dhcp"
                    },
                    "model": "virtio"
                }
            ],
            "pubkeys": [
                "fdd6fbba-644b-49d8-9324-ff6589179da3",
                "6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244"
            ],
            "vnc_password": "7b08b0f03aa840ff"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 1073741824,
            "meta": {},
            "name": "test_srv_test_pubkeys",
            "nics": [
                {
                    "boot_order": null,
                    "firewall_policy": null,
                    "ip_v4_conf": {
                        "conf": "dhcp",
                        "ip": null
                    },
                    "ip_v6_conf": null,
                    "mac": "22:30:3d:8a:b6:59",
                    "model": "virtio",
                    "runtime": null,
                    "vlan": null
                }
            ],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [
                {
                    "resource_uri": "/api/2.0/pubkeys/fdd6fbba-644b-49d8-9324-ff6589179da3/",
                    "uuid": "fdd6fbba-644b-49d8-9324-ff6589179da3"
                },
                {
                    "resource_uri": "/api/2.0/pubkeys/6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244/",
                    "uuid": "6d7db550-d1c5-4e3b-9c0a-e83f6a2b8244"
                }
            ],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/f400243b-7005-4222-b319-dff0a376c4ea/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "f400243b-7005-4222-b319-dff0a376c4ea",
            "vnc_password": "7b08b0f03aa840ff"
        }
    ]
}

Server Context

Server context is a way for the VM to get information on the way it was set-up, i.e. get it’s definition. Server context is communicated over a virtual serial port device, which on UNIX-like operating system would usually appear as /dev/ttyS1 and on Windows as COM2. The serial port device for server context is the second serial device attached to the VM, because some UNIX operating systems configure a serial console on the first serial port.

Having the server definition accessible by the VM can be useful in various ways. For example it is possible to easily determine from within the VM, which network interfaces are connected to public and which to private network. Another use is to pass some data to initial VM setup scripts, like setting the hostname to the VM name or passing ssh public keys through server metadata.

At first sight, it might be confusing with the presence of both ‘server context’ and ‘server metadata’. ‘server metadata’ is really a subset of ‘server context’. The ‘server metadata’ itself is a key-value store for user-defined data on a server definition. The ‘server context’ on the other hand is one step above. It includes the full server definition, as well as the server metadata, along with attached drives definitions.

Context schema

The server context has almost the same schema as the /server/<uuid>/detail/ API request schema. It differs in that it lacks owner, subscriptions, status, and runtime information. The other difference is that the drives attributes are expanded to the corresponding /drive/<uuid>/detail/ which also lacks owner and runtime information. There is also a global_context attribute, which contains context available on all servers (see drive edit).

Setting up the virtual serial port

The virtual serial port device in not connected to a hardware device on the other side, so setting serial port hardware settings, such as baud rate and parity bits, does not affect the actual communication. However on Unix-like operating systems it may be necessary to set up the virtual terminal connected to the serial device. In general it is advisable to use the terminal in raw mode so that all characters are received uninterpreted. It is also important to not echo back received responses, because the may fill up the receive buffer, which may eject pending requests.

To set-up the terminal to raw mode on most unix systems one needs to the following command:

stty -F /dev/ttyS1 raw -echo

It is also possible to use cooked mode terminal for checking data on command line using standard utilities such as echo, read, and cat. As all responses are followed by newline and an End of Transmission character (usually represented as ^D or "\0x04"), so setting the terminal to cooked mode would make it interpret the EOT character as an End-Of-File condition, which makes it possible to use read and cat on the terminal device file (/dev/ttyS1) to receive the response. To set up cooked mode use the following command:

stty -F /dev/ttyS1 cooked -echo

If the default EOF character is different on your terminal it may be necessary to change it using:

stty -F /dev/ttyS1 cooked -echo eol ^D

Server Context Protocol

Requesting the complete server context

There is a simple protocol to retrieve the server context from the serial device. To request the whole server context one needs to send two newlines enclosed between inequality signs (aka pointy brackets, angle brackets). The newline can be either CRLF or just LF. In most programming languages the string to send will look like "<\n\n>".

The resulting response is a single-line json string representing the definition of the VM followed by newline (line feed character) and and an End of Transmission character (usually represented as ^D or "\0x04"). On Unix-like operating systems, if the terminal is set to cooked mode it is possible that the EOT character is interpreted as End-Of-File and is not present in the response.

The example below is for a server with the following definition:

GET /api/2.0/servers/e0fcf2ae-020e-45e1-bf69-982b17da4b6a/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Request the complete server context using python

The best way to access the context is to use a serial port communication library from your favourite programming language. Below is an example using the Python programming language and the pySerial libraray:

#!/bin/env python

# This will work on python 2.6 and python 2.7

import serial;  # pySerial module is called 'serial'

s = serial.Serial("/dev/ttyS1")  # initialize a serial connection to '/dev/ttyS1'
s.write("<\n\n>")  # write an empty request to get the full context

context_str_raw = s.readline()  # read one line, which is the whole context as there are no newlines in the context
# Take the context string and remove any starting/trailing newlines and \x04 symbols
context_str = context_str_raw.strip("\x04\n")
print context_str  # print the context to stdout

Here the same code, as a one-liner, which can be executed directly in bash, or another shell:

python -c 'import serial; s = serial.Serial("/dev/ttyS1");s.write("<\n\n>"); print s.readline().strip("\x04\n")'

Example:

python -c 'import serial; s = serial.Serial("/dev/ttyS1");s.write("<\n\n>"); print s.readline().strip("\x04\n")'

Result:

{"cpus_instead_of_cores": false, "enable_numa": false, "meta": {"ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"}, "pubkeys": [], "requirements": [], "is_grey": false, "nics": [{"boot_order": null, "vlan": null, "ip_v4_conf": {"ip": {"uuid": "94.26.101.144", "tags": [], "nameservers": ["8.8.8.8"], "netmask": 24, "meta": {}, "gateway": "94.26.101.1"}, "conf": "dhcp"}, "mac": "22:81:c9:73:91:e4", "model": "virtio", "ip_v6_conf": null}], "smp": 1, "vnc_password": "1132f1963f9f47b4", "tags": [], "mem": 1073741824, "mem_perf_threshold": 0.0, "cpu_model": null, "drives": [{"device": "virtio", "dev_channel": "0:0", "drive": {"uuid": "ca360a3f-55e4-4b5f-92ba-ada83fca2940", "tags": [], "media": "disk", "name": "test_clone_test_guest_context", "storage_type": "dssd", "meta": {}, "allow_multimount": false, "licenses": [], "affinities": [], "size": 3221225472}, "boot_order": 1}], "hv_relaxed": false, "cpu_perf_threshold": 0.0, "uuid": "e0fcf2ae-020e-45e1-bf69-982b17da4b6a", "name": "test_srv_test_guest_context", "global_context": {}, "hypervisor": "kvm", "hv_tsc": false, "cpu_type": "amd", "cpu": 1000}

Request the complete server context using bash

It is also possible to issue the reques using just standard commands such as read, echo, and cat. Unfortunately that method is prone to errors because it breaks if there are escaped json values, such as "value contains quote: \"", so it is higly recommended to use a serial communication library, such as the python example above. Below is an example of making a request, reading the result, and printing it on Linux in the bash shell:

#!/bin/bash

# set the terminal to cooked mode:
stty -F /dev/ttyS1 cooked -echo eol ^D
# use -e to parse newline escapes, and -n to remove the trailing newline:
echo -en "<\n\n>" > /dev/ttyS1
# read with timeout of 3 seconds and print the value which is put in the variable READVALUE
read -t 3 READVALUE < /dev/ttyS1 && echo $READVALUE

Example:

Request command. Including a flushing read before the actual request with echo:

v=$(read -t 13 READVALUE < /dev/ttyS1 && echo $READVALUE & sleep 1; echo -en "<\n\n>" > /dev/ttyS1; wait %1); echo $v

Result:

{"cpus_instead_of_cores": false, "enable_numa": false, "meta": {"ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"}, "pubkeys": [], "requirements": [], "is_grey": false, "nics": [{"boot_order": null, "vlan": null, "ip_v4_conf": {"ip": {"uuid": "94.26.101.144", "tags": [], "nameservers": ["8.8.8.8"], "netmask": 24, "meta": {}, "gateway": "94.26.101.1"}, "conf": "dhcp"}, "mac": "22:81:c9:73:91:e4", "model": "virtio", "ip_v6_conf": null}], "smp": 1, "vnc_password": "1132f1963f9f47b4", "tags": [], "mem": 1073741824, "mem_perf_threshold": 0.0, "cpu_model": null, "drives": [{"device": "virtio", "dev_channel": "0:0", "drive": {"uuid": "ca360a3f-55e4-4b5f-92ba-ada83fca2940", "tags": [], "media": "disk", "name": "test_clone_test_guest_context", "storage_type": "dssd", "meta": {}, "allow_multimount": false, "licenses": [], "affinities": [], "size": 3221225472}, "boot_order": 1}], "hv_relaxed": false, "cpu_perf_threshold": 0.0, "uuid": "e0fcf2ae-020e-45e1-bf69-982b17da4b6a", "name": "test_srv_test_guest_context", "global_context": {}, "hypervisor": "kvm", "hv_tsc": false, "cpu_type": "amd", "cpu": 1000}

Requesting a partial server context or a single value

To request a part of the definition json one can provide a path in the request. The path contains strings or integers separated by a forward slash (/). To request only the part of the json which is the NICs definitoins one can request the path “/nics”. To request an element from a list value one can use an index in the path. Note that counting starts from 0. For example to get the defintion of the first network interface one can use the following path “/nics/0”.

If the value of pointed to the path is a leaf value (it does not contain a json object or alist), it is returned without the surrounding quotes so requesting <\nname\n> from a server named “myserver” would return:

myserver\n\0xd

and NOT:

"myserver"\n\0xd

Be advised that the returned strings won’t contain surrounding quotes but ASCII control characters will be backslash escaped. For example line-feed will become \n, carriage-return will become \r, and tab will become \t. Also there is no way to represent null json values so this will be converted to an empty string. Make sure that you parse the escaped characters if you need the original unescaped text in your scripts. An easy way to do it on UNIX-like OS is to use echo -e $READVALUE.

Examples:

python -c 'import serial; s = serial.Serial("/dev/ttyS1");s.write("<\nname\n>"); print s.readline().strip("\x04\n")'

Result:

test_srv_test_guest_context

Passing information to the VM

The most suitable place to store information for passing to the VM through the context interface is the server meta field, or drive meta. Check Objects’ metadata field for more information on editing the meta field.

For example in the server definition from above examples, the meta looks like:

{
    "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"
}

One can retrieve the ssh_public_key from the meta from within the VM using:

python -c 'import serial; s = serial.Serial("/dev/ttyS1");s.write("<\n/meta/ssh_public_key\n>"); print s.readline().strip("\x04\n")'

Result:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal

Note that there isn’t anything special about the ssh_public_key attribute of the metadata. It can be stored under any other key in the server metadata, as long as client software is aware where to look for it. It is also possible to store the key in one of the attached drives’ meta.

Global context

Global context can be used to hold server context information common to all user’s servers. Like meta field on servers, it can store arbitrary key-value pairs, but as the name suggests it is global for the user account, and the same for all servers.

Global context is centrally managed at the /global_context/ API url. Within the VM context it resides in the global_context attribute of the server server definition.

Get or update global context

GET /global_context/
POST /global_context/

Example:

Add a value to the global context.

POST /api/2.0/global_context/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "new_global_key": "new_global_val"
}

The resulting global context is:

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

{
    "new_global_key": "new_global_val"
}

Using the server from examples above, we can check the context from the server shell:

Request command:

python -c 'import serial; s = serial.Serial("/dev/ttyS1");s.write("<\n\n>"); print s.readline().strip("\x04\n")'

Result:

{"uuid": "e83c79b3-ef07-4b8e-968e-dff5c386a053", "requirements": [], "name": "test_server_renamed", "cpus_instead_of_cores": false, "tags": [], "mem": 1073741824, "nics": [{"boot_order": null, "vlan": null, "ip_v4_conf": {"ip": {"uuid": "162.213.38.123", "tags": [], "nameservers": ["69.194.139.62", "178.22.66.167", "178.22.71.56"], "netmask": 24, "meta": {}, "gateway": "162.213.38.1"}, "conf": "dhcp"}, "mac": "22:51:c1:18:7b:4a", "model": "virtio", "ip_v6_conf": null}], "enable_numa": false, "global_context": {"new_global_key": "new_global_val"}, "drives": [{"device": "virtio", "dev_channel": "0:0", "drive": {"uuid": "13168369-8450-4070-8909-444f56b747e8", "tags": [], "media": "disk", "name": "test_clone_1", "meta": {"description": "", "install_notes": ""}, "allow_multimount": false, "licenses": [], "affinities": [], "size": 12348030976}, "boot_order": 1}], "cpu_model": null, "hv_relaxed": false, "hv_tsc": false, "meta": {"another_key": "a value or something", "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCy4XpmD3kEfRZ+LCwFh3Xmqrkm7rSiDu8v+ZCTOA3vlNjmy/ZOc3vy9Zr+IhWPP4yipiApkGRsBM63tTgnxqUUn/WU7qkbBNktZBcs5p7Mj/zO4ZHkk4VoTczFzHlPGwuak2P4wTftEj7sU8IRutaAbMoKj4AMuFF50j4sIgF7P5b5FtTIM2b5HSW8BlDz10b67+xsj6s3Jv05xxbBs+RWj+v7D5yjMVeeErXoSui8dlHpUu6QOVKn8LLmdpxvehc6ns8yW7cbQvWmLjOICMnm6BXdVtOKWBncDq9FGLmKF3fUeZZPbv79Z7dyZs+xGZGMHbpaNHpuY9QhNS/hQ5D5 dave@hal"}, "smp": 1, "cpu": 1000, "vnc_password": "3022962f5d944b97"}

Notice how the value of the global_context changed:

{
    "global_context": {
        "new_global_key": "new_global_val"
    }
}

Server Network Interfaces

Private and Public Network Interfaces

There are three configurations for any one NIC that determines how that NIC behaves. Not all combinations of configuration are valid:

  • vlan: Private Network
  • ip_v4_conf: Public IP v4 Network, either static, DHCP, or manually assigned.
  • ip_v6_conf: Public IP v6 Network, either static, DHCP, or manually assigned.
Configurations Result
vlan ip_v4_conf ip_v6_conf  
True True True Error: Cannot assign all configs on a NIC
True True False Error: Cannot assign both Private and Public on a NIC
True False True Error: Cannot assign both Private and Public on a NIC
True False False Private network assigned
False True True Both IP v4 and v6 assigned
False True False Only IP v4 assigned
False False True Only IP v6 assigned
False False False No config assigned

IP Assignment for Public Interfaces

Assignment of IPs on private network interface is up to the user.

For public network interfaces it is possible to configure the way the address is assigned by setting the “conf” attribute on the ip_v4_conf or ip_v6_conf object:

“dhcp”:

The address is chosen by the system at boot time and assigned through DHCP. On each reboot the VM may get a different address. It is an error to specify the IP address for “conf”: “dhcp”. It is possible get the currently assigned dynamic IP of a NIC from the server runtime of a running server.

{
    "ip_v4_conf": {
        "conf": "dhcp"
    }
}
“static”:

The address is chosen and specified by the user. It is assigned to the NIC through DHCP and does not change between reboots. The “ip” attribute is mandatory and an IP address can be assigned from the addresses owned by the user.

{
    "ip_v4_conf": {
        "conf": "static", 
        "ip": "94.26.101.182"
    }
}
“manual”:

There is no address specified for the NIC, and the user has to specify the IP address from within the VM. When this setting is used, the NIC is allowed to use all IPs for which the user has subscription. This “conf” can be used to assign multiple IPs to the same NIC.

{
    "ip_v4_conf": {
        "conf": "manual"
    }
}

Note

The cloud firewall does not allow traffic to/from IPs which are not owned or not assigned to the VM. The only exception is for “manual” conf where the VM is allowed to use any of the IPs which are owned by the user (the user has a subscriptions for them).

MAC Addresses

Newly created NICs have their mac address randomly generated.

Note

All traffic from a MAC address different from the assigned by the system is stopped by the cloud firewall, so users should no attempt to change their MACs from within their VM.

In order to update a NIC definition, the definition should have its “mac” attribute filled in. If on “nics” list update a MAC address disappears from the list, the corresponding NIC is deleted. If a MAC appears in the new list, the corresponding nic is updated, and if no MAC is specified on a NIC, a new NIC is created. It is an error to attempt to specify a MAC address which was not previously in the “nics” list.

The order of NICs in the “nics” attribute is important, because it is also the order in which nics are presented to the VM. It is possible to rearrange NICs by rearranging their orded in the “nics” list.

NIC Models

The “model” attribute specifies the model of the emulated network card. It is recommended to use virtio, whenever possible (when drivers for virtio are available for the VM operating system).

Model Bus Speed Description
e1000 PCI 1Gb/s Intel Gigabit Ethernet
i82551 ? ? ?
i82557b ? ? ?
i82559er ? ? ?
ne2k_pci PCI 10Mb/s NE2000
pcnet ? ? ?
rtl8139 ? 10/100Mb/s Realtek Fast Ethernet
virtio PCI 1Gb/s Virtual High Performance Ethernet card (see Virtio)

Reference: Wikibooks QEMU/Devices/Network.

NIC Runtime

When a server is running, the server definition provides information on the currently assigned dynamic IP and the data traffic made through the NIC. See server runtime for more details.

Examples

Example 1 - Private Network assigned to server:

Definition with all other values default:

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "vlan": "10619300-edda-42ba-91e0-7e3df0689d00"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Result:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:39:8a:48:33:36",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Example 2 - Dynamic IP v4 (DHCP) assigned to NIC with e1000 model:

Definition with model set to ‘e1000’:

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "model": "e1000"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Result:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:76:35:14:21:7b",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Example 3 - Update nics:

Here is an example of a server with two nics:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:cd:d0:81:97:c8",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

In order to change the IP configuration of the NIC the definitions should have a MAC specified. Notice that in order to not delete the other NIC both NICs should be put in the request:

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": "94.26.101.182"
            },
            "ip_v6_conf": null,
            "mac": "22:cd:d0:81:97:c8",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

The result is:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/94.26.101.182/",
                    "uuid": "94.26.101.182"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:cd:d0:81:97:c8",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Example 4 - Rearrange nics:

In order to rearrange the NICs of the server definition from Example 3, the definition should just be updated with different order of NICs (NICs are recognized by their MAC):

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/94.26.101.182/",
                    "uuid": "94.26.101.182"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:cd:d0:81:97:c8",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

The resulting “nics” are:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": null,
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": {
                "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
                "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
            }
        },
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "static",
                "ip": {
                    "resource_uri": "/api/2.0/ips/94.26.101.182/",
                    "uuid": "94.26.101.182"
                }
            },
            "ip_v6_conf": null,
            "mac": "22:cd:d0:81:97:c8",
            "model": "e1000",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Notice that the private and public NICs changed order compared to Example 3.

Example 5 - Delete a NIC and change type of the other:

In order to change a NIC from private to public just remove the “vlan” field and “ip_v4_conf” field. This can also be combined with deletion of the other interface. Using the NICs from Example 4 here is how to delete the public NIC and change the private NIC to public:

PUT /api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "ip_v4_conf": {
                "conf": "dhcp"
            },
            "mac": "22:25:57:2a:dc:cc"
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "testServerAcc",
    "nics": [
        {
            "boot_order": null,
            "firewall_policy": null,
            "ip_v4_conf": {
                "conf": "dhcp",
                "ip": null
            },
            "ip_v6_conf": null,
            "mac": "22:25:57:2a:dc:cc",
            "model": "virtio",
            "runtime": null,
            "vlan": null
        }
    ],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3b3616df-16dc-4a49-bfca-5c2192e1f089/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "3b3616df-16dc-4a49-bfca-5c2192e1f089",
    "vnc_password": "testserver"
}

Notice that the NIC has the same MAC as the private NIC from Example 4, but is configured with DHCP.

Networking

VLAN

Allowed HTTP methods

Method Description
GET get / list VLANs
PUT edit VLANs meta

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /vlans/

Gets the list of VLANs to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/vlans/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ]
}

Detailed listing

GET /vlans/detail/
statuscode 200:no error

Example request:

GET /api/2.0/vlans/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "bottom_vlan_tag": null,
            "grantees": [],
            "meta": {},
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
            "servers": [],
            "subscription": {
                "id": 12,
                "resource_uri": "/api/2.0/subscriptions/12/"
            },
            "tags": [],
            "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
        }
    ]
}

Get single VLAN

GET /vlans/(uuid: vlan_uuid)/
statuscode 200:no error

Example request:

GET /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "bottom_vlan_tag": null,
    "grantees": [],
    "meta": {},
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
    "servers": [],
    "subscription": {
        "id": 12,
        "resource_uri": "/api/2.0/subscriptions/12/"
    },
    "tags": [],
    "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
}

Creating

New VLANs are created by buying a subscription. See Subscriptions.

Editing

Currently only VLAN meta field can be edited.

PUT /vlans/(uuid: vlan_uuid)/
statuscode 200:no error

Example request:

PUT /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    }
}

Example response:

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

{
    "bottom_vlan_tag": null,
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    },
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
    "servers": [],
    "subscription": {
        "id": 12,
        "resource_uri": "/api/2.0/subscriptions/12/"
    },
    "tags": [],
    "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
}

Metadata

It is possible to add arbitrary key-value data to a VLAN definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The VLAN will disappear when the subscription for it expires.

Attaching To servers

A VLAN can be attached to multiple servers. See Server Network Interfaces for more information on using VLANs in NIC configurations.

IPs

The IP object, contains the actual IP in it’s uuid attribute.

The list of IPs includes the IPs that are owned (subscribed to) by the user, and the IPs which are dynamically assigned to user’s servers. The owned IP’s are differentiated by dynamically received IPs by the fact that they have a subscription attached to them (their subscription attribute is not empty).

The detailed listing includes more information about the IP object, such as netmask, nameservers, and gateway which will be set on the NIC. The netmask value is in CIDR notation (/24 for a 255.255.255.0 mask). The nameservers attribute contains a list of DNS servers, which will be assigned through DHCP, and the gateway attribute contains the IP of the default gateway for the current IP.

Allowed HTTP methods

Method Description
GET get / list IPs
PUT edit IP metadata

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /ips/

Gets the list of IPSs to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/ips/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "uuid": "185.12.6.183"
        }
    ]
}

Detailed listing

GET /ips/detail/
statuscode 200:no error

Example request:

GET /api/2.0/ips/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "gateway": "185.12.6.1",
            "grantees": [],
            "meta": {},
            "nameservers": [
                "69.194.139.62",
                "178.22.66.167",
                "178.22.71.56"
            ],
            "netmask": 24,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "subscription": {
                "id": 7273,
                "resource_uri": "/api/2.0/subscriptions/7273/"
            },
            "tags": [],
            "uuid": "185.12.6.183"
        }
    ]
}

Get single IP

GET /ips/(uuid: ip_uuid)/
statuscode 200:no error

Example request:

GET /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {},
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Creating

New IPs are created by buying a subscription. See Subscriptions.

Editing

Currently only IP meta field can be edited.

PUT /ips/(uuid: ip_uuid)/
statuscode 200:no error

Example request:

PUT /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    }
}

Example response:

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

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    },
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Metadata

It is possible to add arbitrary key-value data to an IP definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The IP will disappear when the subscription for it expires.

Attaching To servers

An IP can be attached to a single server. To check whether IP is currently attached to a server look at the attribute on the object in the detailed listing or on single object retrieval. If server is empty, then the IP is not attached to a server and can be used for static IP configuration. See Server Network Interfaces for more information on using IPs in NIC configurations.

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put"
    ],
    "allowed_list_http_methods": "get",
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "bottom_vlan_tag": {
            "default": null,
            "help_text": "Integer data. Ex: 2673",
            "readonly": true,
            "required": false,
            "type": "integer"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "owner": {
            "default": null,
            "help_text": "VLAN owner",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "servers": {
            "default": [],
            "help_text": "Servers in this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "subscription": {
            "default": null,
            "help_text": "Subscription related to this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "VLAN UUID",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Firewall Policies

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /fwpolicies/

Gets the list of firewall policies to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Detailed listing

GET /fwpolicies/detail/

Gets a detailed list of firewall policies to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Create

POST /fwpolicies/

Creates a firewall policy.

Status Codes:
  • 201 – no error

Example request - minimal:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {}
    ]
}

Example response - minimal:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        }
    ]
}

This is the minimal data required to create a policy. It is blank one ( does not contain any rules ), but you can use it to attach it to a couple of servers and edit it later to match your needs.

Example request - full:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "My awesome policy",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23"
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24"
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp"
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55"
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp"
                }
            ]
        }
    ]
}

Example response - full:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

This is a more useful firewall policy. The rules are applied in the order they are stated.

Note

  • The IP and port fields support ”!” prefix, which specifies “NOT” ( ex. ”!192.168.1.1” ).
  • You can specify port ranges with ”:” ( ex. “1:1024” or ”!1:1024”)
  • The IP fields support subnet definition using the CIDR notation ( ex. “192.168.1.1/24” )

Editing

PUT /fwpolicies/{uuid}/

Update an existing firewall policy

Warning

Changes are applied every 30 seconds to all running servers with nics that have the policy attached.

Status Codes:
  • 200 – no error
Example policy:
{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "accept",
            "comment": "Allow SSH traffic to the VM from our office in Dubai",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": "172.66.32.0/24",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all other SSH traffic to the VM",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
            "direction": "in",
            "dst_ip": null,
            "dst_port": null,
            "ip_proto": "udp",
            "src_ip": "!172.66.32.55/32",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "!1:1024",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update request:
PUT /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}

Delete

DELETE /fwpolicies/{uuid}/

Delete a firewall policy

Warning

Only policies attached to servers in status stopped can be deleted.

Status Codes:
  • 204 – no content, object is deleted

Example request:

DELETE /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Attach policy to a server

Attaching a policy is done by specifying the policy uuid in the field firewall_policy on the server’s NIC, using the create or edit server calls

{
    "cpu": 1000, 
    "mem": 536870912, 
    "name": "FirewalledServer", 
    "nics": [
        {
            "firewall_policy": "abb98bcb-2d3c-4758-b59c-3094b54b5c9e", 
            "ip_v4_conf": {
                "conf": "dhcp", 
                "ip": null
            }, 
            "model": "virtio"
        }
    ], 
    "vnc_password": "testserver"
}

Warning

Firewall policies are only applied when attached to your server’s public network interfaces.

Default network restrictions

Depending on your account’s current state, the following network restrictions are applied to the public interfaces of your running servers:

  • regular - for REGULAR users:
    Running servers have limits set on originating broadcast and multicast traffic:
    • broadcast - limited to 5 packets/second with burst of 100
    • multicast - limited to 10 packets/second with burst of 100
  • no_outgoing_email - for new REGULAR users:

    Same as regular, but users cannot send emails from running servers.

  • trial - for TRIAL users:

    Applies regular restrictions plus running servers cannot open communication channels to ports 22, 23, 25, 7777, 43594, 43595 and 25565

  • guest - for GUEST and NEW users:

    Applies regular restrictions plus running servers can only send ICMP requests, request a DHCP IP, query a DNS server and send requests to TCP port 80 and 443 ( usually HTTP and HTTPS )

Please contact support if any of these restrictions breaks your workflow. You can check your effective network restrictions via the network_restrictions field on the user profile

Note

When converting from one user type to another, restrictions are automatically adjusted - no need to powercycle your running servers.

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "meta": {
            "default": {},
            "help_text": "User assigned meta information for this policy",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the firewall policy",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the policy",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "rules": {
            "default": [],
            "fields": {
                "action": {
                    "choices": [
                        "drop",
                        "accept"
                    ],
                    "default": null,
                    "help_text": "Action to be taken",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "comment": {
                    "default": null,
                    "help_text": "Optional rule comment",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "direction": {
                    "choices": [
                        "in",
                        "out",
                        "both"
                    ],
                    "default": null,
                    "help_text": "Packet direction",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "dst_ip": {
                    "default": null,
                    "help_text": "Destination IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "dst_port": {
                    "default": null,
                    "help_text": "Destination port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "ip_proto": {
                    "choices": [
                        "tcp",
                        "udp"
                    ],
                    "default": null,
                    "help_text": "IP protocol",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_ip": {
                    "default": null,
                    "help_text": "Source IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_port": {
                    "default": null,
                    "help_text": "Source port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                }
            },
            "help_text": "List of rules to be applied for this policy",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "servers": {
            "default": [],
            "help_text": "Servers which have nics with this policy applied",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the policy",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Tags

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /tags/

Gets the list of tags to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/tags/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        },
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

List single tag

GET /tag/(uuid: tag_uuid)/

Gets detailed information for tag identified by tag_uuid.

statuscode 200:no error

Example request:

GET /api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "vlans",
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
            "uuid": "f52db291-f754-4434-acac-77268cbac94f"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "ips",
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "uuid": "185.12.6.183"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

Creating

POST /tags/

Creates a new tag or multiple tags.

statuscode 201:object created

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "MyGroupOfThings"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        }
    ]
}

It is possible to add resources to a tag at creation time. Just specify their UUIDs the resources list:

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "TagCreatedWithResource",
            "resources": [
                "401d5ba4-6544-47ef-bf61-54bafe59d871",
                "3576136a-0a7e-4ece-8050-f2e408fbca96",
                "9214aa22-10db-4aff-92f2-779a043b13c7",
                "94.26.101.182",
                "10619300-edda-42ba-91e0-7e3df0689d00"
            ]
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

Editing

PUT /tags/{uuid}/

Edits a tag. It is possible to add or remove resources to a tag by replacing the resources list with a new one:

statuscode 200:no error

Example request:

PUT /api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "TagCreatedWithResource",
    "resources": [
        "a15d7e36-a392-4328-9cb1-616c9107eb26",
        "9214aa22-10db-4aff-92f2-779a043b13c7"
    ]
}

Example response:

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

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "snapshots",
            "resource_uri": "/api/2.0/snapshots/00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f/",
            "uuid": "00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

It is also possible to edit the tags on the resource itself by replacing the tags list. For example here is how to add a tag from a server:

Example request:

PUT /api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        "00f4ea87-891c-4ee9-a28f-21e25b96dd48",
        "c66a2113-be9b-4157-93ac-fb8c0e82087c"
    ],
    "uuid": "3576136a-0a7e-4ece-8050-f2e408fbca96",
    "vnc_password": "pass"
}

Example response:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/00f4ea87-891c-4ee9-a28f-21e25b96dd48/",
            "uuid": "00f4ea87-891c-4ee9-a28f-21e25b96dd48"
        },
        {
            "resource_uri": "/api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/",
            "uuid": "c66a2113-be9b-4157-93ac-fb8c0e82087c"
        }
    ],
    "uuid": "3576136a-0a7e-4ece-8050-f2e408fbca96",
    "vnc_password": "pass"
}

Deleting

DELETE /tags/{uuid}/

Deletes a single tag.

statuscode 204:No content, object deletion started.

Example request:

DELETE /api/2.0/tags/00f4ea87-891c-4ee9-a28f-21e25b96dd48/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Filter Servers, Drives, IPs or VLANs listing by tag

GET /tags/{uuid}/{resource_type}/

Lists the objects of the given resource_type which is one of ‘servers’, ‘drives’, ‘ips’, ‘vlans’.

statuscode 200:no error

Example request:

GET /api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "name": "test_server2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": {
                "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
            },
            "runtime": null,
            "status": "stopped",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        }
    ]
}

ACLs (Access Control Lists)

Access Control Lists (ACLs) can be used to grant permissions to another user to manage your resources. For example it is possible to permit another user to start or stop your servers or to allow another user to connect their servers to your private network (VLAN).

Permissions can be granted on servers, drives, network resources, and firewall policies. All of these resources support LIST and EDIT permissions, which respectively allow the grantee to see the resources when listing them and to edit resources. When a user is granted a LIST permission, this resource appears in the grantee’s resource list. For example granting LIST on a drive will make it appear in the list with grantees drives, when they make a GET request to /drives. Own resources can be differentiated from granted resources, by the owner field.

Some resources have additional permissions. Drives have ATTACH permission which allows another user to use the drive on their server. IPs, VLANs, and Firewall policies have ATTACH which will allow another user to assign these network resource to NICs on their server. Servers have START and STOP, OPEN_VNC permissions which allow another user to start or stop the server, or to open the server console through VNC. Note that ACLs may contain permissions that are not directly applicable on some resources, for example it is possible to to have STOP permission in an ACL on tag which refers only to drives. Drives and servers support CLONE permission, which allows cloning them to the grantee account. Note that in order to clone someone else’s server, you need CLONE permission on both the owner’s server, and on the attached non-cdrom drives. For cdrom drives, the user will need a ATTACH permission. The table below summarizes the permissions applicable to each resource:

Resource Permissions
Server LIST EDIT CLONE START STOP OPEN_VNC
Drive LIST EDIT CLONE ATTACH
IP, VLAN, Firewall Policy LIST EDIT ATTACH

ACLs are granted on tags, and apply for all the tagged resources. One ACL can be attached to multiple tags, and will apply to the set of all resources tagged by these tags. It is also possible to have multiple ACLs on a tag, in which case the permissions on the tagged resources are the combination of all ACLs rules.

Each ACL can have one or more grantee users. Each ACL object has a list of rules, which specify what permission are given by the ACL.

Permissions are not transferable to third parties, i.e. if you grant permission to someone, they can’t grant it to a third user. Only owners can grant permissions.

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /acls/

Gets the list of ACLs defined by the authenticated user.

statuscode 200:no error

Example request:

GET /api/2.0/acls/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 3
    },
    "objects": [
        {
            "grantees": [
                {
                    "email": "user2@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                    },
                    "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                }
            ],
            "meta": {},
            "name": "shared_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "resource_uri": "/api/2.0/acls/d29837e8-27ea-46e8-8b46-843d0df50a82/",
            "rules": [
                {
                    "permission": "ATTACH"
                },
                {
                    "permission": "OPEN_VNC"
                },
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                },
                {
                    "permission": "DELETE"
                },
                {
                    "permission": "START"
                },
                {
                    "permission": "STOP"
                },
                {
                    "permission": "CLONE"
                }
            ],
            "tags": [],
            "uuid": "d29837e8-27ea-46e8-8b46-843d0df50a82"
        },
        {
            "grantees": [
                {
                    "email": "user2@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                    },
                    "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                }
            ],
            "meta": {},
            "name": "shared_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "resource_uri": "/api/2.0/acls/58aa5d82-e890-44db-8cb8-fe3a2f159320/",
            "rules": [
                {
                    "permission": "ATTACH"
                },
                {
                    "permission": "OPEN_VNC"
                },
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                },
                {
                    "permission": "DELETE"
                },
                {
                    "permission": "START"
                },
                {
                    "permission": "STOP"
                },
                {
                    "permission": "CLONE"
                }
            ],
            "tags": [],
            "uuid": "58aa5d82-e890-44db-8cb8-fe3a2f159320"
        },
        {
            "grantees": [],
            "meta": {},
            "name": "test_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
            "rules": [],
            "tags": [],
            "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
        }
    ]
}

List Single ACL

GET /acls/(uuid: acl_uuid)/

Gets detailed information for an ACL identified by acl_uuid.

statuscode 200:no error

Example request:

GET /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "grantees": [
        {
            "email": "user@example.com",
            "resource_uri": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Creating

POST /acls/

Creates a new ACL.

statuscode 201:object created

Example request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [],
            "name": "test_acl",
            "rules": [],
            "tags": []
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [],
            "meta": {},
            "name": "test_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
            "rules": [],
            "tags": [],
            "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
        }
    ]
}

It is possible to define the grantees, tags and rules at creation time. Just specify their UUIDs the grantees list:

Example request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "name": "test_with_grantees",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ]
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    },
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "meta": {},
            "name": "test_with_grantees",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/49134280-55ed-4f4e-815c-85c6dd3ab322/",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ],
            "uuid": "49134280-55ed-4f4e-815c-85c6dd3ab322"
        }
    ]
}

Editing

PUT /acls/{uuid}/

Edits an ACL.

statuscode 200:no error

Example request:

PUT /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "grantees": [
        {
            "email": "user@example.com",
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Example response:

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

{
    "grantees": [
        {
            "email": "user@example.com",
            "resource_uri": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Deleting

DELETE /acls/{uuid}/

Deletes a single ACL.

statuscode 204:No content, object deletion started.

Example request:

DELETE /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Full Example of Sharing a Resource

First let’s create a tag which will be shared with another user:

Request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_TagOne"
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "test_TagOne",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "resources": [],
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ]
}

Let’s create a drive tagged with the new tag:

Request:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_drive_acl",
            "size": 2147483648,
            "tags": [
                "6d302107-fc0b-433a-99b1-9f2d3692eefc"
            ]
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 2147483648,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                }
            ],
            "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
        }
    ]
}

It is also possible to tag an existing drive. Since there is no ACL on the tag, the grantees attribute of the drive is empty.

Now let’s add the tag to an ACL. Notice that we may add several tags to the ACL:

Request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "name": "test_with_grantees",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ]
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    },
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "meta": {},
            "name": "test_with_grantees",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/49134280-55ed-4f4e-815c-85c6dd3ab322/",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ],
            "uuid": "49134280-55ed-4f4e-815c-85c6dd3ab322"
        }
    ]
}

If we get the drive definition we will see the grantee in the grantees attribute:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [
        {
            "permissions": [
                "EDIT",
                "LIST"
            ],
            "user": {
                "email": null,
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

Since there is an ACL on the the tag all resources created with this tag will be shared. For example if we create a server with the same tag, we see that it also shows grantees:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "test_server",
            "tags": [
                "6d302107-fc0b-433a-99b1-9f2d3692eefc"
            ],
            "vnc_password": "pass"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [
                {
                    "permissions": [
                        "EDIT",
                        "LIST"
                    ],
                    "user": {
                        "email": "user@example.com",
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    }
                }
            ],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/e97f8858-4c59-476f-b7e6-08ec2ec85582/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                }
            ],
            "uuid": "e97f8858-4c59-476f-b7e6-08ec2ec85582",
            "vnc_password": "pass"
        }
    ]
}

Permissions on Resources Attached to a Server

When updating another user’s server, the attached resources, such as drives, IPs, VLANs, or firewall policies, should be available for the server owner. This means that either the attached resource should be owned by the server owner, or the owner should be given ATTACH permission on the attached resource. For example if user A shares a server with EDIT permission to user B, and user B wants to attach their drive on the server, user B will have to grant ATTACH permission on the drive, so that the owner of the server is able to start it. Trying to attach a drive, on which there is no permission for the owner of the server will result in an error.

Recognizing Shared Resources and What Permissions Are Given on Them

Finding out which resources were shared with you

Resources shared with you appear in the resource list along with your own resources. In order to differentiate between owner, and shared with you resources you have to look at the owner field. If the user is the same as you, the resource is yours. Non-owned resource have their respective owner uuid in the owner field. The examples in the next two subsections show the same drive from the view point of permission grantor and grantee. Notice how owner is the same.

Finding what permissions are granted to you on a resource

While it is possible to follow the ACL-tag-resource graph to find out what are the resulting permissions on a resource, it hard to do so in a simple script. That is why each resource has permissions field, which shows the effective permissions the current user has on the resource. The permissions field is empty if the owner is the same as the current user.

For example if you get the definition of a drive shared by another user with you:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [
        "EDIT",
        "LIST"
    ],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

The definition includes non-empty permissions attribute:

{
    "permissions": [
        "EDIT", 
        "LIST"
    ]
}

In the next subsection there is an example of the same drive but from the view point of the drive owner.

Finding what permissions you have granted on a resource

As is the case with finding out what permissions are given to the current user, it also hard to find out, to find out what is granted to other users, as users may be granted different permissions through several ACLs referring to different tags. Therefore each resource has read-only field grantees. Each object of the grantees list contains a references to the grantee user, and a list of the permissions granted to them.

For example if you get the definition of your drive shared with another user:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [
        {
            "permissions": [
                "EDIT",
                "LIST"
            ],
            "user": {
                "email": null,
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

The definition includes non-empty grantees attribute:

{
    "grantees": [
        {
            "permissions": [
                "EDIT", 
                "LIST"
            ], 
            "user": {
                "email": null, 
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/", 
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ]
}

In the previous subsection there is an example of the same drive definition but from the view point of the permissions grantee.

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "post",
        "delete"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "grantees": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "meta": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "nullable": false,
            "readonly": false,
            "type": "dict",
            "unique": false
        },
        "name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "owner": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
            "nullable": false,
            "readonly": true,
            "type": "related",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "rules": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "ACL rules",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "tags": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        }
    }
}

Jobs

Jobs are used to track progress of long running tasks. A good example for a long running task is cloning of drives and servers. Depending on the current cloud resource usage and the users preferences ( Creating Drives in a Different Availability Group (Create/Clone Avoid) ), a drive clone operation can take a while.

Currently, the operations that create a job for tracking are:
  • Drive cloning
  • Server cloning

How it works

Drive cloning

After successfully starting a cloning operation via the API, you will receive the definition of the newly created drive. All drives have a jobs field, containing references to the all the long running tasks executed on them. The destination, since it is a newly created drive, references only 1 job - the currently running one. The source might contain more jobs, depending on how many times it was cloned. History of completed jobs is kept for 3 days. Older jobs are discarded.

Example clone request:

POST /api/2.0/drives/5d537d3f-22ea-4967-9ec0-32e837a8b390/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "media": "cdrom",
    "name": "test_drive_y",
    "size": 1207959631,
    "storage_type": "dssd"
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [
                {
                    "resource_uri": "/api/2.0/jobs/8b00acbb-889b-44a5-8a8d-dc3617a6145d/",
                    "uuid": "8b00acbb-889b-44a5-8a8d-dc3617a6145d"
                }
            ],
            "licenses": [],
            "media": "cdrom",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_y",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/03cb7ca7-ca07-4380-9071-c19260fbec59/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 1207975936,
            "snapshots": [],
            "status": "cloning_dst",
            "storage_type": "dssd",
            "tags": [],
            "uuid": "03cb7ca7-ca07-4380-9071-c19260fbec59"
        }
    ]
}

Using the the jobs field we could examine how is our cloning operation doing:

Example request:

GET /api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "children": [],
    "created": "2014-06-05T09:45:08.003595+00:00",
    "data": {
        "progress": 100
    },
    "last_modified": "2014-06-05T09:45:12.941760+00:00",
    "operation": "drive_clone",
    "resource_uri": "/api/2.0/jobs/6c809fa7-f797-4d0f-bbfb-b1b9ba737dda/",
    "resources": [
        "/api/2.0/drives/842e4c44-75a2-4d81-b812-9bc63d3be11e/",
        "/api/2.0/drives/963e3f37-572a-4e40-b70f-06f093ea7eb5/"
    ],
    "state": "success",
    "uuid": "6c809fa7-f797-4d0f-bbfb-b1b9ba737dda"
}

The interesting field here is data.progress. 100 means the job has finished.

Server cloning

Cloning a server is a bit more complex. Since servers generally contain drives, drives must also be cloned. That is why jobs support sub-jobs. When you send a clone server request, you receive the definition of the newly created server. It also has a jobs field containing the definitions of jobs and sub-jobs.

Example clone request:

POST /api/2.0/servers/ee11b9d1-e837-4f27-91a4-d1ae4c621bd1/action/?do=clone HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "test_cloned_server_name",
    "random_vnc_password": true
}

Example clone response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [
        {
            "resource_uri": "/api/2.0/jobs/559a2a76-df4a-4c0d-8449-979576b2c354/",
            "uuid": "559a2a76-df4a-4c0d-8449-979576b2c354"
        }
    ],
    "mem": 536870912,
    "meta": {},
    "name": "test_cloned_server_name",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/2d69b07c-c7a3-4e25-88d2-c7055217e1fb/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "2d69b07c-c7a3-4e25-88d2-c7055217e1fb",
    "vnc_password": "QR5coR4V"
}

Each job has children field with containing its sub-jobs. Note that each sub-job contains a children field, too. Meaning that a sub-job could have a sub-jobs, too.

Example request:

GET /api/2.0/jobs/4e1944be-a078-4ead-9d19-5f8823a84d42/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "children": [
        {
            "children": [],
            "created": "2014-06-05T09:50:06.771415+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T09:50:12.817209+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/5cf1a9e0-c019-4022-9ca5-08af64fa5105/",
            "resources": [
                "/api/2.0/drives/4f41610b-b73b-49f0-a7c8-2e5cd110eb31/",
                "/api/2.0/drives/eaa0b214-7f8c-446d-9d6b-1c106fcd9aba/"
            ],
            "state": "success",
            "uuid": "5cf1a9e0-c019-4022-9ca5-08af64fa5105"
        }
    ],
    "created": "2014-06-05T09:50:06.436976+00:00",
    "data": {
        "progress": 100
    },
    "last_modified": "2014-06-05T09:50:12.726357+00:00",
    "operation": "server_clone",
    "resource_uri": "/api/2.0/jobs/4e1944be-a078-4ead-9d19-5f8823a84d42/",
    "resources": [
        "/api/2.0/servers/3ee19ba9-fd1a-435b-9dbf-559d188fba90/",
        "/api/2.0/servers/810850e5-593b-4c21-af9e-a7cadac5b79c/"
    ],
    "state": "success",
    "uuid": "4e1944be-a078-4ead-9d19-5f8823a84d42"
}

List all jobs

All jobs can be listed and examined quite easily.

Example request:

GET /api/2.0/jobs/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 500
    },
    "objects": [
        {
            "children": [],
            "created": "2014-06-05T00:27:12.890638+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T00:27:17.537618+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/654b3d26-0b4a-41ff-b166-741adc9fcc61/",
            "resources": [],
            "state": "success",
            "uuid": "654b3d26-0b4a-41ff-b166-741adc9fcc61"
        },
        {
            "children": [],
            "created": "2014-06-04T13:48:30.146021+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:48:30.182588+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/2bb2929e-75e0-47ea-a7ef-88ae5c205bca/",
            "resources": [],
            "state": "success",
            "uuid": "2bb2929e-75e0-47ea-a7ef-88ae5c205bca"
        },
        {
            "children": [],
            "created": "2014-06-04T19:27:22.929792+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T19:27:28.194541+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/6d9eef6c-7b7b-412f-b0c8-b31acfa31b4b/",
            "resources": [],
            "state": "success",
            "uuid": "6d9eef6c-7b7b-412f-b0c8-b31acfa31b4b"
        },
        {
            "children": [],
            "created": "2014-06-05T05:20:06.808650+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T05:20:07.714198+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/f6f9423d-e239-48bf-b3e1-7eef57f41df5/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "f6f9423d-e239-48bf-b3e1-7eef57f41df5"
        },
        {
            "children": [],
            "created": "2014-06-04T09:44:52.922093+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T09:44:59.151935+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/51f17911-5db7-414a-b291-6a26d99c7af4/",
            "resources": [],
            "state": "success",
            "uuid": "51f17911-5db7-414a-b291-6a26d99c7af4"
        },
        {
            "children": [],
            "created": "2014-06-05T08:27:17.837077+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T08:27:22.451556+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/98be68fd-bc5b-42fd-ba42-2a197e7ad7bb/",
            "resources": [],
            "state": "success",
            "uuid": "98be68fd-bc5b-42fd-ba42-2a197e7ad7bb"
        },
        {
            "children": [],
            "created": "2014-06-04T10:37:08.377980+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T10:37:09.264198+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/b18335fd-5c38-43a0-a6ad-5e4150609317/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "b18335fd-5c38-43a0-a6ad-5e4150609317"
        },
        {
            "children": [],
            "created": "2014-06-04T14:47:51.859179+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T14:47:52.695159+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/ad1d412b-c51a-4cca-8ff9-81f5976471dd/",
            "resources": [
                "/api/2.0/drives/b9a2e66c-81d1-4de3-aac0-b6f2bde806f1/"
            ],
            "state": "success",
            "uuid": "ad1d412b-c51a-4cca-8ff9-81f5976471dd"
        },
        {
            "children": [],
            "created": "2014-06-04T12:08:35.939653+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T12:08:42.703768+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/9df9bccb-7a7a-4dc3-afbe-65614ae68828/",
            "resources": [],
            "state": "success",
            "uuid": "9df9bccb-7a7a-4dc3-afbe-65614ae68828"
        },
        {
            "children": [],
            "created": "2014-06-04T14:54:38.461484+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T14:54:44.194807+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/a71f63ac-940c-4b1b-b536-d98b7ebcdd1f/",
            "resources": [],
            "state": "success",
            "uuid": "a71f63ac-940c-4b1b-b536-d98b7ebcdd1f"
        },
        {
            "children": [],
            "created": "2014-06-04T10:15:45.013901+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T10:15:49.998849+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/b75498db-c630-4eae-9d4c-545b55c9f80c/",
            "resources": [],
            "state": "success",
            "uuid": "b75498db-c630-4eae-9d4c-545b55c9f80c"
        },
        {
            "children": [],
            "created": "2014-06-04T18:23:05.924797+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T18:23:07.201011+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/5ca591ad-4973-486f-865e-f649924ec8a9/",
            "resources": [],
            "state": "success",
            "uuid": "5ca591ad-4973-486f-865e-f649924ec8a9"
        },
        {
            "children": [],
            "created": "2014-06-04T13:22:41.878643+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:22:43.423951+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/1590cc04-a04d-47c6-aeea-e686fba11480/",
            "resources": [],
            "state": "success",
            "uuid": "1590cc04-a04d-47c6-aeea-e686fba11480"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-04T09:22:19.895663+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-04T09:22:21.182049+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/b3c8791a-7163-47fd-871d-ce7e74cdea22/",
                    "resources": [],
                    "state": "success",
                    "uuid": "b3c8791a-7163-47fd-871d-ce7e74cdea22"
                }
            ],
            "created": "2014-06-04T09:22:19.229671+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T09:22:21.090352+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/2f9fb6cb-d879-4bfb-afaa-0e7e9e8c8171/",
            "resources": [],
            "state": "success",
            "uuid": "2f9fb6cb-d879-4bfb-afaa-0e7e9e8c8171"
        },
        {
            "children": [],
            "created": "2014-06-05T09:45:29.984652+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T09:45:34.243982+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/a34a8179-f6c1-4a0c-8d96-f0d727017807/",
            "resources": [],
            "state": "success",
            "uuid": "a34a8179-f6c1-4a0c-8d96-f0d727017807"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-05T07:22:35.318791+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-05T07:22:36.437933+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/b548f9cc-9290-4c44-880a-688511964088/",
                    "resources": [],
                    "state": "success",
                    "uuid": "b548f9cc-9290-4c44-880a-688511964088"
                }
            ],
            "created": "2014-06-05T07:22:34.982635+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T07:22:36.341483+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/b60c32a1-6c07-4ba0-bffa-ef7a5b51829b/",
            "resources": [],
            "state": "success",
            "uuid": "b60c32a1-6c07-4ba0-bffa-ef7a5b51829b"
        },
        {
            "children": [
                {
                    "children": [],
                    "created": "2014-06-04T13:49:17.336222+00:00",
                    "data": {
                        "progress": 100
                    },
                    "last_modified": "2014-06-04T13:49:22.411035+00:00",
                    "operation": "drive_clone",
                    "resource_uri": "/api/2.0/jobs/2f575e30-3a2c-45a2-bc46-0dd6e73ba5bb/",
                    "resources": [],
                    "state": "success",
                    "uuid": "2f575e30-3a2c-45a2-bc46-0dd6e73ba5bb"
                }
            ],
            "created": "2014-06-04T13:49:16.986663+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T13:49:22.312955+00:00",
            "operation": "server_clone",
            "resource_uri": "/api/2.0/jobs/f1deb190-bb8f-4bc2-8013-ca6f69e4f481/",
            "resources": [],
            "state": "success",
            "uuid": "f1deb190-bb8f-4bc2-8013-ca6f69e4f481"
        },
        {
            "children": [],
            "created": "2014-06-04T16:31:41.972433+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T16:31:49.636223+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/eb93dffd-d457-471c-a812-f970c39aef65/",
            "resources": [],
            "state": "success",
            "uuid": "eb93dffd-d457-471c-a812-f970c39aef65"
        },
        {
            "children": [],
            "created": "2014-06-05T06:22:43.214966+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-05T06:22:44.265751+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/4a616d17-8e57-4756-b186-211539405d8d/",
            "resources": [],
            "state": "success",
            "uuid": "4a616d17-8e57-4756-b186-211539405d8d"
        },
        {
            "children": [],
            "created": "2014-06-04T15:29:03.093430+00:00",
            "data": {
                "progress": 100
            },
            "last_modified": "2014-06-04T15:29:09.318627+00:00",
            "operation": "drive_clone",
            "resource_uri": "/api/2.0/jobs/68609b60-7f6f-4890-8940-b9e0c8d2af77/",
            "resources": [],
            "state": "success",
            "uuid": "68609b60-7f6f-4890-8940-b9e0c8d2af77"
        }
    ]
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "children": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Background jobs, initiated by this job.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "created": {
            "blank": false,
            "default": "2014-06-05T09:46:41.793232+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "data": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Meta information related to this background job's execution.",
            "nullable": true,
            "readonly": false,
            "type": "object",
            "unique": false
        },
        "last_modified": {
            "blank": false,
            "default": "2014-06-05T09:46:41.793249+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "operation": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "resources": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Resources linked to this background job.",
            "nullable": true,
            "readonly": false,
            "type": "list",
            "unique": false
        },
        "state": {
            "blank": false,
            "default": "started",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        }
    },
    "filtering": {
        "state": 1
    },
    "ordering": [
        "-last_modified"
    ]
}

Objects’ metadata field

Objects, such as servers, drives, IPs, and VLANs have a meta field. This field can be used to store arbitrary information in key-value form. There is no predefined structure for the meta attribute, only keys are limited to 32 characters, and values should be strings. The Web UI uses the meta to store drive and server descriptions.

Note that the whole meta is updated completely so all old key-value pairs should be present in new definition, when updating meta, unless they are to be deleted.

Server’s metadata fields with special meaning

  • ssh_public_key is filled with the contents of the “SSH Key” field from the server’s properties section
  • cloudinit-user-data if available (and cloud-init 0.7.5 or newer is installed on the server) this field should contains valid cloud-init user data, that will be taken into account from the cloud-init
  • base64_fields contains comma-separated meta keys in the metadata that are encoded in base64. This feature is useful when a meta field has more than one lines of text. cloud-init (0.7.5 or newer) for example will automatically decode from base64 the contents of cloudinit-user-data if the name of the meta key is in base64_fields

Drive’s metadata fields with special meaning

When drive is cloned from the library we copy its Metadata to the new drive’s meta as:

  • os - drive’s operating system (e.g. GNU/Linux, BSD, Windows...)
  • arch - the architecture of the OS (e.g. 32-bit or 64-bit)
  • distribution - for GNU/Linux and BSD operating systems (e.g. Debian, Fedora, FreeBSD...)
  • version - distribution’s version (if any)
  • default_user - used in pre-installed images in order to specify the default user in the installed OS
  • install notes - used if the image is not pre-installed
  • url - URL to the official website of the OS
  • description - description of what the drive contains
  • image_type - type of the image on the drive (e.g. Live CD, Install CD, Pre-install)
  • category - states what this image is most suitable for (e.g. dbserver, webserver, router, networking, ...)
  • paid - this boolean field states if cloning the drive from the library is being charged
  • favorite - this boolean field states if this drive is among the most popular library drives

These fields with special meaning could still be changed and deleted (even created if missing) just like every other metadata field. Their content don’t change server/drive’s behavior nor any one of them is required.

Examples

Add meta to a drive:

To add meta to the following drive:

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

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

one has to use update call:

PUT /api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Response is:

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

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {
        "meta_key1": "value",
        "meta_key2": "value\nwith\nnew lines"
    },
    "mounted_on": [],
    "name": "test_drive_1",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 1073741824,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "5d3bb6d8-ce39-41e8-8742-2ba5af5ef2d0"
}

Update server meta, by removing one key and adding another:

Suppose a server is updated to have the following definition:

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

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key1": "value1",
        "meta_key2": "value2"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

In order to remove meta_key1, it is just skipped in the meta definition. Keeping meta_key2 with its value is achieved by redefining it, and new key meta_key3 is added by defining it:

PUT /api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

The final result is:

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

{
    "context": true,
    "cpu": 2000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {
        "meta_key2": "value2",
        "meta_key3": "value3"
    },
    "name": "test_server_updated",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/0dacaaf7-1ba8-451d-b135-8848e76381ee/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [],
    "uuid": "0dacaaf7-1ba8-451d-b135-8848e76381ee",
    "vnc_password": "updated_password"
}

Availability Grouping and Avoid

Resources requested by user are usually allocated to maximize performance. However this can lead to a situation, where user’s servers or drives share the same compute or storage host. This may be undesirable if the user attempts to build, a redundant setup, as in the unlikely event of hardware failure, servers sharing the same faild compute host will crash at the same time, and drives sharing the same failed storage host will become unavailable at the same time.

To improve the robustness of redundant setups, it is possible to hint the system, which resources are preferred to be on separated physical hosts. This is achieved through the Avoid functionality for starting servers, and for creating/cloning drives.

To check the grouping of running servers on compute hosts, or the grouping of drives on storage hosts, one can use the corresponding availaility_groups API calls.

Checking Availability Groups for Drives and Servers

The availability_groups call returns which resources are grouped on the same physical host.

Server availability groups

GET /servers/availability_groups/
statuscode 200:no error

Returns which running servers share same physical computes host. Returns an array containing arrays. Each inner array holds the UUIDs of servers which reside on same physical host. Non-running servers are not in the array as they are on any host.

GET /servers/availability_groups/{uuid}/
statuscode 200:no error

Queries which other servers share same physical host with the given one. Returns an array holding server UUIDs. The response includes also the UUID of the queried server. If the queried server is not running, the array will be empty.

Drives availability groups

GET /drives/availability_groups/
statuscode 200:no error

Returns which drives share same physical storage host. Returns an array containing arrays. Each inner array holds the UUIDs of drives which reside on same physical host.

GET /drives/availability_groups/{uuid}/
statuscode 200:no error

Queries which other drives share same physical storage host with the given one. Returns an array holding drives UUIDs. The response includes also the UUID of the queried drive.

Examples

Example request - servers availability:

GET /2.0/servers/availability_groups/ HTTP/1.1

Example response - servers availability:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
 [
    "313e73a4-592f-48cf-81c4-a6c079d005a5",
    "e035a488-8587-4a15-ab25-9b7343236bc9"
 ],
 [
    "313e73a4-592f-48cf-81c4-a6c079d005a5",
    "e035a488-8587-4a15-ab25-9b7343236bc9"
 ]
]

Example request - single-server availability:

GET /2.0/servers/availability_groups/313e73a4-592f-48cf-81c4-a6c079d005a5/ HTTP/1.1

Example response - single-server availability:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

[
 "313e73a4-592f-48cf-81c4-a6c079d005a5",
 "e035a488-8587-4a15-ab25-9b7343236bc9"
]

General Notes on Avoid Functionality

Avoid functionality is best effort. This means that requests containing avoid will succeed even if the avoid can not be satisfied and the requested resource ends in the same availability group as an avoid resource.

The order of the avoid argument UUIDs also specifies the order of preference to avoid. This means that avoid requests are satisfied from left to right, and if it is not possible to satisfy the full avoid list, only part of the aoid list will be satisfied and it will consist of UUIDs from the left part of the list. For example if there are only three hosts which can satisfy a request, and there are three avoid resources on these hosts, the newly request resource, will end up on the same host as the avoid resource which appears last in the list.

Avoid functionality may incur performance penalty. Specifying avoid for drives cloning and servers cloning, as it also clones attached drives, usually slows down significantly the clone operation, as the drive data has to be moved over the network between storage hosts.

Starting Servers in a Different Availability Group (Start Avoid)

POST /servers/{uuid}/action/?do=start&avoid={<server1_uuid>,<server2_uuid>,...}
statuscode 202:Action accepted, execution is proceeding.

Starts a server with specific UUID attempting to run it on a different physical infrastructure host from the other servers specified in the avoid argument which is a single server UUID or a comma-separated list of server UUIDs. This way the server specified by uuid may be run in a distinct availability group from the other listed servers.

Note that it might not always be possible to run a server in a different availability group, therefore the order of the avoid list also signifies the priority of avoiding other servers.

Example request:

POST /2.0/servers/2767d839-3a9d-4bd5-983b-676d1307438f/action/?do=start&avoid=bb1d5184-ebcc-4f33-867e-db654eb2d17e,dc3dd6d4-9b2d-44e6-bc40-e927950e8b77 HTTP/1.1

Creating Drives in a Different Availability Group (Create/Clone Avoid)

POST /drives/{uuid}/action/?do=clone&avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 202:Action accepted, execution is proceeding.
POST /drives/?avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 201:object created
POST /servers/{server_uuid}/action/?do=clone&avoid={<server_or_drive_uuid1>,<server_or_drive_uuid2>,...}
statuscode 202:Action accepted, execution is proceeding.

It is possible to hint the system which drives are preferred to be on separate physical storage hosts. Avoid can be specified on all drive creation operations: create, clone drive, and clone server. The value of the avoid GET parameter may contain a single or a comma-separated list of drive or server UUIDs. If a server uuid is in the avoid parameter, this is interpreted as avoiding all the drives attached to the server.

Note that it might not always be create a drive in a different availability group, therefore the order of the avoid list also signifies the priority of avoiding other drives. Since it is not possible to specify the order of drives attached to a server, if a drive from a server needs to be avoided with high priority, it may be specified in addition to the server UUID. For example avoid={important_to_avoid_drive_uuid},{server_uuid_to_which_drive_is_attached}.

Recipe for Creating a Redundant Server Backed by Separate Infrastructure

The best way to create a clone of server that does not share hardware with the original is to clone the origin server with avoiding itself, and to start the clone with avoiding the origing:

POST /2.0/servers/2767d839-3a9d-4bd5-983b-676d1307438f/action/?do=clone&avoid=2767d839-3a9d-4bd5-983b-676d1307438f HTTP/1.1

If the created server uuid is bb1d5184-ebcc-4f33-867e-db654eb2d17e:

POST /2.0/servers/bb1d5184-ebcc-4f33-867e-db654eb2d17e/action/?do=start&avoid=2767d839-3a9d-4bd5-983b-676d1307438f HTTP/1.1

Subscriptions

Statuses

Every subscription has a status associated with it:

  • active: A subscription that is currently being used, either because the current time is between its start or end date or because it was the subscription for depletable resources (traffic) that is currently being used.
  • inactive: A subscription that is not currently being used, either because its not active yet or because there is another depletable resource (traffic) subscription being used.
  • expired: A subscription that has either expired or that has been depleted.

Listing

GET /subscriptions/

Gets the list of subscriptions of the user.

param status:filters only subscriptions in that status. Can be one of active , inactive, expired, all, notexpired. Default is all.
param resource:a list (comma separated) of resources. One or more of: dssd, cpu, mem, tx, ip, vlan.
statuscode 200:no error

Example request:

GET /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "amount": "32212254720",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "14",
            "period": "365 days, 2:45:57.487493",
            "price": "0E-20",
            "remaining": "32212254720",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/14/",
            "start_time": "2014-08-26T09:14:02.512507+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "e067df3c-35c5-4327-927e-2ee52b6f796a",
            "was_billed": true
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "13",
            "period": "365 days, 2:46:06.019766",
            "price": "0E-20",
            "remaining": "1",
            "resource": "ip",
            "resource_uri": "/api/2.0/subscriptions/13/",
            "start_time": "2014-08-26T09:13:53.980234+00:00",
            "status": "active",
            "subscribed_object": "94.26.101.195",
            "uuid": "aa442254-08fa-4d36-b511-47d4aa3a303b",
            "was_billed": true
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "12",
            "period": "365 days, 2:46:12.563258",
            "price": "0E-20",
            "remaining": "1",
            "resource": "vlan",
            "resource_uri": "/api/2.0/subscriptions/12/",
            "start_time": "2014-08-26T09:13:47.436742+00:00",
            "status": "active",
            "subscribed_object": "10619300-edda-42ba-91e0-7e3df0689d00",
            "uuid": "e31585fb-6c3f-422d-a51e-395fd53fd2e5",
            "was_billed": true
        },
        {
            "amount": "17179869184",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "10",
            "period": "365 days, 2:46:54.269604",
            "price": "0E-20",
            "remaining": "17179869184",
            "resource": "mem",
            "resource_uri": "/api/2.0/subscriptions/10/",
            "start_time": "2014-08-26T09:13:05.730396+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "5830f712-6eef-4732-9dbd-6a9f3b1fcb2f",
            "was_billed": true
        },
        {
            "amount": "10000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "9",
            "period": "365 days, 2:47:23.682426",
            "price": "0E-20",
            "remaining": "10000",
            "resource": "cpu",
            "resource_uri": "/api/2.0/subscriptions/9/",
            "start_time": "2014-08-26T09:12:36.317574+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "664fb99b-f8cc-4e85-8764-ef3215767682",
            "was_billed": true
        }
    ],
    "price": "0E-20"
}

Subscription duration

There are three parameters that determine the subscription’s duration. All times are in UTC. Not all combinations are valid:

  • start_time: In ISO 8601 format. Defaults to the current time.
  • end_time: In ISO 8601 format.
  • period: Free form text describing the period. Ex: ‘2 months 1 week’.
Inputs Result
start_time end_time period  
True True True Error: Ambiguous.
True True False Between start_time and end_time.
True False True Period from start_time.
True False False Error: Not specific enough.
False True True Period until end_time.
False True False From now until end_time.
False False True Period from now.
False False False Error: Not specific enough.

Creating

POST /subscriptions/
Status Codes:
  • 201 – object created

Creates a new subscription. There is a limit of 500 subscriptions that can be purchased in one request.

The resource can be a license or one of: dssd (hdd is an alias for this, but is being deprecated), cpu, mem, tx, ip, vlan.

When buying tx, the time parameters are ignored.

Trying to purchase a subscription for IP or VLAN with an amount bigger than one will generate several subscriptions of that type.

Subscription times are rounded to noon UTC, using the following rules:

  • End time is always rounded to the next noon.

  • Start time is rounded to the maximum between the current time an the previous noon. This means that subscriptions bought for now do start now, but subscriptions for the future start at the previous noon.

    Warning

    Subscriptions are mostly immutable for the customer. The only parameter that can be changed is the auto renew.

Example request:

POST /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 30000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "30000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": "0",
            "discount_percent": "0",
            "end_time": "2013-04-22T12:00:00+00:00",
            "id": "28",
            "period": "31 days, 1:31:53.888650",
            "price": "0.000003839842975139617919921875",
            "remaining": "30000",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/28/",
            "start_time": "2013-03-22T10:28:06.111350+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "f622f364-bccf-4a36-a1ce-632a81640ad4"
        }
    ],
    "price": "0.000003839842975139617919921875"
}

Extending

POST /subscriptions/{id}/action/?do=extend
Status Codes:
  • 200 – no error

Extends the subscription. An extended subscription is actually just another subscription that is linked to the original If a period or and end_time are specified in the request,they are used. If neither are specified, the creation length of the subscription is used.

A caveat to this is that a subscription created initially with an end_time, the exact interval is used. Subscriptions that are created with a period have the period parsed again in the context of the new start_time. An example would be a subscription created on the 1st of February with a period of ‘1 month’ will be extended for 31 days, but one that was created with an end date of 1st of March will be extended for 28 days.

If the specified subscription has actually been extended, it traverses and extends the last subscription in the chain.

Autorenewing

POST /subscriptions/{id}/action/?do=auto_renew

Toggles the autorenew flag of the subscription. Optionally, the value can be specified in the request.

Status Codes:
  • 200 – no error

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "post"
    ],
    "allowed_list_http_methods": [
        "get",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "amount": {
            "blank": false,
            "default": 1,
            "help_text": "Subscription amount",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "auto_renew": {
            "blank": false,
            "default": true,
            "help_text": "States if the subscription will auto renew on expire",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "descendants": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscriptions that have been extended from the current one",
            "nullable": true,
            "readonly": true,
            "type": "related",
            "unique": false
        },
        "discount_amount": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Amount of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "discount_percent": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Percent of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "discounts": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "All discounts for this subscription",
            "nullable": true,
            "readonly": true,
            "type": "dict",
            "unique": false
        },
        "end_time": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "End time of subscription",
            "nullable": true,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "free_tier": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Duration of the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "price": {
            "blank": false,
            "default": 0,
            "help_text": "Subscription price",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "remaining": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Amount remaining",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Name of resource associated with the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "start_time": {
            "blank": false,
            "default": "2015-03-19T13:55:01.236421+00:00",
            "help_text": "Start time of subscription",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "status": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Status of the subscription",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "subscribed_object": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscribed object - the target of this subscription, if applicable",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "was_billed": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        }
    },
    "filtering": {
        "subscribed_object": [
            "exact"
        ]
    }
}

Grouped subscriptions

GET /groupedsubscriptions/

Returns only the first subscriptions from a chain of extended subscriptions. The extensions are listed in the ‘descendants’ attribute and the end_time is that of the last subscription in the chain.

Status Codes:
  • 200 – no error

Calculator

POST /subscriptioncalculator/

Returns the price of the subscriptions POSTed in the same format as the normal subscriptions.

Status Codes:
  • 200 – no error

Example request:

POST /api/2.0/subscriptioncalculator/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 10000000000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 200 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "10000000000",
            "discount_amount": "0E-24",
            "discount_percent": "0",
            "discounts": {},
            "end_time": "2015-04-20T12:00:00+00:00",
            "free_tier": false,
            "period": "31 days, 22:04:59.904871",
            "price": "1.010484993457794189453125",
            "resource": "dssd",
            "start_time": "2015-03-19T13:55:00.095129+00:00",
            "was_billed": true
        }
    ],
    "price": "1.010484993457794189453125"
}

Similarly, the price of extending a subscription can be calculated.

Example request:

POST /api/2.0/subscriptioncalculator/7272/action/?do=extend HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

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

{
    "amount": "32212254720",
    "discount_amount": "9.60750000000000000",
    "discount_percent": "0.2500000000",
    "discounts": {
        "period": "0.2500000000"
    },
    "end_time": "2016-08-26T12:00:00+00:00",
    "free_tier": false,
    "period": "366 days, 0:00:00",
    "price": "28.82250000000000000000",
    "resource": "dssd",
    "start_time": "2015-08-26T12:00:00+00:00",
    "was_billed": true
}

Accounts

Note

See RFC 2616 for more details on HTTP methods semantics

General

The accounts API supports the following actions

Create account

POST /accounts/action/?do=create
Creates an account on the system. In case of succes, the user has to check his email for a confirmation link, which will ask him to create a password for the account.
Status Codes:
  • 200 – no error
Parameters:
  • email – The email of the account to be created
  • promo – Promo code for initial subscriptions and demo server (optional)

Example request:

POST /api/2.0/accounts/action/?do=create HTTP/1.1
Content-Type: application/json

{
    "email": "john_doe+42@cloudsigma.com",
    "promo": null
}

Example response:

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

{
    "success": true,
    "uuid": "ba8cce4c-9809-4389-a41e-2f9faabf87e9"
}

Login/Logout

POST /accounts/action/?do=login

Login to the system using cookie auth

Status Codes:
  • 200 – no error
  • 401 – unauthorized

Example request:

POST /accounts/action/?do=login HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{
'username':'123@asd.com',
'password':'parola'

}
Response:
Empty
POST /accounts/action/?do=logout

Logout from the system when using cookie auth

Status Codes:
  • 200 – no error
Example request:
POST /accounts/action/?do=logout HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{}
Response:
Empty
POST /accounts/action/?do=check_login

Check if you are logged in the system

Status Codes:
  • 200 – no error

Example request:

POST /accounts/action/?do=check_login HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json

Request body

{}
Response:
Empty

Audit logs

Note

See RFC 2616 for more details on HTTP methods semantics

General

Audit logs are used to track changes made on your resources, either by you or by other parties, like CloudSigma staff or people that have permission to access you resources.

Querying is done as follows:

GET /logs/
Status Codes:
  • 200 – no error
GET /api/2.0/logs/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 3193934
    },
    "objects": [
        {
            "action": "delete",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:29.378194+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "stop",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:26.864672+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "stop_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:41:24.811553+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "boot",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:48.789732+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        },
        {
            "action": "start_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:47.897876+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}

Actions

Actions give information about the operation that created the log. They go in a few categories.

  • General actions - related to most resource types like servers, drives and snapshots:
    • create: During resource creation
    • update: During resource update
    • delete: During resource deletion
    • change_owner: The ownership of the resource has changed. Currently only CloudSigma staff can change ownership of a resource.
    • clone_src: Resource is used as a cloning source
    • clone_dst: Resource is a cloning destination - the newly cloned drive.
  • Drive specific actions - these only relate to drives:
    • move: Drive is moved to another physical storage. Only staff members can move drives.
    • convert_to_library: Drive is converted to a library drive. Only staff members can convert drives.
    • converted_from_library: Drive is converted to a regular drive from a library drive. Only staff members can convert drives.
    • init_upload: Drive upload is initialized.
  • Server specific actions - these only relate to servers:
    • start_send: An attempt to start a server
    • boot: The result of a start operation.
    • stop_send: An attempt to stop a server.
    • stop: The result of a stop operation
    • open_vnc: Open VNC channel to a server
    • close_vnc: Close VNC channel to a server
    • shutdown_ACPI_send: An ACPI shutdown request is send to the server.
    • heal: Server got healed, because its recorded state did not match the physical infrastructure. For example, a server is marked as unavailable, but it is actually running fine.

Errors

If the field success is marked as False, that means that an error occurred during the operation. The error details are saved in the following fields:

  • error_type - States the type of the error
  • error_point - Points to cause of the error and is mainly used for validation errors
  • error_message - Human readable message associated with the error

Example

The following example will show all the logged information during a server’s lifecycle.

First we create a server:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "test_server",
            "vnc_password": "testserver"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/973a1039-8014-4622-9a6a-8caf21e08e7e/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [],
            "uuid": "973a1039-8014-4622-9a6a-8caf21e08e7e",
            "vnc_password": "testserver"
        }
    ]
}

Upon completion you will see the following log at the top of the audit log list:

GET /api/2.0/logs/?limit=1 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193929
    },
    "objects": [
        {
            "action": "create",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "{\"name\": \"test_server\", \"tags\": [], \"mem\": 536870912, \"smp\": 1, \"cpu\": 1000, \"vnc_password\": \"testserver\"}",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:29.833850+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}
  • action states that we wanted to create a server
  • details state the parameters of the create call
  • actor states the user which executed the operation
  • success is true, so the operation completed successfully.
  • uuid matches the server’s uuid

Then we start the server:

POST /api/2.0/servers/4002da8d-94d7-4093-ab7a-a78d976a9efc/action/?do=start HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}
HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "action": "start",
    "result": "success",
    "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
}

We check the logs again. We see that the action is start_send and success is true:

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

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193930
    },
    "objects": [
        {
            "action": "start_send",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:47.897876+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}

If the server is fully booted and operational, its status will change to running. If it failed to boot for some reason, the error_type, error_point and error_message fields will explain why that happened. In this particular case, we had a successful start, so the audit log looks like this:

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

{
    "meta": {
        "limit": 1,
        "offset": 0,
        "total_count": 3193931
    },
    "objects": [
        {
            "action": "boot",
            "actor": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "category": "Servers",
            "details": "",
            "error_message": "",
            "error_point": null,
            "error_type": null,
            "success": true,
            "timestamp": "2014-06-05 09:40:48.789732+00:00",
            "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc"
        }
    ]
}
The pattern is the same when stopping a server:
  • an audit log with action stop_send is saved, representing the status of the request to stop a server.
  • If that succeeded i.e. the request to stop a server is successfully send, you can expect a log with action stop, representing the status of the stop operation i.e. the server actually stopped.

Note

If you stop a server from inside, only a log entry with stop action will be added. This way, you can figure out if the server got stopped from the API or not:

  • If there are 2 logs stop_send and stop, it is stopped via an API request
  • If only stop is present ( no stop_send ), it means that the server is stopped by other means (stopped from inside, crashed, etc).

Schema

GET /logs/schema/
GET /api/2.0/logs/schema/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "action": {
            "default": null,
            "help_text": "Name of the executed action",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "actor": {
            "default": null,
            "help_text": "User who executed action.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "category": {
            "default": null,
            "help_text": "Category the action belongs to.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "details": {
            "default": null,
            "help_text": "Details about the executed action.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_message": {
            "default": null,
            "help_text": "Error message, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_point": {
            "default": null,
            "help_text": "The field that caused the error, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "error_type": {
            "default": null,
            "help_text": "Type of error, if applicable.",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "success": {
            "default": true,
            "help_text": "Whether the action was successful.",
            "readonly": false,
            "required": true,
            "type": "boolean"
        },
        "timestamp": {
            "default": null,
            "help_text": "Time when entry was added.",
            "readonly": false,
            "required": true,
            "type": "string"
        },
        "uuid": {
            "default": null,
            "help_text": "The uuid of resource the action is executed on. Can be empty, meaning no resource is referenced.",
            "readonly": false,
            "required": false,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Profile

Allowed HTTP methods

Method Description
GET get the profile object
PUT update the profile object

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /profile/

Gets the user profile. Note that profile is a single object so the API does not return a list.

statuscode 200:no error

Example request:

GET /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "address": "Somwhere in time",
    "api_https_only": false,
    "autotopup_amount": "0E-16",
    "autotopup_threshold": "0E-16",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "",
    "country": "BG",
    "currency": "EUR",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "has_tx_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "EN",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2015-03-19 07:41:24.231684",
    "network_restrictions": null,
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2014-08-25T14:34:33.868186+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "Sofia",
    "tx_autotopup_amount": "0E-16",
    "tx_autotopup_threshold": "0E-16",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Editing

PUT /profile/
statuscode 200:no error

Edits a user profile. (We want to change the company name for example)

Example request:

PUT /api/2.0/profile/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "address": "Somwhere in time",
    "api_https_only": false,
    "autotopup_amount": "0E-16",
    "autotopup_threshold": "0E-16",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "Newly Set Company Name",
    "country": "BG",
    "currency": "EUR",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "has_tx_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "EN",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2015-03-19 07:41:24.231684",
    "network_restrictions": null,
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2014-08-25T14:34:33.868186+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "Sofia",
    "tx_autotopup_amount": "0E-16",
    "tx_autotopup_threshold": "0E-16",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Example response:

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

{
    "address": "Somwhere in time",
    "api_https_only": false,
    "autotopup_amount": "0E-16",
    "autotopup_threshold": "0E-16",
    "bank_reference": "jdoe123",
    "clone_naming": "COUNTER",
    "company": "Newly Set Company Name",
    "country": "BG",
    "currency": "EUR",
    "email": "user@example.com",
    "first_name": "John",
    "has_autotopup": false,
    "has_tx_autotopup": false,
    "invoicing": true,
    "key_auth": false,
    "language": "EN",
    "last_name": "Doe",
    "mailing_list": true,
    "meta": {},
    "my_notes": "2015-03-19 07:41:24.231684",
    "network_restrictions": null,
    "nickname": "",
    "phone": "",
    "postcode": "1000",
    "reseller": "",
    "signup_time": "2014-08-25T14:34:33.868186+00:00",
    "state": "REGULAR",
    "tax_name": null,
    "tax_rate": null,
    "title": "",
    "town": "Sofia",
    "tx_autotopup_amount": "0E-16",
    "tx_autotopup_threshold": "0E-16",
    "uuid": "6f670b3c-a2e6-433f-aeab-b976b1cdaf03",
    "vat": ""
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get",
        "put"
    ],
    "allowed_list_http_methods": [
        "get",
        "put"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "address": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "api_https_only": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "autotopup_amount": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "autotopup_threshold": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "bank_reference": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "clone_naming": {
            "blank": false,
            "default": "NONE",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "company": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "country": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "currency": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "email": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "first_name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "has_autotopup": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "has_tx_autotopup": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "invoicing": {
            "blank": false,
            "default": true,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "key_auth": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "language": {
            "blank": false,
            "default": "EN",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "last_name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "mailing_list": {
            "blank": false,
            "default": true,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "meta": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "nullable": false,
            "readonly": false,
            "type": "dict",
            "unique": false
        },
        "my_notes": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "network_restrictions": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "nickname": {
            "blank": false,
            "default": "",
            "help_text": "User nickname",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "phone": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "postcode": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "reseller": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "signup_time": {
            "blank": false,
            "default": "2015-03-19T13:49:15.421660+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "state": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "tax_name": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "tax_rate": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": true,
            "readonly": true,
            "type": "decimal",
            "unique": false
        },
        "title": {
            "blank": false,
            "default": "",
            "help_text": "User title",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "town": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "tx_autotopup_amount": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "tx_autotopup_threshold": {
            "blank": false,
            "default": 0,
            "help_text": "Fixed precision numeric data. Ex: 26.73",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "vat": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        }
    }
}

Notification contacts

Listing

GET /notification_contacts/

Gets the list of contacts configured for the account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/notification_contacts/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "email": "some_email_1@example.com",
            "main": true,
            "name": "Some Name",
            "phone": "",
            "resource_uri": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "uuid": "e13c4b8c-68c8-4163-bc00-2a43a86e5937"
        }
    ]
}

Creating

POST /notification_contacts/

Creates a new contact.

Status Codes:
  • 201 – object created

Example request:

POST /api/2.0/notification_contacts/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "email": "some_email_2@example.com",
            "name": "Some Name 2",
            "phone": "+1 123 555 1234"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "email": "some_email_2@example.com",
            "main": null,
            "name": "Some Name 2",
            "phone": "+11235551234",
            "resource_uri": "/api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/",
            "uuid": "0103f398-9f85-446a-a285-fe63cf9f0f28"
        }
    ]
}

Editing

PUT /notification_contacts/{uuid}/

Edits a notification contact. Note that changing the main user’s email is not recommended, as if the account email changes, so will the main contact.

Status Codes:
  • 200 – no errors

Example request:

PUT /api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "email": "some_email_2@example.com",
    "name": "Some New Name"
}

Example response:

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

{
    "email": "some_email_2@example.com",
    "main": null,
    "name": "Some New Name",
    "phone": "+11235551234",
    "pk": "0103f398-9f85-446a-a285-fe63cf9f0f28",
    "resource_uri": "/api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/",
    "uuid": "0103f398-9f85-446a-a285-fe63cf9f0f28"
}

Deleting

DELETE /notification_contacts/{uuid}/

Delete a notification contact. Note that you cannot delete the main contact.

Status Codes:
  • 204 – no errors

Example request:

DELETE /api/2.0/notification_contacts/0103f398-9f85-446a-a285-fe63cf9f0f28/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Notification preferences

Listing

GET /notification_preferences/

Gets the list of contacts configured for the account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/notification_preferences/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 22
    },
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_withheld",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_failed",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_failure",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "out_of_money_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "stop_servers",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_success",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "out_of_money_very_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "drives_delete_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_very_soon",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "new_account",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "reset_password",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "drives_delete",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "random_upgrade",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_cancelled",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_renewal_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "subscription_expire_very_soon",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_approved",
            "value": true
        }
    ]
}

Updating

PUT /notification_preferences/

Updates the specified preferences. Only the ones in the request are modified.

Status Codes:
  • 200 – no error

Example request:

PUT /api/2.0/notification_preferences/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
    "medium": "email",
    "type": "trial_expire",
    "value": true
}

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": true
        }
    ]
}

Multiple objects can be specified in the request.

Example request:

PUT /api/2.0/notification_preferences/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

[
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "trial_expire",
        "value": false
    },
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "payment_withheld",
        "value": true
    },
    {
        "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
        "medium": "email",
        "type": "payment_failed",
        "value": false
    }
]

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "trial_expire",
            "value": false
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_withheld",
            "value": true
        },
        {
            "contact": "/api/2.0/notification_contacts/e13c4b8c-68c8-4163-bc00-2a43a86e5937/",
            "medium": "email",
            "type": "payment_failed",
            "value": false
        }
    ]
}

Billing

Balance

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /balance/

Get the balance and currency of the current account.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/balance/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "balance": "155367.99237092264288897986",
    "credit_limit": null,
    "currency": "EUR"
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "Amount of money in account",
            "readonly": true,
            "required": true,
            "type": "decimal"
        },
        "credit_limit": {
            "default": "No default provided.",
            "help_text": "Credit limit applied to the account, if present",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "currency": {
            "default": "No default provided.",
            "help_text": "Currency of the account",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Pricing

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /pricing/

Gets the pricing information that are applicable to the cloud. Subscription prices use a burst level of 0.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/pricing/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "current": {
        "cpu": 20,
        "dssd": 1,
        "ip": 1,
        "mem": 17,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "sparc_t4_cpu": 1,
        "sparc_t4_mem": 1,
        "ssd": 1,
        "tx": 1,
        "vlan": 1,
        "vlan_ecx": 1,
        "zadara": 1
    },
    "meta": {
        "limit": 5,
        "offset": 0,
        "total_count": 484
    },
    "next": {
        "cpu": 20,
        "dssd": 1,
        "ip": 1,
        "mem": 17,
        "msft_7jq_00341": 1,
        "msft_7nq_00302": 1,
        "msft_p73_04837_core": 1,
        "msft_tfa_00523": 1,
        "sms": 1,
        "sparc_t4_cpu": 1,
        "sparc_t4_mem": 1,
        "ssd": 1,
        "tx": 1,
        "vlan": 1,
        "vlan_ecx": 1,
        "zadara": 1
    },
    "objects": [
        {
            "currency": "GBP",
            "id": "656",
            "level": 1,
            "multiplier": 2783138807808000,
            "price": "0.18200000000000000000",
            "resource": "dssd",
            "unit": "GB/month"
        },
        {
            "currency": "EUR",
            "id": "636",
            "level": 1,
            "multiplier": 2783138807808000,
            "price": "0.21000000000000000000",
            "resource": "dssd",
            "unit": "GB/month"
        },
        {
            "currency": "USD",
            "id": "616",
            "level": 1,
            "multiplier": 2783138807808000,
            "price": "0.28000000000000000000",
            "resource": "dssd",
            "unit": "GB/month"
        },
        {
            "currency": "CHF",
            "id": "596",
            "level": 1,
            "multiplier": 2783138807808000,
            "price": "0.26600000000000000000",
            "resource": "dssd",
            "unit": "GB/month"
        },
        {
            "currency": "USD",
            "id": "307",
            "level": 0,
            "multiplier": 2783138807808000,
            "price": "0.14000000000000000000",
            "resource": "dssd",
            "unit": "GB/month"
        }
    ]
}

Burst levels

The current and future burst levels are provided in objects at the root of the response. The burst levels are calculated every 5 minutes based on the usage of the cloud and are applied 5 minutes later (when the next burst levels are calculated)

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

{
    "current": {
        "cpu": 20, 
        "dssd": 1, 
        "ip": 1, 
        "mem": 17, 
        "msft_7jq_00341": 1, 
        "msft_7nq_00302": 1, 
        "msft_p73_04837_core": 1, 
        "msft_tfa_00523": 1, 
        "sms": 1, 
        "sparc_t4_cpu": 1, 
        "sparc_t4_mem": 1, 
        "ssd": 1, 
        "tx": 1, 
        "vlan": 1, 
        "vlan_ecx": 1, 
        "zadara": 1
    }, 
    "next": {
        "cpu": 20, 
        "dssd": 1, 
        "ip": 1, 
        "mem": 17, 
        "msft_7jq_00341": 1, 
        "msft_7nq_00302": 1, 
        "msft_p73_04837_core": 1, 
        "msft_tfa_00523": 1, 
        "sms": 1, 
        "sparc_t4_cpu": 1, 
        "sparc_t4_mem": 1, 
        "ssd": 1, 
        "tx": 1, 
        "vlan": 1, 
        "vlan_ecx": 1, 
        "zadara": 1
    }
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "currency": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The currency of the price",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "level": {
            "blank": false,
            "default": 0,
            "help_text": "The burst level the price applies to",
            "nullable": false,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "multiplier": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The multiplier applied to get the price of one unit per second, from the unit of the price",
            "nullable": false,
            "readonly": true,
            "type": "integer",
            "unique": false
        },
        "price": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Price",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "resource": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The resource the price applies to",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "unit": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The unit of the price",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        }
    },
    "filtering": {
        "level": 1
    }
}

Discounts

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /discount/

Get discount information.

statuscode 200:no error

Example request:

GET /api/2.0/discount/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "period": "3 months",
            "value": "0.0300000000"
        },
        {
            "period": "6 months",
            "value": "0.1000000000"
        },
        {
            "period": "1 year",
            "value": "0.2500000000"
        },
        {
            "period": "2 years",
            "value": "0.3500000000"
        },
        {
            "period": "3 years",
            "value": "0.4500000000"
        }
    ]
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The minimum period for this discount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "value": {
            "blank": false,
            "default": 0,
            "help_text": "The value of the discount",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        }
    }
}

Transaction list

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /ledger/

Get the transactions for the account.

statuscode 200:no error

Example request:

GET /api/2.0/ledger/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 98203
    },
    "objects": [
        {
            "amount": "0.00014583333333333333",
            "billing_cycle": 105157,
            "end": "469291.07488238102453490453",
            "human_interval": "5 minutes",
            "id": "39509304",
            "initial": "469291.07502821435786823786",
            "interval": 300,
            "poll_time": "2014-06-05T09:06:06.713945+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 09:06",
            "resource_amount": "4831838208",
            "time": "2014-06-05T09:08:47.992023+00:00"
        },
        {
            "amount": "0.00908310000000000000",
            "billing_cycle": 105150,
            "end": "469291.07502821435786823786",
            "human_interval": "2 minutes",
            "id": "39506824",
            "initial": "469291.08411131435786823786",
            "interval": 137,
            "poll_time": "2014-06-05T08:31:06.610957+00:00",
            "reason": "Burst: 12.00 GHz of cpu for 2 minutes at 2014-06-05 08:31",
            "resource_amount": "12000",
            "time": "2014-06-05T08:33:48.047354+00:00"
        },
        {
            "amount": "0.00255733333333333333",
            "billing_cycle": 105150,
            "end": "469291.08411131435786823786",
            "human_interval": "2 minutes",
            "id": "39506823",
            "initial": "469291.08666864769120157119",
            "interval": 137,
            "poll_time": "2014-06-05T08:31:06.610957+00:00",
            "reason": "Burst: 4.00 GB of mem for 2 minutes at 2014-06-05 08:31",
            "resource_amount": "4294967296",
            "time": "2014-06-05T08:33:48.036326+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105148,
            "end": "469291.08666864769120157119",
            "human_interval": "5 minutes",
            "id": "39506114",
            "initial": "469291.08681399491342379341",
            "interval": 299,
            "poll_time": "2014-06-05T08:21:06.603517+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 08:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T08:23:50.433096+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469291.08681399491342379341",
            "human_interval": null,
            "id": "39505412",
            "initial": "469235.63681399491342095124",
            "interval": null,
            "poll_time": "2014-06-05T08:16:04.495196+00:00",
            "reason": "Payment through card - 9fddd858-ec89-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T08:16:04.495183+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "469235.63681399491342095124",
            "human_interval": null,
            "id": "39505411",
            "initial": "469158.40681399491341697220",
            "interval": null,
            "poll_time": "2014-06-05T08:15:58.552271+00:00",
            "reason": "Payment through card - 9c37a0bc-ec89-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T08:15:58.552247+00:00"
        },
        {
            "amount": "0.00888420000000000000",
            "billing_cycle": 105138,
            "end": "469158.40681399491341697220",
            "human_interval": "2 minutes",
            "id": "39502556",
            "initial": "469158.41569819491341697220",
            "interval": 134,
            "poll_time": "2014-06-05T07:31:06.597276+00:00",
            "reason": "Burst: 12.00 GHz of cpu for 2 minutes at 2014-06-05 07:31",
            "resource_amount": "12000",
            "time": "2014-06-05T07:33:51.033990+00:00"
        },
        {
            "amount": "0.00250133333333333333",
            "billing_cycle": 105138,
            "end": "469158.41569819491341697220",
            "human_interval": "2 minutes",
            "id": "39502555",
            "initial": "469158.41819952824675030553",
            "interval": 134,
            "poll_time": "2014-06-05T07:31:06.597276+00:00",
            "reason": "Burst: 4.00 GB of mem for 2 minutes at 2014-06-05 07:31",
            "resource_amount": "4294967296",
            "time": "2014-06-05T07:33:51.022223+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105136,
            "end": "469158.41819952824675030553",
            "human_interval": "5 minutes",
            "id": "39501851",
            "initial": "469158.41834487546897252775",
            "interval": 299,
            "poll_time": "2014-06-05T07:21:06.607872+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 07:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T07:23:49.590257+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469158.41834487546897252775",
            "human_interval": null,
            "id": "39501157",
            "initial": "469102.96834487546896968558",
            "interval": null,
            "poll_time": "2014-06-05T07:16:04.926285+00:00",
            "reason": "Payment through card - 3fe9a3bc-ec81-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T07:16:04.926273+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "469102.96834487546896968558",
            "human_interval": null,
            "id": "39501156",
            "initial": "469025.73834487546896570654",
            "interval": null,
            "poll_time": "2014-06-05T07:16:01.585853+00:00",
            "reason": "Payment through card - 3dca136e-ec81-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T07:16:01.585840+00:00"
        },
        {
            "amount": "0.00633993750000000000",
            "billing_cycle": 105126,
            "end": "469025.73834487546896570654",
            "human_interval": "2 minutes",
            "id": "39498298",
            "initial": "469025.74468481296896570654",
            "interval": 135,
            "poll_time": "2014-06-05T06:31:06.554201+00:00",
            "reason": "Burst: 8.50 GHz of cpu for 2 minutes at 2014-06-05 06:31",
            "resource_amount": "8500",
            "time": "2014-06-05T06:33:52.255963+00:00"
        },
        {
            "amount": "0.00031500000000000000",
            "billing_cycle": 105126,
            "end": "469025.74468481296896570654",
            "human_interval": "2 minutes",
            "id": "39498297",
            "initial": "469025.74499981296896570654",
            "interval": 135,
            "poll_time": "2014-06-05T06:31:06.554201+00:00",
            "reason": "Burst: 0.50 GB of mem for 2 minutes at 2014-06-05 06:31",
            "resource_amount": "536870912",
            "time": "2014-06-05T06:33:52.244645+00:00"
        },
        {
            "amount": "0.00014534722222222222",
            "billing_cycle": 105124,
            "end": "469025.74499981296896570654",
            "human_interval": "5 minutes",
            "id": "39497582",
            "initial": "469025.74514516019118792876",
            "interval": 299,
            "poll_time": "2014-06-05T06:21:06.570020+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 06:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T06:23:51.102193+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "469025.74514516019118792876",
            "human_interval": null,
            "id": "39496879",
            "initial": "468970.29514516019118508659",
            "interval": null,
            "poll_time": "2014-06-05T06:16:03.979389+00:00",
            "reason": "Payment through card - dc2f7084-ec78-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T06:16:03.979376+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "468970.29514516019118508659",
            "human_interval": null,
            "id": "39496878",
            "initial": "468893.06514516019118110755",
            "interval": null,
            "poll_time": "2014-06-05T06:15:58.310868+00:00",
            "reason": "Payment through card - d88fbc54-ec78-11e3-bf8f-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T06:15:58.310852+00:00"
        },
        {
            "amount": "0.00536987500000000000",
            "billing_cycle": 105114,
            "end": "468893.06514516019118110755",
            "human_interval": "2 minutes",
            "id": "39494022",
            "initial": "468893.07051503519118110755",
            "interval": 133,
            "poll_time": "2014-06-05T05:31:06.501327+00:00",
            "reason": "Burst: 7.50 GHz of cpu for 2 minutes at 2014-06-05 05:31",
            "resource_amount": "7500",
            "time": "2014-06-05T05:33:52.682096+00:00"
        },
        {
            "amount": "0.00014583333333333333",
            "billing_cycle": 105112,
            "end": "468893.07051503519118110755",
            "human_interval": "5 minutes",
            "id": "39493319",
            "initial": "468893.07066086852451444088",
            "interval": 300,
            "poll_time": "2014-06-05T05:21:06.511910+00:00",
            "reason": "Burst: 4.50 GB of dssd for 5 minutes at 2014-06-05 05:21",
            "resource_amount": "4831838208",
            "time": "2014-06-05T05:23:50.866953+00:00"
        },
        {
            "amount": "-55.45000000000000284217",
            "billing_cycle": null,
            "end": "468893.07066086852451444088",
            "human_interval": null,
            "id": "39492621",
            "initial": "468837.62066086852451159871",
            "interval": null,
            "poll_time": "2014-06-05T05:15:59.277046+00:00",
            "reason": "Payment through card - 78fc2118-ec70-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T05:15:59.277034+00:00"
        },
        {
            "amount": "-77.23000000000000397904",
            "billing_cycle": null,
            "end": "468837.62066086852451159871",
            "human_interval": null,
            "id": "39492620",
            "initial": "468760.39066086852450761967",
            "interval": null,
            "poll_time": "2014-06-05T05:15:55.898020+00:00",
            "reason": "Payment through card - 76a699d4-ec70-11e3-8c3b-00259082dfa8",
            "resource_amount": "1",
            "time": "2014-06-05T05:15:55.898007+00:00"
        }
    ]
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "amount": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of the operation, positive for debits, negative for credits",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "billing_cycle": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Billing cycle that generated this charge",
            "nullable": true,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "end": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of money after the operation",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "human_interval": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Human readable interval of bill entry",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "initial": {
            "blank": false,
            "default": 0,
            "help_text": "Amount of money before the operation",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "interval": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Interval of bill entry",
            "nullable": true,
            "readonly": false,
            "type": "integer",
            "unique": false
        },
        "poll_time": {
            "blank": false,
            "default": "2014-06-05T09:41:58.809494+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "reason": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Description of the operation",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_amount": {
            "blank": false,
            "default": 1,
            "help_text": "Resource amount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "time": {
            "blank": false,
            "default": "2014-06-05T09:41:58.809480+00:00",
            "help_text": "A date & time as a string. Ex: \"2010-11-10T03:07:43\"",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        }
    },
    "filtering": {
        "billing_cycle": 1,
        "time": 1
    },
    "ordering": [
        "time"
    ]
}

Discounts

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /discount/

Get discount information.

statuscode 200:no error

Example request:

GET /api/2.0/discount/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "period": "3 months",
            "value": "0.0300000000"
        },
        {
            "period": "6 months",
            "value": "0.1000000000"
        },
        {
            "period": "1 year",
            "value": "0.2500000000"
        },
        {
            "period": "2 years",
            "value": "0.3500000000"
        },
        {
            "period": "3 years",
            "value": "0.4500000000"
        }
    ]
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 0,
    "fields": {
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The minimum period for this discount",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "value": {
            "blank": false,
            "default": 0,
            "help_text": "The value of the discount",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        }
    }
}

Current usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /currentusage/

Get the current usage of the user.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/currentusage/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "balance": {
        "balance": "155367.99237092264288897986",
        "currency": "EUR"
    },
    "usage": {
        "amd_cpu": {
            "burst": 0,
            "subscribed": 10000,
            "using": 0
        },
        "amd_mem": {
            "burst": 0,
            "subscribed": 17179869184,
            "using": 0
        },
        "cpu": {
            "burst": 0,
            "subscribed": 10000,
            "using": 0
        },
        "dssd": {
            "burst": 0,
            "subscribed": 32212254720,
            "using": 30064771072
        },
        "ip": {
            "burst": 0,
            "subscribed": 1,
            "using": 1
        },
        "mem": {
            "burst": 0,
            "subscribed": 17179869184,
            "using": 0
        },
        "msft_7jq_00341": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_7nq_00302": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_p73_04837_core": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "msft_tfa_00523": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "sms": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "sparc_t4_cpu": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "sparc_t4_mem": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "tx": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "vlan": {
            "burst": 0,
            "subscribed": 1,
            "using": 1
        },
        "vlan_ecx": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "zadara": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        }
    }
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        },
        "usage": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}

Licenses list

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /licenses/

Get the licenses available on the cloud. The type of the license can be one of:

Status Codes:
  • 200 – no error
  • install - These licenses are billed per installation, regardless of whether it is attached to a running server or not.
  • instance - These licenses are billed per running instance of a server. A license attached to a guest that’s stopped is not billed.
  • stub - These licenses are billed per a metric specified by the customer (i.e. per number of users license)

The user metric field specifies what attribute on the instance of the server is used for determining the number of licenses. For example, “smp” will count one license for each CPU/core in the virtual machine.

Example request:

GET /api/2.0/licenses/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

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

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "burstable": false,
            "long_name": "SQL Server Enterprise Edition",
            "name": "msft_7jq_00341",
            "resource_uri": "/api/2.0/licenses/13/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": false,
            "long_name": "SQL Server Standard Edition",
            "name": "msft_7nq_00302",
            "resource_uri": "/api/2.0/licenses/14/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": true,
            "long_name": "Windows Server",
            "name": "msft_p73_04837_core",
            "resource_uri": "/api/2.0/licenses/12/",
            "type": "instance",
            "user_metric": "smp"
        },
        {
            "burstable": false,
            "long_name": "SQL Server Web",
            "name": "msft_tfa_00523",
            "resource_uri": "/api/2.0/licenses/15/",
            "type": "instance",
            "user_metric": "smp"
        }
    ]
}

Schema

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

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "burstable": {
            "blank": false,
            "default": false,
            "help_text": "Whether this resource can be used on burst",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "long_name": {
            "blank": false,
            "default": "",
            "help_text": "A human readable name for the resource.",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "name": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Name that should be used when purchasing",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "type": {
            "blank": false,
            "default": "instance",
            "help_text": "Type of billing",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "user_metric": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "The metric that the user is charged for",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        }
    }
}

Burst Usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /burstusage/

Get the burst usage of the authenticated user for the specified period (last 30 days by default).

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/burstusage/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
             "uuid": "75fbf5d6-4ef6-11e4-9ce3-8bd2cacc5639",
             "amount": 0.01000000000000000000,
             "resource_type": "ip",
             "usage": 1
        },
        {
             "uuid": "f2669d85-2dbd-4f0d-8a1f-40a06deb3233",
             "amount": 0.03010000000000000000,
             "resource_type": "cpu",
             "usage": 12000
        },
        {
             "uuid": "1e170e6e-5339-477d-a29d-c3e6533a1825",
             "amount": 0.02000000000000000000,
             "resource_type": "mem",
             "usage": 9663676416
        },
        {
             "uuid": "42b2af55-ec3c-4066-a152-66d201c59576",
             "amount": 0.01000000000000000000,
             "resource_type": "dssd",
             "usage": 107374182400
        },
    ]
}

Filtering

It’s possible to specify period of burst usage using filtering by date:

  • Exact: ?date=2014-10-21

  • Lower than: ?date__lt=2014-10-21

  • Lower than or equal: ?date__lte=2014-10-21

  • Greater than: ?date__gt=2014-10-21

  • Greater than or equal: ?date__gte=2014-10-21

    Example for retreiving burst usage for the whole July 2014:

    GET /api/2.0/burstusage/?date__gte=2014-07-01&date__lt=2014-08-01 HTTP/1.1
    Content-Type: application/json
    Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
    

Daily Burst Usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /dailyburstusage/

Get the daily burst usage of the authenticated user for the specified period (last 30 days by default).

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/dailyburstusage/?date__gt=2014-11-15&date__lt=2014-11-19 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 4
    },
    "objects": [
        {
            "amount": "0.00886683986848225317",
            "date": "2014-11-17",
            "resource_type": "dssd",
            "usage": 309237645312
        },
        {
            "amount": "0.00886684598104320994",
            "date": "2014-11-16",
            "resource_type": "dssd",
            "usage": 309237645312
        },
        {
            "amount": "0.00514153897280246914",
            "date": "2014-11-18",
            "resource_type": "dssd",
            "usage": 179314884608
        },
        {
            "amount": "0.00886683701903935188",
            "date": "2014-11-15",
            "resource_type": "dssd",
            "usage": 309237645312
        }
    ]
}

Filtering

It’s possible to specify period of burst usage using filtering by date:

  • Lower than: ?date__lt=2014-10-21

  • Greater than: ?date__gt=2014-10-21

    Example for retreiving burst usage for the whole July 2014:

    GET /api/2.0/dailyburstusage/?date__gt=2014-07-01&date__lt=2014-08-01 HTTP/1.1
    Content-Type: application/json
    Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
    

Note

The date is actually a full time, which means that 2014-11-11 is actually 2014-11-11 00:00. This matters when trying to filter because when using less than, it will not include the day, whereas it will be included for greater then.

Current Usage

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616 for more details on HTTP methods semantics

Listing

GET /currentusage/

Gets the current usage of the authenticated user has access.

Parameters:
  • context – another account whose drives should be listed
Status Codes:
  • 200 – no error

Example request:

GET /2.0/currentusage/ HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json
Authorization: Basic dGVzdHVzZXJAY2xvdWRzaWdtYS5jb206dmJudmJu

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8

{
    "balance": {
        "balance": "9899.16666666666666666667",
        "currency": "CHF"
    },
    "usage": {
        "cpu": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "dssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ip": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "mem": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "ssd": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        },
        "vlan": {
            "burst": 0,
            "subscribed": 0,
            "using": 0
        }
    }
}

Request schema

None.

Response schema

{
    "allowed_detail_http_methods": [
        "get"
    ],
    "allowed_list_http_methods": [
        "get"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "balance": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        },
        "usage": {
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "readonly": false,
            "required": true,
            "type": "dict"
        }
    }
}

Asynchronous server

Authentication

In order to use the asynchronous server, you must first authenticate through the API. This will give you a cookie that is valid for 2 minutes and that has to be used when connecting to the server.

statuscode 200:no error

Example request:

POST /2.0/accounts/action/?do=authenticate_asynchronous HTTP/1.1
Host: api.cloudsigma.com
Accept: application/json
Authorization: Basic dGVzdHVzZXJAY2xvdWRzaWdtYS5jb206dmJudmJu

Example response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8
Set-Cookie: async_auth=YTlhZmMwYTctOWYzNi00ZmUzLThlYmUtMGZiOGZlODE0ZmQx|1356012032|f785e3d8083c7666209e54477652de0d057f0791; expires=Thu, 20-Dec-2012 14:02:32 GMT; Max-Age=120; Path=/

{}

Using this cookie will allow you to connect to the server at /2.0/websocket

Information

The websocket server sends frames every time one of the following changes:

The frame is a JSON object that contains the following fields:
  • resource_type: A text field that describes the type of resource covered by the notification.
  • resource_uri: The URI of the resource that has changed.

The JSON object might contain a ‘object’ key, that will contain the full blown resource referenced by the notification, JSON encoded.

Indices and tables