API v2 reference

This document contains detailed information about the Skytap resources that can be accessed from the v2 API.

For general information about using the API, see API quick start. For a comparison of v1 and v2, see API versions.

API overview v1 reference

Accessing the v2 REST API

v2 capabilities

v2 resources

v2 change log

Accessing the v2 REST API

The v2 API has many of the same authentication requirements as the v1 API.

The primary difference is that when you make a v2 request, you must include at least one v2 indicator:

Indicator

Example

v2 after the host name in your API request

https://cloud.skytap.com/v2/templates

GET https://cloud.skytap.com/v2/templates/12345

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Accept: application/json

Content-Type: application/json

A v2 Accept header

Accept: application/vnd.skytap.api.v2+json

GET https://cloud.skytap.com/templates/12345

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Accept: application/vnd.skytap.api.v2+json

Content-Type: application/json

The Content-Type header remains either application/json or application/xml. Don’t include v2 in the Content-Type header.

Notes

You don't need to specify v1 in your v1 API requests. If a version number isn't specified, Skytap processes the request as a v1 request.
For more information about crafting a Skytap API request, see the Skytap API quick start.

v2 capabilities

Scope, filter, sort, and paginate parameters

Many of the primary v2 API resource collections (including environments, templates, assets, users, and departments) can respond to scope, filter, sort, and pagination request parameters on a GET request. These parameters can be combined or omitted as needed to request more specific or more comprehensive resource representations.

Parameter options for the GET requests vary by resource. For additional details, see the supporting documentation for each v2 API resource.

For example, an admin can use the following request to get a representation of the first 100 environments in a list of environments owned by all users in the account:

GET https://cloud.skytap.com/v2/configurations?scope=all&count=100&offset=0

When making a GET request to a resource collection, you must specify both a count and offset parameter; otherwise, you may receive a 302 response. In the above example, scope is an optional parameter.

If you want to return a full list of resources, you can use the Content-Range header to determine the total number of items that can be returned. For more information, see Content-Range and Link headers below.

More specifically, a project owner can request a list of 50 environments that belong to a particular project, that are in the US-West region, and that haven’t been run in the last 30 days, sorted by name:

GET https://cloud.skytap.com/v2/configurations?query=project_id:12345,region:US-West&last_run=to+now-30d&count=50&offset=0&sort=name

Content-Range and Link headers

If the response to a GET request to a resource collection doesn’t include all of the resources, the response header will include a Content-Range header and Link header. For example, these headers will appear if the API returns 10 of 40 total environments.

Content-Range header

The Content-Range header lists the range of items you’re viewing, along with the total number of those items. For example, if your account has 40 environments, and Skytap returns the first 10 environments, the Content-Range header will read items 0-9/40.
Notes
- The item range begins with 0, not 1; this means that in the above example, the first 10 items are represented as 0-9, not 1-10.
- The total number of items begins with 1, not 0; this means that in the above example 40 total items are represented as 40, not 39.
Link header

If you perform a GET command with a count less than your total number of environments, the collection will be paginated. A Link header will provide links with different offsets (e.g., </v2/configurations?count=10&offset=20>; rel="next", </v2/configurations?count=10&offset=0>; rel="previous"); copying these will allow you to view other environments in the list.

v2 resources

The following sections describe the principal resource types exposed in the API, their representations and reference URI pattern, and the key operations defined for the resource.

As you use the API, there may be elements present in the returned structures that aren’t documented. These are unsupported elements, and there is no guarantee that they will exist in future revisions of the API. Don’t build dependencies on these unsupported and undocumented elements.

Environments v2 resource

> VM network adapters v2

> Published services v2

> Secondary IP addresses v2

> Environment containers v2

> Environment labels v2

> Environment lock v2

> Environment Multi-Attach Storage

> Environment networks v2

> Environment notes v2

> Environment sharing portals v2

> Environment tags v2

> Environment metadata v2

> Environment VM sequencing stages v2

Templates v2 resource

> VM network adapters v2

> Published services v2

> Template networks v2

> Template labels v2

> Template sharing portals v2

> Template tags v2

> Template VM sequencing stages v2

Environments v2 resource

An environment consists of one or more virtual machines, networks, and associated settings and metadata. Unlike a template, an environment can be run and have most of its settings modified.

Environments v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}

Environments v2 resource model

The element name is configurations.

Throughout the Skytap API, environments are referred to as “configurations.” Skytap no longer uses the term “configurations” in the web interface; however, this name has been maintained in the API for backward-compatibility.

The following fields are defined:

Field Name	Type	Access	Description
alerts	array	ro	Environment-wide warnings or informational alerts.
auto_shutdown_description	string	ro	Describes either the time the environment is set to automatically shut down (for example, “At May 1, 10:30 PM”), or the automatic shut down period (for example, “After 5 minutes of idle time”). If `null`, automatic shutdown is off.
auto_suspend_description	string	ro	Describes either the time the environment is set to automatically suspend (for example, “At May 1, 10:30 PM”), or the automatic suspend period (for example, “After 5 minutes of idle time”). If `null`, automatic suspend is off.
can_change_state	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role, environment_locked state, or project permissions (if the environment is in a project).
can_copy	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role, environment_locked state, or project permissions (if the environment is in a project).
can_delete	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role, environment_locked state, or project permissions (if the environment is in a project).
can_edit	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role, environment_locked state, or project permissions (if the environment is in a project).
can_lock	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role or project permissions (if the environment is in a project).
can_save_as_template	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role, environment_locked state, or project permissions (if the environment is in a project).
can_share	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role or project permissions (if the environment is in a project).
can_tag	Boolean	ro	The user’s permissions relative to this environment. These permissions are controlled by the user’s role or project permissions (if the environment is in a project).
container_hosts_count	integer	ro	Number of container host VMs in the template.
created_at	timestamp	ro	The date and time that the environment was created.
description	string	rw	User-defined description of the environment. Limited to 1000 characters. Null allowed. UTF-8 character type.
disable_internet	Boolean	rw	If true, outbound internet is disabled for VMs in this environment. Note that VMs with public IPs or published services will still be exposed to the Internet.
errors	array	ro	Describes any errors with the environment.
error_details	array	ro	Provides details about any errors with the environment.
id	string	ro	Environment identifier.
last_run	timestamp	ro	The date and time that the environment was last run. If `null`, the environment hasn’t been run.
label_count	integer	ro	Number of labels in the environment (label = label category + label value key pair).
label_category_count	integer	ro	Number of label categories used in the environment.
licensed_vm_count	integer	ro	Number of licensed VMs in the environment
name	string	rw	User-defined name of the environment. Limited to 255 characters. UTF-8 character type. Defaults to source template’s name if `null` is provided.
network_count	integer	ro	Number of networks in the environment.
networks	array	ro	Array of networks in the environment. Every environment can have multiple networks; the number of total networks that can be created is restricted by your customer account’s network usage limit. Networks are added to this list when they are connected to a network adapter on a VM in the environment. Similarly, networks are removed from this list when they are disconnected from network adapters on VMs in the environment. For more information, see Network Interface v2 Resource
note_count	integer	ro	Number of environment notes in this environment.
outbound_traffic	Boolean	rw	If true, outbound internet is disabled for VMs in this environment.
owner	integer	wo	User ID of the environment’s owner. This field is only used to change the environment owner; it isn’t displayed during a GET request.
owner_id	integer	ro	User ID of the environment’s owner.
owner_name	string	ro	Name of the environment’s owner.
owner_url	URI	ro	URI reference of the environment’s owner (e.g., https://cloud.skytap.com/v2/users/123456).
platform_errors	array	ro	Array containing information about select errors. Each object contains an incident_id parameter that can be used to troubleshoot issues with the Skytap support team.
prefer_local_routing	Boolean	rw	If true, different subnets within an environment can communicate with each other.
project_count	integer	ro	Number of projects that this environment belongs to.
published_service_count	integer	ro	Number of published services across all VMs in the environment.
public_ip_count	integer	ro	Number of public IPs attached to network adapters across all VMs in the environment.
publish_set_count	integer	ro	Number of publish sets configured for this environment. Note: This number only counts published sets; it doesn’t count published URLs within those sets.
rate_limited	Boolean	ro	If true, the environment is being rate-limited due to a high amount of activity in the account. For more information, see API best practice: Checking for busyness.
region	string	ro	Region that the resource is housed in (for example, US-West). The environment will exist in the same region as the template it was created from.
region_backend	string	ro	Region that the resource is housed in (for example, US-West).
routable	Boolean	rw	Indicates whether networks within the environment can route traffic to one another.
runstate	string	rw	Because it can potentially represent the states of many VMs, the ‘runstate’ of an environment is a synthesized value. The environment runstate results should be interpreted as follows: running – one or more VMs are running stopped – all VMs are stopped suspended – one or more VMs are suspended, others are stopped For information about editing this field, see Run/Stop/Suspend/Restart Environment UTF-8 character type. .
schedule_count	integer	ro	Number of schedules that include this environment in an action.
sequencing_enabled	Boolean	ro	If true, VM sequencing is on.
shutdown_at_time	timestamp	rw	The date and time that the environment will be automatically shut down. If shutdown_on_idle and shutdown_at_time are both `null`, automatic shut down is disabled.
shutdown_on_idle	integer	rw	The number of seconds an environment can be idle before it’s automatically shut down. If shutdown_on_idle and shutdown_at_time are both `null`, automatic shut down is disabled.
storage	integer	ro	Amount of storage space consumed by the environment (in MB). This is calculated by adding the total storage space consumed by all disks in all of the environment’s VMs.
suspend_at_time	timestamp	rw	The date and time that the environment will be automatically suspended. If suspend_on_idle and suspend_at_time are both `null`, automatic suspend is disabled.
suspend_on_idle	integer	rw	The number of seconds an environment can be idle before it’s automatically suspended. If suspend_on_idle and suspend_at_time are both `null`, automatic suspend is disabled.
svms	integer	ro	The amount of Metered RAM this environment will consume when running. For information about how Metered RAM is calculated, see Usage Overview.
svms_by_architecture	object	ro	Lists the amount of x86 and power Metered RAM consumed by VMs in the environment. Example contents:`"svms_by_architecture": {"x86": 0, "power": 2}`.
tags	array	ro	Array of tags attached to the environment. To add or remove environment tags, see Environment tags sub-resource.
url	URI	ro	URI reference for the environment.
vm_count	integer	ro	Number of VMs in the environment.
vms	array	rw	Array of virtual machines in the environment. It is legal to have 0 entries in this array. The API supports adding elements to the array indirectly by adding VMs to the environment; it also supports deleting entries from the array by a DELETE request on the array member.
vpn_count	integer	ro	Number of VPNs attached to networks in the environment.

Environments v2 sub-resources

The environments resource contains several sub-resources that must be directly accessed from their own resource URIs. For documentation, see:

Environment VMs sub-resource
Environment containers sub-resource
Environment labels sub-resource
Environment networks sub-resource
Environment notes sub-resource
Environment sharing portals sub-resource
Environment tags sub-resource
Environment VM sequencing stages sub-resource
Environment multi-attach storage groups

Operations on environments

Get environment

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}.json

Response

Representation of the environment.

Get list of environments

Request

GET https://cloud.skytap.com/v2/configurations?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return a list of 50 environments that belong to a particular project and that have been created in the last 30 days, you could use the following request:

GET https://cloud.skytap.com/configurations?query=project_id:12345&created_at=now-30d+to+now&count=50&offset=0

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

scope

string

Filters results by resource ownership. Scope options:

me	Returns all resources owned by the user
company	Returns all resources owned by the user or shared with the user through projects

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

has_container_hosts	Filters results by whether the environment contains container host VMs. Value must be `true` or `false`.
name	Filters results by keyword (example, CentOS).
project_id	Filters results to display resources in a particular project (example: `12345`). To filter by environments that aren’t in a project, use `none`.
region	Filters results by region. Options: All+Skytap (includes environments from all Skytap-backed regions) A single region name (example, US-Central)
status	Filters results by environment runstate. Options: running suspended stopped busy copying error
user_id	Filters results by resource owner (example, `67890`). Limited to one user_id per request. This option isn’t available if the scope parameter is me.

created_at

string

Filters by environment creation date. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

last_run

string

Filters by environment last run date. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

sort

string

Sorts the results either in ascending or descending order. Options:

Sort by date created: created_at or created_at_desc.
Sort by date last run: last_run or last_run_desc.
Sort by name: name or name_desc.
Sort by region: region or region_desc.
Sort by VM count: vm_count or vm_count_desc.
Sort by Metered RAM amount: svms or svms_desc.
Sort by network count: network_count or network_count_desc.
Sort by storage size: storage or storage_desc.

label_category_id

integer

Filters results by all values in a label category (example: 12312)

label_value_id

integer

Filters results by label value (example: 77777)

Response

Returns a list of environments.

Some environment fields won’t be returned. To see a full representation of an environment, perform a GET request using the configuration ID (see Get Environment Description).

Get all environments

Request

Administrators can get a list of all environments with the following steps:

Submit a GET request to the Environments resource. Include the company scope.

GET https://cloud.skytap.com/v2/configurations?scope=company
Read the Content-Range header in the API response to get the total number of environments in the account (for example, if the header includes items 0-9/25, there are 25 environments).
Submit a GET request to the Environments resource that includes the count gathered above. Example:

GET https://cloud.skytap.com/v2/configurations?scope=company&count=25&offset=0

Response

Representations of environments in the account.

Edit environment

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}?{attr-name}={attr-value}

Response

Representation of the updated environment

Change environment owner

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "owner": "1245"
}

Required and optional parameters

Required parameters

owner

ID of the user you want to be the new environment owner. If the user is a restricted user, you must also include project_id with the ID of a project that the user has editor or manager privileges in.

Optional parameters

project_id

Contains a project ID; used to add the environment to a project during ownership reassignment. This parameter is required when reassigning ownership to a restricted user and optional when reassigning ownership to any other user type.

Response

Representation of the updated environment.

The operation will fail if the new owner doesn’t have the correct permissions or enough storage to own the environment.

Change environment runstate

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "runstate": "running"
}

Required parameters

runstate

One of running, stopped, halted, or suspended. Setting the environment’s runstate to one of the legal target states initiates state transitions for the contained VMs. Not all transitions are valid.

Runstate options

The following table describes the possible runstate transitions:

Starting Runstate	New Runstate
	running	reset	stopped	halted	suspended
running	No change	VMs are powered off and then run	Graceful shut down	Forced shut down	Suspended
stopped	Running environment	(invalid)	No change	No change	(invalid)
suspended	Running environment	(invalid)	(invalid)	Forced shut down	No change

Note that the reset and halted runstates don’t appear as starting states. These are pseudo-states:

halted	Setting the runstate of a running or suspend VM to halted forces a transition to stopped. This can be used when the VM won’t shut down due to errors in the guest VM. “Halting” is equivalent to pulling the plug on the VM, and it should only be used as last resort due to the potential for data corruption.
reset	Setting the runstate of a running configuration to reset powers off the VMs and then returns them to a running state.

Other states may appear from time to time, such as busy. Any state other than the states defined above should be interpreted as a sign of an environment (or VM) in transition. These aren’t legal ‘target’ states.

Response

The response will return immediately, even if the transition isn’t complete. The environment may have a “busy” runstate for some time after the initial request.

If your next API request depends on the environment being in the new state, you should poll until the environment is in the desired state and then make the next request.

Notes

Power VMs can't be suspended. If the environment runstate is changed to suspended, VMs that can't be suspended are skipped and remain running.
Setting the runstate to stopped succeeds only if the VMs have VMware Tools or open-vm-tools installed.

Change runstate of some VMs

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/

{
    "runstate": "running",
    "multiselect" : [
        "1234567",
        "8901234",
        "5678901"
    ]
}

Required Parameters

runstate	One of running, stopped, reset, halted, or suspended. For more information, see the runstate transitions defined in the parameters section for Run/Stop/Suspend/Restart Environment.
multiselect	An array of VM IDs that includes the VMs you want to run, stop, suspend, or restart.

Response

The response will return immediately, even if the transition isn’t complete. The VM may have a “busy” runstate for some time after the initial request.

If your next API request depends on the VM being in the new state, you should poll until the environment is in the desired state and then make the next request.

Enable automatic suspend when the environment is idle

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": "suspend_on_idle",
    "suspend_on_idle": 3600
}

Required parameters

suspend_type	Must be suspend_on_idle
suspend_on_idle	The number of seconds the environment should be idle before it automatically suspends. Valid range: 300 to 86400 seconds (5 minutes to 1 day).

Notes

An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
If multiple suspend or shut down options are sent in the same request, the suspend_type field determines which setting Skytap will honor.

Response

Returns a representation of the updated environment.

Enable automatic shutdown when the environment is idle

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": "shutdown_on_idle",
    "shutdown_on_idle": 3600
}

Required parameters

suspend_type	Must be shutdown_on_idle
shutdown_on_idle	The number of seconds the environment should be idle before it shuts down. Valid range: 300 to 86400 seconds (5 minutes to 1 day).

Notes

An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
If multiple suspend or shut down options are sent in the same request, the suspend_type field determines which setting Skytap will honor.

Response

Returns updated environment.

Enable automatic suspend for a specific date and time

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": "suspend_at_time",
    "suspend_at_time": "2018/05/20 14:20:00"
}

Required parameters

suspend_type	Must be suspend_at_time
suspend_at_time	The date and time the environment should be suspended. Format: `yyyy/mm/dd hh:mm:ss`.

By default, the suspend time uses the UTC offset for the time zone defined in your user account settings. Optionally, a different UTC offset can be supplied (for example: 2018/07/20 14:20:00 -0000). The value in the API response is converted to your time zone.

Notes

An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
If multiple suspend or shut down options are sent in the same request, the suspend_type field determines which setting Skytap will honor.

Response

Returns updated environment.

Enable automatic shut down for a specific date and time

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": "shutdown_at_time",
    "shutdown_at_time": "2018/05/20 14:20:00"
}

Required parameters

suspend_type	Must be shutdown_at_time
shutdown_at_time	The date and time the environment should be shut down. Format: `yyyy/mm/dd hh:mm:ss`.

By default, the shutdown time uses the UTC offset for the time zone defined in your user account settings. Optionally, a different UTC offset can be supplied (for example: 2018/07/20 14:20:00 -0000). The value in the API response is converted to your time zone.

Notes

An environment can't be set to automatically suspend and shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
If multiple suspend or shut down options are sent in the same request, the suspend_type field determines which setting Skytap will honor.

Response

Returns updated environment.

Disable automatic suspend

Request

suspend_type must be set to an empty string ("").

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": ""
}

Response

Returns updated environment.

Disable automatic shut down

Request

suspend_type must be set to an empty string ("").

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}.json

{
    "suspend_type": ""
}

Response

Returns updated environment.

Export environments report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/configurations/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/configurations/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/configurations/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/configurations/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request:
```
 GET https://cloud.skytap.com/configurations/exports/123456.csv
```

Response

The report is downloaded.

Environment VMs v2 resource

The environment VM resource represents an image of a single virtual machine.

Note that:

VMs don’t exist outside of environments or templates.
An environment or template can have multiple VMs.
Each VM is a unique resource. Therefore, a VM in a template will have a different ID than a VM in an environment created from that template.

Environment VMs v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}

Environment VMs v2 resource model

The element name is vms and the following fields are defined:

Field Name Type Access Description

asset_id

URI

Used to mount an ISO on the VM. For instructions, see Mount ISO Asset.

This field is write-only—it is always displayed as empty.

audio_in

Boolean

If true, audio input is enabled for SRA browser client sessions. To enable audio_in:

display_server must be set to rdp
audio_out must be set to true.

This field can be edited when the VM is powered off.

Not available in all accounts. For more information, see Connection types.

audio_out

Boolean

If true, audio output is enabled for SRA browser client sessions.
To enable audio_out, display_server must be set to rdp.
This field can be edited when the VM is powered off.

Not available in all accounts. For more information, see Connection types.

configuration_url string ro Location of VM. configuration_url is used for a VM in an environment. template_url is used for a VM in a template.

containers

object

If null, the VM isn’t a container host. To make the VM a container host, see Make the VM a container host.
If the VM is a container host, this object contains the following fields:

Field Name	Type	Description
agent_version	string	VM agent version number.
agent_status	string	Status of the VM agent.
containers_count	integer	Number of containers on this VM.

created_at timestamp ro Date and time the VM was created.

credentials array ro Array of credentials stored on the VM and available from the Credentials page in the UI. Includes text and id values.
To edit this array, see VM credentials sub-resource.

display_server

string

One of none, rdp, or ssh. Indicates whether an additional connection type is enabled in the Secure Remote Access (SRA) browser client. To use the audio_in and audio_out options, display_server must be set to rdp.This field can be edited when the VM is powered off.

Not available in all accounts. For more information, see Connection types.

display_server_port

string

Used to specify a custom port number for RDP or SSH connections in the SRA browser client.
The VM must be powered off to change this value.

Not available in all accounts. For more information, see Connection types.

error string ro If there was a fault or failure in performing some operation on the VM, this field will contain some information that will help interpret the error.

error_details object ro Provides details about any errors with the environment.

hardware hardware rw Hardware description. For more information, see Notes on the “hardware” element.

hardware_version integer ro VM hardware version number. Always null for Power.

id string ro VM identifier.

interfaces interface ro Array of virtual network interfaces.
To edit this array, see VM network adapters.

labels array ro Array of labels attached to the VM. Includes type, text, and id values.
To edit this array, see VM labels sub-resource.

lpar_id string ro LPAR ID of the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.

name

string

User-defined name. Limited to 100 characters.

The name will be truncated to 33 UTF-8 characters after saving.

notes array ro Array of notes stored on the VM. Includes text and id values.
To edit this array, see VM notes.

pinning_type string rw Indicates whether and how the VM should be pinned. Initially null until a VM is pinned. Accepted values are hard to pin a VM or null to unpin it. Always null for x86.

power_machine_type string ro Machine type of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.

power_model_number string ro Model number of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.

power_serial_number string ro Serial number of the Power host for the pinned VM. Initially null. After the VM is run, this field is populated with a value that persists, regardless of runstate, until the VM is powered off and unpinned. Always null for x86.

publish_set_refs

array

Array of references to published sets that include this VM. Contains details about the published sets and the anonymous URIs used to access them. Accessing these URIs doesn’t require a Skytap account.

These references exist only when the enclosing environment has been assigned one or more Published Set resources. If no such resources are defined then the publish_set_refs element won't be returned.

rate_limited Boolean ro Shows if the VM is rate-limited.

region_backend string ro Region that the resource is housed in (for example, US-West).

runstate string rw Runstate of VM. UTF-8 character type. See allowed values in parameters section of Change VM runstate below.

template_url string ro Location of VM. configuration_url is used for a VM in an environment. template_url is used for a VM in a template.

user_data string – user_data** does NOT appear in the normal representation of a VM; it must be requested from its own endpoint. See VM metadata.

Notes on the hardware element

The hardware element is syntactically nested but logically represents a single parameter named hardware with defined fields:

Field Name Type Access Description

architecture string ro Either power or x86.

boot_option string ro Either bios or uefi.

copy_paste_enabled

Boolean

If true, copy and paste is enabled between a local machine and the VM (when the VM desktop is accessed via the browser).

Copy/paste for Power is available only for SSH connections.

cpus

integer

Number of CPUs allocated to this virtual machine. Maximum limit depends on ram and the max_cpus setting.

The VM must be powered off to change this value.

cpw integer ro Estimated CPW (Commercial Processor Workload) for IBM i VMs.

cpus_per_socket

integer

rw (x86)
ro (Power)

This field can be edited only if the supports_multicore Boolean field is true.

Specifies how the total number of CPUs should be distributed across virtual sockets. By default cpus_per_socket is set to 1, meaning that a single core is distributed per virtual socket.
To create multi-core CPUs, set a higher number of CPUs per socket. For example, to create two quad-core processors in the VM, use the following settings: {"cpus": 8,"cpus_per_socket": 4}

Notes

The VM can't have more than 12 CPUs.
The number of CPUs must be evenly divisible by the number of cores per socket (for example, if you have 12 CPUs, the cores per socket must be 1, 2, 3, 4, or 6).
Always 1 for Power

disks array rw Array of virtual disks within the VM. The disk size is in MB; it will be converted to GB in the Skytap UI. The maximum disk size is 2,096,128 MB (1.999 TB).

displays integer rw Total number of displays enabled in the SRA browser client. Default is 1. Maximum is max_displays.

entitled_capacity integer ro Total entitled capacity enabled for this VM. This value is determined by ram and cpus

guestOS string rw This field tells the underlying host which operating system the VM is running and whether nested hypervisors are enabled.

guestOS_version

string

This field tells the underlying host which version of the operating system configured in guestOS that the VM is running.
For a complete list of supported guest OS versions, see Supported operating systems for Skytap VMs

guestOS_version applies only to Power VMs.

ibmi_boot_side string rw IPL source. For details about IBM i IPL types, see IPL type.

ibmi_boot_mode string rw IPL mode: normal for unattended, or manual for attended.

ibmi_current_pricing string ro Current pricing plan for this VM. Either hourly or monthly.

ibmi_future_pricing string rw The pricing plan that will be charged for this VM after the end of the current billing cycle. Either hourly or monthly.

ibmi_licenses

string

A list of IBM i licenses in use by this VM. Current valid settings are:

Field Name	Type	Description
ibmi_default	Boolean	`true` for licensed IBM i VMs.
ibmi_mimix_integration	Boolean	`true` if Precisely Assure MIMIX™ Software is enabled for this VM.
ibmi_powerha	Boolean	`true` if Power HA is enabled for this VM.
developer_licenses	integer	Number of IBM Rational Developer for i licenses enabled for this VM.

instance_type string ro This field is not currently in use. It always returns as null.

live_hardware_updates_enabled Boolean rw If true, dynamically configurable hardware is enabled for this VM.

max_cpus integer ro Maximum settable CPUs for this VM.

max_displays integer ro Total number of displays that can be enabled in the SRA browser client.

max_ram integer ro Maximum settable RAM for this VM.

maximum_video_ram_enabled Boolean rw If true, multiple-monitor display mode is enabled in the SRA browser client.

min_ram integer ro Minimum settable RAM for this VM.

nested_virtualization Boolean rw (x86)
ro (Power) If true, nested virtualization is enabled on the VM. For more information, see Enabling nested virtualization.
Always false for Power.

power_cpu_sharing_mode

string

vCPU sharing mode for Power. Either capped or uncapped. For more information, see Editing VM vCPUs and RAM.

The VM must be powered off to change this value.

ram

integer

Amount of RAM allocated to this VM.
Maximum limit depends on max_ram setting

The VM must be powered off to change this value.

rdp_port string ro Displays a port number, if the VM is configured to allow RDP connections in the SRA browser client over a custom port number.

rtc_start_time Unix timestamp rw (x86)
ro (Power) Used to set the VM BIOS clock at boot. Must be a UNIX timestamp (for example, 1456168430 is the Unix timestamp for Feb 22, 2016 7:13 PM UTC) or null (to disable this feature).
You can’t set the rtc_start_time if time-sync is enabled
Always null for Power.

svms integer ro Amount of Metered RAM used by this VM.

storage integer ro Total amount of storage consumed by the VM in MB. Calculated by adding the storage size of all disks within the VM.

supports_multicore Boolean ro Indicates whether the VM supports multi-core CPUs. Currently, multi-core CPUs are only supported for VMs set to hardware version 10 or 11.false for Power.

time_sync_enabled Boolean rw (x86)
ro (Power) If true, time-sync is enabled. For more information, see Editing VM hardware and guest OS settings.
Always false for Power.

ssh_port string ro Displays a port number, if the VM is configured to allow SSH connections in the SRA browser client over a custom port number.

uuid integer rw (x86)
ro (Power) User-defined, static Universal Unique Identifier (UUID). By default, this field is null; this means that Skytap automatically assigns the UUID. Maximum of 32 hexadecimal characters (0-9, A-F, a-f).
Always null for Power.

upgradable Boolean ro If true, the VM isn’t on the latest supported hardware version; the VM hardware version can be upgraded through the Skytap UI
Always false for Power.

vnc_keymap string rw (x86)
ro (Power) Keyboard language mapping (UTF-8). For a list of supported international keyboards and attribute values, see Using an international keyboard with a VM.
Always null for Power.

Environment VM v2 sub-resources

The environment VM resource contains several sub-resources that must be directly accessed from their own resource URIs. For documentation, see:

VM credentials sub-resource
VM metadata sub-resource
VM labels sub-resource
VM notes sub-resource
VM network adapters sub-resource
- Published services sub-resource
- Secondary IPs sub-resource

Operations on environment VMs

Get environment VM

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

Response

Selected virtual machine element.

Sample response

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/v2/configurations/12345678/networks/111111",
            "network_type": "automatic",
            "network_subnet": "10.0.0.0/24",
            "nic_type": "vmxnet3",
            "promiscuous": false,
            "secondary_ips": []
        }
    ],
    "notes": [],
    "labels": [],
    "credentials": [],
    "desktop_resizable": true,
    "local_mouse_cursor": true,
    "maintenance_lock_engaged": false,
    "region_backend": "skytap",
    "created_at": "2017/02/27 13:35:58 -0800",
    "can_change_object_state": true,
    "containers": null,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678",
    "publish_set_refs": []
}

Create VM

VMs are created indirectly, either by creating an environment from a template or by merging a template into an existing environment.

Update environment VM

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}?{attr-name}={attr-value}

Response

Updated VM element

Pin a Power VM to a host

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware":
    {
        "pinning_type":"hard"
    }
}

Response

Updated VM element

Unpin a Power VM from a host

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware":
    {
        "pinning_type":null
    }
}

Response

Updated VM element

Make a VM a container host

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "container_host": true
}

Power VMs (VMs with power architecture) can’t be container hosts.

Response

Sample response

If successful, updated representation of the VMs resource, with a populated containers object.

{
    ...
    "containers": {
        "docker_version": null,
        "agent_version": null,
        "agent_status": "Unknown",
        "containers_count": 0
    },
    ...
}

View a list of Docker networks on the container host

Request

GET https://cloud.skytap.com/v2/vms/{vm-id}/container_host_status.json?host_info=1

Response

Sample response

Representation of the containers information from the VMs resource, with a populated networks array.

{
    "docker_version": 1.12.2,
    "agent_version": 0.2-2f5a0831e62d,
    "agent_status": "Responding",
    "containers_count": 4,
    "networks": [
        {
            "id": "a222a18dffb48c48a1eae50a971799c92a507397e262bae6a64f7c2ca5eae0f0",
            "name": "bridge"
        }
    ]
}

Remove container host capability from a VM

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "container_host": false
}

Response

Updated representation of the VMs resource, with a null containers field.

{
    ...
    "containers": null,
    ...
}

Edit VM hardware settings (for example: CPUs)

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware": {
        "cpus": 8
    }
}

For a description of the editable fields, see Notes on the hardware element.

Response

Updated representation of the VM.

Sample response

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 8,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/v2/configurations/12345678/networks/111111",
            "network_type": "automatic",
            "network_subnet": "10.0.0.0/24",
            "nic_type": "vmxnet3",
            "promiscuous": false,
            "secondary_ips": []
        }
    ],
    "notes": [],
    "labels": [],
    "credentials": [],
    "desktop_resizable": true,
    "local_mouse_cursor": true,
    "maintenance_lock_engaged": false,
    "region_backend": "skytap",
    "created_at": "2017/02/27 13:35:58 -0800",
    "can_change_object_state": true,
    "containers": null,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678",
    "publish_set_refs": []
}

Add a disk

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware": {
        "disks": {
            "new": [5120]
        }
    }
}

Notes

The new disk's size should be provided in MB; it will be converted to GB in the Skytap UI. The minimum disk size is 2048 MB; the maximum is 2096128 MB (1.999 TB).
This request doesn't support URL query parameters. Use a request body to submit the data.

Response

Updated representation of the VM. The VM is busy until the new disk is added.

Sample response

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/v2/configurations/12345678/networks/111111",
            "network_type": "automatic",
            "network_subnet": "10.0.0.0/24",
            "nic_type": "vmxnet3",
            "promiscuous": false,
            "secondary_ips": []
        }
    ],
    "notes": [],
    "labels": [],
    "credentials": [],
    "desktop_resizable": true,
    "local_mouse_cursor": true,
    "maintenance_lock_engaged": false,
    "region_backend": "skytap",
    "created_at": "2017/02/27 13:35:58 -0800",
    "can_change_object_state": true,
    "containers": null,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678",
    "publish_set_refs": []
}

Edit the size of a disk

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware": {
        "disks": {
            "existing": {
                "disk-1234567-1234567-scsi-0-0": {
                    "id": "disk-1234567-1234567-scsi-0-0",
                    "size": 8192
                }
            }
        }
    }
}

Notes

The disk size should be provided in MB; it's converted to GB in the Skytap UI.
The minimum disk size is 2048 MB (2 GB), and the maximum disk size is 2096128 MB (1.999 TB).
You can't make a disk smaller; you can make it larger.
This request doesn't support URL query parameters. Use a request body to submit the data.

Response

Updated representation of the VM. The VM is busy until the disk is resized.

Sample response

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/v2/configurations/12345678/networks/111111",
            "network_type": "automatic",
            "network_subnet": "10.0.0.0/24",
            "nic_type": "vmxnet3",
            "promiscuous": false,
            "secondary_ips": []
        }
    ],
    "notes": [],
    "labels": [],
    "credentials": [],
    "desktop_resizable": true,
    "local_mouse_cursor": true,
    "maintenance_lock_engaged": false,
    "region_backend": "skytap",
    "created_at": "2017/02/27 13:35:58 -0800",
    "can_change_object_state": true,
    "containers": null,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678",
    "publish_set_refs": []
}

Delete a disk

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "hardware": {
        "disks": {
            "existing": {
                "disk-1234567-1234567-scsi-0-0": {
                    "id": "disk-1234567-1234567-scsi-0-0",
                    "size": null
                }
            }
        }
    }
}

This request doesn’t support URL query parameters. Use a request body to submit the data.

Response

Updated representation of the VM. The VM is busy until the disk is deleted.

Sample response

{
    "id": "12345678",
    "name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
    "runstate": "busy",
    "hardware": {
        "cpus": 1,
        "supports_multicore": true,
        "cpus_per_socket": 1,
        "ram": 1024,
        "svms": 1,
        "guestOS": "ubuntu-64",
        "max_cpus": 12,
        "min_ram": 256,
        "max_ram": 262144,
        "vnc_keymap": null,
        "uuid": null,
        "disks": [
            {
                "id": "disk-5236169-10952835-scsi-0-0",
                "size": 20480,
                "type": "SCSI",
                "controller": "0",
                "lun": "0"
            }
        ],
        "storage": 20480,
        "upgradable": false,
        "instance_type": null,
        "time_sync_enabled": true,
        "rtc_start_time": null,
        "copy_paste_enabled": true,
        "nested_virtualization": false,
        "architecture": "x86"
    },
    "error": false,
    "asset_id": null,
    "hardware_version": 10,
    "max_hardware_version": 10,
    "interfaces": [
        {
            "id": "nic-1234567-1234567-0",
            "ip": "10.0.0.2",
            "hostname": "host-2",
            "mac": "00:50:56:14:34:E4",
            "services_count": 0,
            "services": [],
            "public_ips_count": 0,
            "public_ips": [],
            "vm_id": "12345678",
            "vm_name": "Ruby on Rails - Ubuntu Server 14.04 - 64-bit",
            "status": "busy",
            "network_id": "111111",
            "network_name": "Network 1",
            "network_url": "https://cloud.skytap.com/v2/configurations/12345678/networks/111111",
            "network_type": "automatic",
            "network_subnet": "10.0.0.0/24",
            "nic_type": "vmxnet3",
            "promiscuous": false,
            "secondary_ips": []
        }
    ],
    "notes": [],
    "labels": [],
    "credentials": [],
    "desktop_resizable": true,
    "local_mouse_cursor": true,
    "maintenance_lock_engaged": false,
    "region_backend": "skytap",
    "created_at": "2017/02/27 13:35:58 -0800",
    "can_change_object_state": true,
    "containers": null,
    "display_server": null,
    "audio_in": false,
    "audio_out": false,
    "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678",
    "publish_set_refs": []
}

Change VM keyboard language

For a list of supported international keyboards and attribute values, see Using an international keyboard with a VM. Attribute values are listed in parentheses on that page.

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}?hardware[vnc_keymap]={attr-value}

Cannot be performed on Power VMs.

Response

Updated keyboard settings.

Disable copy and paste

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}?hardware[copy_paste_enabled]=false

Cannot be performed on Power VMs.

Response

Copy and paste is disabled between a local machine and the VM (when the VM is accessed via the browser client).

Enable nested virtualization

Note: Some guest OS types don’t support nested virtualization. For more information about nested virtualization, see Enabling nested virtualization.

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}?hardware[nested_virtualization]=true

Cannot be performed on Power VMs.

Response

If you attempt to enable nested virtualization on a Power VM or a VM whose guest OS doesn’t support it, you will receive an error message. Otherwise, you will be able run a VM from within the VM.

Change VM run state

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}.json

{
    "runstate": "running"
}

Required parameters

runstate : One of running, stopped, reset, halted, or suspended. The following table describes the possible runstate transitions for x86:

Runstate options

Starting Runstate	New Runstate
	Running	Reset	Stopped	Halted	Suspended
Running	No change	VM is powered off and then run	Graceful shut down	Forced shut down	Suspended
Stopped	Running VM	(invalid)	No change	No change	(invalid)
Suspended	Running VM	(invalid)	(invalid)	Forced shut down	No change

Power VMs can’t be suspended.
Note that the reset and halted runstates don’t appear as starting states. These are pseudo-states:
- halted: Setting the runstate of a running or suspend VM to halted executes a forcible transition to stopped. This can be used when the VM won’t shut down due to errors in the guest VM. “Halting” is equivalent to pulling the plug on the VM, and it should only be used as last resort due to the potential for data corruption.
- reset: Setting the runstate of a running VM to reset will power off the VM and then return it to a running state.

Response

The response will return immediately, even if the transition isn’t complete. The VM may have a “busy” runstate for some time after the initial request. If your next API request depends on the VM being in the new state, you should poll until the environment is in the desired state and then make the next request.

Notes

Power VMs can't be suspended.
Setting the runstate to stopped succeeds only if the VMs have VMware Tools or open-vm-tools installed.

Mount ISO Asset

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}

{
    "asset_id": "12345"
}

Required Parameters

asset_id – ID or URI of the ISO asset you want to mount.

Response

Updated VM element. If a non-ISO asset is specified, the operation will fail.

Download VM RDP File

Request

https://cloud.skytap.com/v2/configurations/<configuration-id>/vms/<vm-id>.rdp

Optional Parameters

interface_id – If you have multiple network adapters with RDP published services on the VM, you can specify which network adapter you want to download the RDP file for.

vpn_key – If you have multiple NAT VPNs connected to the VM, you can specify which NAT VPN connection to download the RDP file for.

Cannot be performed on Power VMs.

Response

One of the following RDP files:

If the VM has a NAT IP address from a Skytap VPN, an RDP file that connects over <NAT IP>:3389 will be returned
If the VM isn’t connected to a VPN, but it’s configured for an RDP published service, an RDP file that connects over the published service port opening will be returned.

Export a network endpoints report (.CSV)

The network endpoints include any published services, public IPs, and IPs associated with any connected network adapters (non-NAT IPs, VPN NAT IPs, and ICNR NAT IPs).

Step 1: Create the report

POST https://cloud.skytap.com/vms/{vm-id}/export_network_connections.json

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/vms/111111/export_network_connections/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/vms/111111/export_network_connections/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/vms/111111/export_network_connections/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request:
```
 GET https://cloud.skytap.com/vms/<vm-id>/export_network_connections/<export-id>.csv
```

Response

The report is downloaded.

Delete VM

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}

Deleted VMs can’t be recovered.

Response

Status only

VM credentials v2 resource

The environment VM and template VM resources contain a credentials sub-resource that must be directly accessed from its own URI.

VM credentials v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/credentials.json

https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/credentials.json

VM credentials v2 resource model

Field Name	Type	Access	Description
id	string	ro	Identifier
text	string	rw	VM credentials in `username / password` format.
notes	string	rw	User-defined text

Operations on VM credentials

Get VM credentials

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/credentials.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/credentials.json

Response

Credentials will be displayed.

Add VM credentials

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/credentials.json

{
    "text": "username / password",
    "notes": "User-defined note."
}

Required Parameters

text	Credentials in `username / password` format.

This action isn’t supported for VMs in templates.

Response

Added credentials will be displayed, along with a unique ID.

Edit VM credentials

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/credentials/{credential-id}.json

{
    "text": "username / password"
}

Required Parameters

text	Credentials in `username / password` format.

This action isn’t supported for VMs in templates.

Response

Edited credentials will be displayed.

Delete VM credentials

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/credentials/{credential-id}

This action isn’t supported for VMs in templates.

Response

Status.

VM labels v2 resource

The environment VM resource and template VM resource contain a labels sub-resource that must be directly accessed from its own URI.

VM labels v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/labels.json

https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/labels.json

VM labels v2 resource model

Field Name	Type	Access	Description
id	integer	ro	Template label identifier.
tag_type	string	wo	Label category name. Each label must have a tag_type on PUT. This is returned as type on GET. The label category must be a multi value label category.
text	string	rw	Contents of the label. Max 255 characters.
type	string	ro	Read-only representation of the tag_type field.

Supported operations on VM labels

Get VM labels

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/labels.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/labels.json

Response

Representation of the VM labels.

Add VM label

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/labels.json

POST https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/labels.json

{
    "tag_type": "SecurityTag",
    "text": "AV installed"
}

Required parameters

tag_type	Label category name. The label category type must be a multi value label category.
text	Contents of the tag.

Response

{
    "type": "Security note",
    "text": "AV installed",
    "id": "12345"
}

Edit VM label

VM labels can’t be edited. Instead, delete the VM label and add a new one.

Delete VM label

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/labels/{label-id}

DELETE https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/labels/{label-id}

Response

Status.

VM notes v2 resource

The environment VM resource and template VM resource contain a notes sub-resource that must be directly accessed from its own URI.

VM notes v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/notes.json

https://cloud.skytap.com/v2/templates/{template-id}/notes.json

VM notes v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
created_at	timestamp	ro	Date and time the note was created.
id	integer	ro	Note identifier.
text	string	rw	Contents of the note.
time	timestamp	ro	Date and time the note was created.
updated_at	timestamp	ro	Date and time the note was last edited.
user	object	ro	Representation of the user who created the note.
user_id	integer	ro	ID of the user who created the note.

Operations on VM notes

Get VM notes

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/notes.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/notes.json

Response

Representation of VM notes.

Add VM note

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/notes.json

POST https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/notes.json

{
    "text": "Note contents"
}

Response

Added note, along with a unique ID and information about the note creation.

Sample Response

{
    "id": "1234567",
    "user_id": 12345,
    "user": {
        "id": "12345",
        "url": "https://cloud.skytap.com/v2/users/12345",
        "first_name": "Corrina",
        "last_name": "Corrina",
        "login_name": "ccorrina",
        "email": "corrina_corrina@internet.net",
        "title": "",
        "deleted": false
        },
    "created_at": "2015/07/15 15:20:47 -0700",
    "updated_at": "2015/07/15 15:20:47 -0700",
    "text": "message"
}

Edit VM note

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/notes/{note-id}.json

PUT https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/notes/{note-id}.json

{
    "text": "Replacement contents"
}

Response

Edited note will be displayed.

Delete VM note

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/notes/{note-id}

DELETE https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/notes/{note-id}

Response

Status.

VM network adapters v2 resource

A Skytap network adapter is a virtualized network interface card (also known as a network adapter). It is logically contained in a VM and attached to a network.

Network adapters v2 reference URI

Network adapter are properties of VMs, so references to network adapters are extensions of references to environment and template VMs. The network adapter reference URI is as follows:

https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}

https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/interfaces/{interface-id}

Network adapters v2 resource model

The element name is interfaces and the following fields are defined:

Field Name Type Access Description

hostname string rw Limited to 32 characters. Valid characters are lowercase letters, numbers, and hyphens. Cannot begin or end with hyphens. Cannot be gw.

id string ro Identifier.

ip IP v4 address rw Internally, Skytap uses DHCP to provision an IP address (for example, 10.1.0.37) based on the MAC address. Skytap won’t assign the same IP address to multiple interfaces on the same network. This field can be modified if you want to provide your own network information.
Each segment of the IP address must be within the valid range (0 to 255, inclusive).

mac

string

rw for x86 VMs
ro for Power VMs

Internally, Skytap provisions a MAC address for the network adapter (for example, 00:1e:c2:c3:52:61). Skytap won’t assign the same MAC address to multiple interfaces. This field can be modified if you want to provide your own network information.

MAC addresses must begin with the hexadecimal digits 00:50:56.
The maximum value for a MAC address is `00:50:56:3F:FF:FF`.
The valid MAC address range is `00:50:56:00:00:00` to `00:50:56:3F:FF:FF`.

nat_addresses

object

This object will appear only on networks that are connected to a NAT-enabled network via ICNR or a VPN tunnel. It contains two arrays:

The vpn_nat_addresses array will provide the NAT IP and details about the associated VPN. Includes: ip_address, vpn_id, vpn_name, and vpn_url.
The network_nat_addresses array will provide the NAT IP address and details about the connected network. Includes: ip_address, network_id, network_name, network_url, configuration_id, and configuration_url.

network_id integer rw ID of the network that this network adapter is attached to.

network_name string ro Name of the network that this network adapter is attached to.

network_subnet string ro Subnet of network that this network adapter is attached to.

network_type string ro Type of network that this network adapter is attached to.

network_url URI ro URL for the network that this network adapter is attached to.

nic_type

string

rw for x86 VMs
ro for Power VMs

Network adapter type. One of: default, e1000, pcnet32, vmxnet, vmxnet3, or e1000e. UTF-8 character type.
Always default for Power VMs.

Not all NIC types are supported for all VMs; the VM guest operating system setting determines which NICs are supported.

promiscuous

Boolean

rw for x86 VMs
ro for Power VMs

Indicates whether promiscuous mode is enabled.
By default, this is set to false. Always false for Power VMs.

This field will be visible if promiscuous mode permissions are enabled for the customer account; otherwise, this field is hidden. This field is also read-only, unless the user has permission to edit promiscuous mode settings. For more information, see Enabling Promiscuous Mode on a Network Adapter.

public_ips_count

integer

If the VM is running:

The number of dynamic and static public IPs in use by the VM.
If the VM is suspended or powered off:
The number of static public IPs attached to the VMs

public_ip_attachments

array

An array of dynamic or static public IP objects attached to the network adapter. For dynamic IPs, these attachments appear even if the VM is suspended or shut down.

Name	Type	Description
id	integer	Unique ID associated with the PIP attachment to this network adapter
public_ip_attachment_key	integer	Unique ID associated with the PIP attachment to this network adapter
address	string	For dynamic public IPs: If the public IP address is deployed, the IPv4 address attached to the VM. null if the VM isn't running. For static public IPs: The IPv4 public IP address attached to the VM.
connect_type	integer	Either static or dynamic.
hostname	string	For dynamic PIPs, the VM hostname used in the FQDN. For static PIPs, null.
dns_name	string	For dynamic PIPs, the entire fully-qualified domain name for the VM. For static PIPs, null.
public_ip_key	string	Unique ID of the public IP address (if currently attached). Otherwise, null.

public_ips public_ip ro An array of a public IPs attached to the VM network adapter. If the VM is suspended or shut down, dynamic public IP addresses don’t appear in this list.

services array ro An array of a published services attached to the VM. To add a published service, see Published Service v2 Resource.

services_count integer ro Number of published services attached to the VM.

status string ro Runstate status of the VM that this network is attached to.

vm_id integer ro ID of the VM that this network is attached to.

vm_name string ro name of the VM that this network is attached to.

Supported operations on v2 network adapters

Get network adapter

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/interfaces/{interface-id}.json

Response

Identified network adapter element

List VM network adapters

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/interfaces.json

Response

Network interface elements

Create network adapter

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces.json

{
    "nic_type": "default"
}

The VM must be shut down before you can create a new network adapter on it.

Required parameters

nic_type

For x86 VMs, one of: default, e1000, pcnet32, vmxnet, vmxnet3, or e1000e.
For Power VMs, must be default.

This action isn’t supported for VMs in templates.

Response

New network adapter element

Update network adapter

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}.json

{
    "mac": "00:1e:c2:c3:52:61"
}

Required parameters

One or more of the following:

ip	IP address (can only be edited if the network adapter is connected to a network).
mac	MAC address; MAC address can’t be edited for Power VMs.
hostname	Hostname (can only be edited if the network adapter is connected to a network).
promiscuous	If true, promiscuous mode is enabled; promiscuous mode can’t be enabled for Power VMs.

Notes

The VM must be shut down before you can delete a network adapter.
This action isn't supported for VMs in templates.

Response

Updated network adapter

Connect network adapter to network

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}.json

{
    "network_id": "123456"
}

Required parameters

network_id

ID of the network you want to connect the network adapter to

This action isn’t supported for VMs in templates.

Response

Connected network adapter

Add/remove published services

See Published v2 Resource.

Add/remove secondary IPs

See Secondary IP v2 Resource.

Add dynamic public IP with DNS name to a network adapter

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/dynamic_public_ips.json

Response

Returns a list of dynamic public IP with DNS name objects attached to the VM. If the VM is running, the address field contains the current dynamic public IP address; if the VM is shut down or suspended, this field is null.

Sample response

[
    {
        "id": 109,
        "public_ip_attachment_key": 109,
        "address": "199.199.199.199",
        "connect_type": "dynamic",
        "hostname": "sample-host",
        "dns_name": "sample-host.companyname.skytapdns.com",
        "public_ip_key": "publicip-123456789"
    }
]

Edit DNS name used with the dynamic public IP address

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/dynamic_public_ips/{public-ip-attachment-key}.json

{
    "hostname": "new-name"
}

Requirements:

The hostname can contain only lowercase letters, numbers, and hyphens.
The hostname can’t begin or end with a hyphen.
Max. of 32 characters.

Response

Updated representation of the dynamic public IP address with DNS name object

Sample response

[
    {
        "id": 109,
        "public_ip_attachment_key": 109,
        "address": "199.199.199.199",
        "connect_type": "dynamic",
        "hostname": "new-name",
        "dns_name": "new-name.companyname.skytapdns.com",
        "public_ip_key": "publicip-123456789"
    }
]

Detach dynamic public IP address and DNS name

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/dynamic_public_ips/{public-ip-attachment-key}.json

Response

Updated list of dynamic public IP with DNS name objects attached to the VM.

Attach static public IP to network adapter

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/ips.json

{
    "ip": "10.0.0.1"
}

Required parameters

ip	Static public IP address

Response

Static public IP attached to specified network

View static public IPs attached to a network adapter

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/ips.json

Response

List of public IPs attached to a network adapter

Detach static public IP from a network adapter

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/ips/{public-ip-address}/detach.json

Response

Static public IP is detached

Disconnect network adapter from network

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}?network_id=

To disconnect from the network, you must set network_id to an empty value.

This action isn’t supported for VMs in templates.

Response

Disconnected network adapter

Delete network adapter

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}

Notes

The VM must be shut down before you can delete a network adapter.
This action isn't supported for VMs in templates.

Response

Network adapter is deleted

Published services v2 resource

Generally, a published service represents a binding of a port on a network interface to an IP and port that is routable and accessible from the public Internet. This mechanism is used to selectively expose ports on the guest to the public Internet.

Published services exist and are managed as aspects of network interfaces—that is, as part of the overall environment element.

Published services v2 reference URI

Published services is a resource located within the network interface resource.

https://cloud.skytap.com/v2/configurations/<{configuration-id}>/vms/<{vm-id}>/interfaces/<{interface-id}>/services/<{service-id}>

https://cloud.skytap.com/v2/templates/<{template-id}>/vms/<{vm-id}>/interfaces/<{interface-id}>/services/<{service-id}>

Published services v2 resource model

The element name is services and the following fields are defined:

Field Name	Type	Access	Description
external_ip	string	ro	Exposed routable host address. Connections to this address and port (below) are routed to the internal port in the guest VM. The external IP and port are selected by Skytap. For the IP address that the returned URL resolves to, see: Published services.
external_port	integer	ro	Exposed routable port. The port number is selected by Skytap.
id	string	ro	Identifier.
internal_port	integer	rw	The port that is exposed on the interface. Typically this will be dictated by standard usage (e.g., port 80 for http traffic, port 22 for SSH).

Operations on v2 published services

Get published service description

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services/{service-id}.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/interfaces/{interface-id}/services/{service-id}.json

Response

Representation of the published service.

{
    "id": "3389",
    "internal_port": 3389,
    "external_ip": "76.191.118.29",
    "external_port": 12345
}

List published services

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services.json

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/interfaces/{interface-id}/services.json

Response

A list of published services.

Add a published service

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services.json

{
    "internal_port": 8080
}

Required parameters

internal_port

Port number you want to open.

In the request body, port can be used in place of internal_port . internal_port will be returned in the response body.

You can’t perform this action on VMs in templates.

Response

Representation of new published service.

{
    "id": "3389",
    "internal_port": 3389,
    "external_ip": "76.191.118.29",
    "external_port": 12345
}

Delete a published service

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/services/{port-number}

You can’t perform this action on VMs in templates.

Response

Status

Secondary IP addresses v2 resource

Sometimes called IP aliasing, secondary IP addresses are useful for tasks such as setting up multiple sites on virtual web hosting or having multiple connections to a network, each of which can serve a different purpose.

Secondary IP addresses v2 reference URI

Secondary IP addresses is a resource located within the network adapter resource on environment VMs. This resource doesn’t exist for template VMs.

https://cloud.skytap.com/v2/configurations/<configuration-id>/vms/<vm-id>/interfaces/<interface-id>/secondary_ips/<ip-id>

Secondary IP addresses v2 resource model

The element name is secondary_ips and the following fields are defined:

Field Name	Type	Access	Description
address	IP address	rw	Secondary IP address assigned to the network adapter.
id	string	ro	Identifier

Operations on v2 secondary IP addresses

List secondary IP addresses

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/secondary_ips.json

Response

Representation of the secondary IP addresses

Add a secondary IP address

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/secondary_ips.json

{
    "address": "10.0.2.2"
}

Required parameters

address

An available IP address in the network’s subnet. One IP address can be added per request.

Response

Representation of the secondary IP address, with added ID field. If the requested IP address isn’t available, an error will be returned.

{
    "id": "10.0.2.2",
    "address": "10.0.2.2"
}

Edit a secondary IP address

Secondary IP addressess can’t be edited. Instead, detach the unwanted secondary IP address and create a new one.

Detach a secondary IP address

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/secondary_ips/{ip-id}

Where ip-id is the ID of the secondary IP address.

Response

Removed secondary IP address.

VM metadata v2 resource

(The environment VM resource and template VM resource contain a metadata sub-resource that must be directly accessed from its own URI. This is a free-form text field used in automation scenarios. For more information, see Accessing the VM Metadata Service.

VM metadata v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/user_data.json

https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}/user_data.json

VM metadata v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
contents	string	rw	Contents of the metadata field. `null` if empty. This field is limited to 16,384 characters. UTF-8 character type.

Supported operations on VM metadata

Get VM metadata

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/user_data.json

Response

Contents of metadata field.

Update VM metadata

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/user_data.json

{
    "contents": "Text you want saved in the metadata field"
}

Required parameters

contents

Any text you want saved in the user_data field.

This action isn’t supported for VMs in templates.

Response

Updated metadata field.

Remove contents of VM metadata field

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/user_data.json

{
    "contents": null
}

This action isn’t supported for VMs in templates.

Response

Updated metadata field.

Environment containers v2 resource

The environment resource contains a containers sub-resource that must be directly accessed from its own URI.

Environment containers v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/containers

Environment containers v2 resource model

The containers resource contains an array of containers on container host VMs in the environment. For more information about the container resource model, see Containers v2 resource.

Operations on environment containers

Get list of containers in an environment

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/containers?count=20&offset=0

Required and optional parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

query

string

Filters the results.
Options:

container host (VM)	string	Filters by container host VM. Syntax: query=vm_id:12345
status	string	Filters by container status. Syntax: query=status:running Options: created running paused restarted exited

sort

string

Sorts the results either in ascending or descending order.
Options:

Sort by date created: created_at or created_at_desc
Sort by VM container host name: host or host_desc
Sort by image: image or image_desc
Sort by name: name or name_desc
Sort by status: status or status_desc

For example, to see running containers on a container host with the VM ID 333333:

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/containers?count=20&offset=0&query=vm_id:333333,status:running

Response

The API will return a read-only representation of the containers on container hosts in the environment

Sample response body

[
    {
        "id": 1122,
        "cid": "123456789abcdefghijk123456789abcdefghijk123456789abcdefghijk",
        "name": "nginxtest1",
        "image": "nginx:latest",
        "created_at": "2016/06/16 11:58:50 -0700",
        "last_run": "2016/06/16 11:58:51 -0700",
        "can_change_state": true,
        "can_delete": true,
        "status": "running",
        "privileged": false,
        "vm_id": 111000,
        "vm_name": "Docker VM1",
        "vm_runstate": "running",
        "configuration_id": 123456
    },
    {
        "id": 1123,
        "cid": "987654321abcdefghijk987654321abcdefghijk987654321abcdefghijk",
        "name": "skytap_agent",
        "image": "skytap/agent:latest",
        "created_at": "2016/06/16 11:48:07 -0700",
        "last_run": "2016/06/16 14:23:47 -0700",
        "can_change_state": true,
        "can_delete": true,
        "status": "running",
        "privileged": false,
        "vm_id": 111000,
        "vm_name": "Docker VM1",
        "vm_runstate": "running",
        "configuration_id": 123456
    }
]

Start, stop, pause, unpause or kill multiple containers in an environment

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/containers/update_multiple

{
    "runstate": "pause",
    "multiselect": [
        "1234567",
        "8901234"
    ]
}

runstate	must be one of start, stop, pause, unpause, or kill.
multiselect	must be an array of container IDs. All containers must be in the same environment.

Response

HTTP status code	Explanation
200	Success. At least one of the containers was updated. Containers that aren't accessible are skipped. Check the response body for the status of each container and any possible errors.
400	Containers aren’t all contained within a single environment or the environment could not be found.
404	You do not have permission to change the container runstates in this environment.
409	VM agent isn’t responding, container doesn’t exist (likely removed since the last API request), or the runstate change is invalid (attempting to pause a stopped container). See the returned error message for more detail.

Sample response body

[
    {
        "can_change_state": true,
        "can_delete": true,
        "cid": "7283e6203437312d633243dcae5ba7781a906f540ce4583d72fd6d4c15836274",
        "configuration_id": "111111",
        "created_at": "2016/08/10 15:39:40 -0700",
        "finished_at": null,
        "id": 1234567,
        "image": "nginx:latest",
        "last_run": "2016/08/10 15:39:40 -0700",
        "name": "nginx new",
        "privileged": false,
        "spawned_at": "2016/08/10 15:39:40 -0700",
        "status": "running",
        "vm_id": 809072,
        "vm_name": "Host 1",
        "vm_runstate": "running"
    },
    {
        "can_change_state": true,
        "can_delete": true,
        "cid": "e2ce2d89a77fee41dfcf220c99de066f39f4136d325aa53a93233bcf6ced0338",
        "configuration_id": "111111",
        "created_at": "2016/08/10 15:53:00 -0700",
        "error": "The container no longer exists.",
        "finished_at": "2016/08/10 16:12:27 -0700",
        "id": 8901234,
        "image": "centos",
        "last_run": "2016/08/10 15:53:00 -0700",
        "name": "centos",
        "privileged": false,
        "spawned_at": "2016/08/10 15:53:00 -0700",
        "status": "exited",
        "vm_id": 809072,
        "vm_name": "Host 1",
        "vm_runstate": "running"
    }
]

Environment labels v2 resource

The environment resource contains a labels sub-resource that must be directly accessed from its own URI.

Environment labels v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/labels

Environment labels v2 resource model

Field Name	Type	Access	Description
id	integer	ro	Label identifier.
label_category	string	wo on creation, then ro	Name of the label category that the label belongs to.
label_category_id	integer	ro	ID of the label category that the label belongs to.
label_category_single_value	Boolean	ro	If `true`, the label belongs to a single value label category.
value	string	wo on creation, then ro	Name of the label. Max. 255 characters.

Operations on environment labels

Get environment labels

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/labels.json

Optional pagination parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

If count and offset aren’t defined, the API will return 100 results. Example request:

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/labels.json?count=20&offset=0

Response

Representation of the environment labels

Sample response

[
    {
        "id": "111",
        "value": "ValueCorp",
        "label_category": "Customer",
        "label_category_id": "123456",
        "label_category_single_value": false
    },
    {
        "id": "333",
        "value": "Update home page",
        "label_category": "Feature",
        "label_category_id": "123457",
        "label_category_single_value": false
    }
]

Add labels to environment

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Each label must contain:

label_category	the name of an existing label category
value	the label value

Sample request to add two new labels to an environment

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/labels.json

[
    {
        "label_category": "Feature",
        "value": "BlackHat 2016 Demo"
    },
    {
        "label_category": "Team",
        "value": "Security"
    }
]

Notes

An environment can have up to 30 labels.
Each label category can contain up to 2,000 label values.
If the label category is single_value, you can only apply one label from that category to each environment. If the environment already contains a label from that category, the new label will replace the old label.
You can't edit existing label values. Instead, detach the label and then attach a new label in the same category.

Response

Updated representation of the environment labels sub-resource.

Sample response

[
    {
        "id": "333",
        "value": "Operations",
        "label_category": "Team",
        "label_category_id": "123452",
        "label_category_single_value": false
    }
]

Add labels to multiple environments

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id-1},{configuration-id-2}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Required parameters

An array or of one more label objects. Each label must contain:

label_category	the name of an existing label category
value	the label value

Response

Updated list of labels attached to each environment.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        },
        {
            "id": "12345677",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        }
    ]
}

Edit environment label

Environment labels can’t be edited. Instead, delete the label and add a new one.

Remove environment label

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/labels/{label-id}.json

The label won’t be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Environment lock v2 resource

The environments resource contains a lock sub-resource that must be directly accessed from its own URI.

Environment lock v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/lock.json

Environment lock v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
configuration_id	string	ro	ID of the locked environment.
configuration_url	string	rw	Contents of the note.
created_at	timestamp	ro	Date and time the environment was locked.
id	integer	ro	ID of the lock event.
reason	string	rw	Optional. Max. 500 characters.
user	object	ro	Representation of the user who created the note.
user_id	integer	ro	ID of the user who created the note.

Operations on v2 environment lock

Get a list of environment lock parameters

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/lock.json

Response

A representation of the environment lock parameters.

If the environment isn’t locked, the request returns an error: “This environment is not locked.”

Sample response

[
    {
        "id": 123,
        "reason": "You kids stop shutting down my server!",
        "created_at": "2020/06/17 14:26:10 -0700",
        "user_id": 12345,
        "user": {
            "id": "12345",
            "url": "https://cloud.skytap.com/v2/users/12345",
            "login_name": "user-name",
            "first_name": "User",
            "last_name": "Name",
            "email": "user-name@notarealserver.com",
            "role": "admin",
            "deleted": false
        },
        "configuration_id": 12345678,
        "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678"
    }
]

Lock the environment

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/lock.json?reason=Someone+keeps+shutting+this+server+down+so+you+leave+me+no+choice

The endpoint can also accept a JSON request body.

[
    {
        "reason": "You kids stop shutting down my server!"
    }
]

Optional parameters

Reason for locking the environment.

Response

List of environment lock parameters.

Sample response

[
    {
        "id": 123,
        "reason": "You kids stop shutting down my server!",
        "created_at": "2020/06/17 14:26:10 -0700",
        "user_id": 12345,
        "user": {
            "id": "12345",
            "url": "https://cloud.skytap.com/v2/users/12345",
            "login_name": "user-name",
            "first_name": "User",
            "last_name": "Name",
            "email": "user-name@notarealserver.com",
            "role": "admin",
            "deleted": false
        },
        "configuration_id": 12345678,
        "configuration_url": "https://cloud.skytap.com/v2/configurations/12345678"
    }
]

Unlock an environment

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id-1}/lock.json

Response

The lock is removed.

Environment Multi-Attach Storage resource

The environments resource contains a multi-attach storage sub-resource that must be directly accessed from its own URI.

Notes

Disk sets are excluded when you copy an environment or save it as a template.
Disk sets exist within an environment and can connect only to VMs in that environment.
A disk set can be attached to two Power VMs.
You can create up to five disk sets per region.
The total size of a disk set must be smaller than both the maximum storage for a VM and the maximum storage for your account.
The default maximum combined storage capacity that can be connected to a Power VM is 32 TB, including the disks in a multi-attach storage group disk set. For example, if a Power VM uses 1.5 TB of storage, you can connect a disk set with up to 30.5 TB.
The default maximum number of disks that can be connected to a Power VM is 32, including the disks in a multi-attach storage group disk set. For example, if a Power VM has two disks, you can connect a disk set with up to 30 disks.
To increase the total number of disks that can be connected to the Power VMs in an environment, contact Skytap Support

Environment multi-attach storage reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}.json

Environment multi-attach storage resource model

The element name is multi_attach_storage_groups.

The following fields are defined:

Field Name Type Access Description

id string ro ID of the group.

configuration_id string ro ID of the environments used to create the group .

hypervisor string rw The group hypervisor type. Currently, the only valid value is power.

name string rw The name of the group.

vm_attachments array rw Array of VMs attached to the group value.

storage_allocations

array

Array of storage allocations that are part of the group.

Name Type Acccess Description

id ro string Unique ID of this storage allocation

depot_key ro string ID of the storage depot

depot_type ro string Storage depot type

size ro string The size of the storage allocation in MB

disk_attachments

string

Array of storage devices (disks) configured for this allocation

Name	Type	Acccess	Description
id	ro	string	Unique ID of the associated storage allocation
controller	ro	string	ID of the disk controller
bus_type	ro	string	The storage controller bus type. Always `scsi`
bus_id	ro	string	The ID of the storage controller bus
lun	ro	string	The LUN (Logical Unit Number) of the storage device

Operations on multi-attach storage groups

A multi-attach storage group—referred to as a disk set in the UI—is a storage resource that can be shared with multiple VMs in an environment.

You can change multi-attach storage group attachments only for VMs that are powered off.

Get a multi-attach storage single group for an environment

Request

GET https://cloud.skytap.com/v2//multi_attach_storage_groups/`{storage-group-id}`.json

Response

Multi-Attach Storage disk set

Sample response

{
    "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
    "configuration_id": "81135602",
    "hypervisor": "power",
    "vm_attachments": [
        "12345678",
        "98765432"
    ],
    "storage_allocations": [
        {
            "id": "storage_allocation-1",
            "depot_key": "d53db02a7c124a22bfce2c31491592b1",
            "depot_type": "volume",
            "size": 2048,
            "disk_attachments": [
                {
                    "id": "storage_allocation_disk_attachment-57",
                    "controller": "disk_controller-××××××××-××××××××-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 5
                },
                {
                    "id": "storage_allocation_disk_attachment-60",
                    "controller": "disk_controller-yyyyyyyy-yyyyyyyy-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 5
                }
            ]
        }
    ]
}

Get multiple multi-attach storage groups for an environment

Request

GET https://cloud.skytap.com/v2//configurations/`{configuration-id}`/`{storage-group-id}`,`{storage-group-id}`.json

Response

Representation of all multi-attach storage groups in the environment

Sample response

[
    {
        "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
        "configuration_id": "81135602",
        "hypervisor": "power",
        "vm_attachments": [
            "23456789",
            "87654321"
        ],
        "storage_allocations": [
            {
                "id": "storage_allocation-1",
                "depot_key": "d53db02a7c124a22bfce2c31491592b1",
                "depot_type": "volume",
                "size": 2048,
                "disk_attachments": []
            },
            {
                "id": "storage_allocation-2",
                "depot_key": "a2ef7def37cb49aeb3bfdc65ce77ac0c",
                "depot_type": "volume",
                "size": 2048,
                "disk_attachments": []
            }
        ]
    },
    {
        "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
        "configuration_id": "987654",
        "hypervisor": "power",
        "vm_attachments": [
            "12345678",
            "98765432"
        ],
        "storage_allocations": [
            {
                "id": "storage_allocation-4",
                "depot_key": "a2ef7def37cb49aeb3bfdc65ce77ac0c",
                "depot_type": "volume",
                "size": 4096,
                "disk_attachments": []
            },
            {
                "id": "storage_allocation-5",
                "depot_key": "d53db02a7c124a22bfce2c31491592b1",
                "depot_type": "volume",
                "size": 4096,
                "disk_attachments": []
            }
        ]
    }
]

Create a multi-attach storage group

Request

POST https://cloud.skytap.com/v2/configurations/`{configuration-id}`/multi_attach_storage_groups.json

[
    {
    "name":"TestGroup",
    "hypervisor": "power"
    }
]

Required parameters

Required Parameters

name	The name of the multi-attach storage group.
hypervisor	The multi-attach storage group hypervisor type. Currently, the only valid value is power.

Response

Sample response

{
    "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
    "configuration_id": "81135602",
    "hypervisor": "power",
    "vm_attachments": [],
    "storage_allocations": []
}

Delete a multi-attach storage group

You can change multi-attach storage group attachments only for VMs that are powered off.

Request

DELETE https://cloud.skytap.com/v2/multi_attach_storage_groups/`{storage-group-id}`

Response

Status.

Create storage within a multi-attach storage group

You can change multi-attach storage group attachments only for VMs that are powered off.

Request

POST https://cloud.skytap.com/v2/multi_attach_storage_groups/`{storage-group-id}`/storage_allocations.json

{
    "spec":
    {
        "volume":
        [
            2048,
            2048
        ]
    }
}

Required parameters

Required Parameters

volume

The disk size in MB.

Response

Updated representation of the multi-attach storage groups.

Sample response

{
    "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
    "configuration_id": "81135602",
    "hypervisor": "power",
    "vm_attachments": [],
    "storage_allocations": [
        {
            "id": "storage_allocation-30",
            "depot_key": "a2ef7def37cb49aeb3bfdc65ce77ac0c",
            "depot_type": "volume",
            "size": 2048,
            "disk_attachments": []
        },
        {
            "id": "storage_allocation-31",
            "depot_key": "d53db02a7c124a22bfce2c31491592b1",
            "depot_type": "volume",
            "size": 2048,
            "disk_attachments": []
        }
    ]
}

Delete storage from within a multi-attach storage group

You can change multi-attach storage group attachments only for VMs that are powered off.

Request

DELETE https://cloud.skytap.com/v2/multi_attach_storage_groups/`{storage-group-id}`/storage_allocations.json

{
    "allocation_ids": 
    [
        "storage-allocation-id-30", 
        "storage-allocation-id-31"
    ]
}

Response

Updated representation of the multi-attach storage groups.

Attach a multi-attach storage group to a VM

You can change multi-attach storage group attachments only for VMs that are powered off.

Request

POST https://cloud.skytap.com/v2/multi_attach_storage_groups/`{storage-group-id}`/vm_attachments.json

{
    "vm_ids": 
    [
        "12345678",
        "87654321"
    ]
}

Response

Updated representation of the multi-attach storage groups.

Sample response

{
    "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
    "configuration_id": "81135602",
    "hypervisor": "power",
    "vm_attachments": [
        "12345678",
        "87654321"
    ],
    "storage_allocations": [
        {
            "id": "storage_allocation-1",
            "depot_key": "a2ef7def37cb49aeb3bfdc65ce77ac0c",
            "depot_type": "volume",
            "size": 2048,
            "disk_attachments": [
                {
                    "id": "storage_allocation_disk_attachment-57",
                    "controller": "disk_controller-29035167-37891559-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 5
                },
                {
                    "id": "storage_allocation_disk_attachment-60",
                    "controller": "disk_controller-29035167-37891560-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 5
                }
            ]
        },
        {
            "id": "storage_allocation-2",
            "depot_key": "d53db02a7c124a22bfce2c31491592b1",
            "depot_type": "volume",
            "size": 2048,
            "disk_attachments": [
                {
                    "id": "storage_allocation_disk_attachment-58",
                    "controller": "disk_controller-29035167-37891559-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 6
                },
                {
                    "id": "storage_allocation_disk_attachment-61",
                    "controller": "disk_controller-29035167-37891560-scsi-0",
                    "bus_type": "scsi",
                    "bus_id": 0,
                    "lun": 6
                }
            ]
        }
    ]
}

Detach a multi-attach storage group from a VM

A multi-attach storage group can be detached only from VMs that are powered off.

Request

DELETE https://cloud.skytap.com/v2/multi_attach_storage_groups/`{storage-group-id}`/vm_attachments.json

{
    "vm_ids": 
    [
        "12345",
        "23456"
    ]
}

Response

Updated representation of the multi-attach storage groups.

Sample response

{
    "id": "mas-2dOu8ysdhhM1PkDWv6iRfRnaLRu",
    "configuration_id": "81135602",
    "hypervisor": "power",
    "vm_attachments": [],
    "storage_allocations": [
        {
            "id": "storage_allocation-1",
            "depot_key": "d53db02a7c124a22bfce2c31491592b1",
            "depot_type": "volume",
            "size": 4096,
            "disk_attachments": []
        },
        {
            "id": "storage_allocation-2",
            "depot_key": "a2ef7def37cb49aeb3bfdc65ce77ac0c",
            "depot_type": "volume",
            "size": 4096,
            "disk_attachments": []
        }
    ]
}

Environment networks v2 resource

Networks aren’t top-level elements of the API. Rather, they are elements properly contained within an environment. Operations on them are implicitly on the containing environment.

Environment networks v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{networks-id}

Environment networks v2 resource model

The element name is networks and the following fields are defined:

Field Name	Type	Access	Description
domain	string	rw	Domain name for the Skytap network. Limited to 64 characters. Valid characters are lowercase letters, numbers, and hyphens. Can’t be blank, must not begin or end with a period, and must start and end with a letter or number. This field can be changed only when all virtual machines in the environment are stopped (not suspended or running). domain can only be defined and edited for automatic networks (see network_type below).
gateway	string	rw	Gateway IP address.
id	integer	ro	Identifier.
name	string	rw	User defined name of the network. Limited to 255 characters. UTF-8 character type.
nat_pool_remaining	integer	ro	Remaining assignable IP addresses for NAT. Does not appear if network isn’t NAT-enabled.
nat_pool_size	integer	ro	The total number of IP addresses for external mapping. Does not appear if network isn’t NAT-enabled.
nat_subnet	string	rw	A CIDR block which determines the external IP addresses which will be assigned to network interfaces on connected networks. The larger the subnet, the larger the IP pool will be. Does not appear on manual networks or if an automatic network isn’t NAT-enabled. Cannot overlap with subnet (see above). Can be unset with `""`.
network_type	string	rw	Type of network (must be automatic or manual). Once it’s defined, this field can’t be edited.
primary_nameserver	string	rw	User-provided primary name server for this network. On an automatic network, Skytap provisions the domain name servers. Users can optionally override this and provide their own primary and secondary name servers. If this value is set, all name resolution requests are routed to this server. Must be a valid IPv4 address.
region	string	ro	Region that the resource is housed in (for example, US-West).
secondary_nameserver	string	rw	User-provided secondary name server for this network. The secondary_nameserver is used if the primary_nameserver doesn’t resolve.
subnet	string	rw	Defines the subnet address and subnet mask size in CIDR format (for example, 10.0.0.0/24). IP addresses for the VMs are assigned from this subnet and standard network services (DNS resolution, CIFS share, routes to Internet) are defined appropriately for it. The subnet mask size must be between 16 and 30. Valid characters are lowercase letters, numbers, and hyphens. Cannot be blank, must not begin or end with a period, and must start and end with a letter or number. This field can be changed only when all virtual machines in the environment are stopped (not suspended or running). The subnet field replaces the previous subnet_addr and subnet_size fields. The subnet_addr and subnet_size fields are still supported, if you would like to define the subnet address and subnet size separately.
tunnelable	Boolean	rw	If true, this network can be connected to other networks.
tunnels	array	ro	List of connections between this network and other networks.
vpn_attachments	array	ro	Representations of the relationships between this network and any VPN or Private Network Connections it’s attached to, including whether the network is currently connected.

Operations on v2 environment networks

Get network description

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}.json

Response

Representation of the network

Sample response

{
    "id": "1234567",
    "url": "https://cloud.skytap.com/configurations/1111111/networks/123467",
    "name": "Network 1",
    "network_type": "automatic",
    "subnet": "10.0.0.0/24",
    "subnet_addr": "10.0.0.0",
    "subnet_size": 24,
    "gateway": "10.0.0.254",
    "primary_nameserver": null,
    "secondary_nameserver": null,
    "region": "US-West",
    "domain": "sampledomain.com",
    "vpn_attachments": [  
       {
          "id":"111111-vpn-1234567",
          "connected":false,
          "network":{
             "id":"1111111",
             "subnet":"10.0.0.0/24",
             "network_name":"Network 1",
             "configuration_id":"1212121"
          },
          "vpn":{
             "id":"vpn-1234567",
             "name":"CorpNet",
             "enabled":true,
             "nat_enabled":true,
             "remote_subnets":"10.10.0.0/24, 10.10.1.0/24, 10.10.2.0/24, 10.10.4.0/24",
             "remote_peer_ip":"199.199.199.199",
             "can_reconnect":true
          }
       },
       {
          "id":"111111-vpn-1234555",
          "connected":false,
          "network":{
             "id":"1111111",
             "subnet":"10.0.0.0/24",
             "network_name":"Network 1",
             "configuration_id":"1212121"
          },
          "vpn":{
             "id":"vpn-1234555",
             "name":"Offsite DC",
             "enabled":true,
             "nat_enabled":true,
             "remote_subnets":"10.10.0.0/24, 10.10.1.0/24, 10.10.2.0/24, 10.10.4.0/24",
             "remote_peer_ip":"188.188.188.188",
             "can_reconnect":true
          }
       }
    ],
    "tunnelable": false,
    "tunnels": []
}

Create automatic network

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/networks.json

{
    "name": "API Network",
    "network_type": "automatic",
    "subnet": "10.0.1.0/24",
    "domain": "sampledomain.com"
}

Required and optional parameters

Required parameters

name	Network name.
network_type	automatic.
subnet	Subnet address and subnet mask size.
domain	Network domain.

Optional parameters

gateway	Network gateway.
primary_nameserver	Primary custom DNS server.
secondary_nameserver	Secondary custom DNS server; can only be specified if a primary name server is specified; must be combined with primary_nameserver.
tunnelable	If true, network can be connected to other networks.
nat_subnet	NAT subnet address and subnet mask size.

Response

Representation of the new network

Sample response

{
    "id": "2881190",
    "url": "https://cloud.skytap.com/configurations/4745364/networks/2881190",
    "name": "API Network",
    "network_type": "automatic",
    "subnet": "10.0.1.0/24",
    "subnet_addr": "10.0.1.0",
    "subnet_size": 24,
    "gateway": "10.0.1.254",
    "primary_nameserver": null,
    "secondary_nameserver": null,
    "region": "US-West",
    "domain": "sampledomain.com",
    "vpn_attachments": [],
    "tunnelable": false,
    "tunnels": []
}

Create Manual Network

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/networks.json

{
    "name": "API Network",
    "network_type": "manual",
    "subnet": "10.0.1.0/24",
    "gateway": "10.0.1.254"
}

Required and optional parameters

Required Parameters

name	Network name
network_type	manual
subnet	Subnet address and subnet mask size
gateway	Network gateway

Optional Parameters

primary_nameserver	Primary custom DNS server
secondary_nameserver	Secondary custom DNS server; can only be specified if a primary name server is specified; must be combined with primary_nameserver
tunnelable	If true, network can be connected to other networks

Response

Representation of the new network

Sample response

{
    "id": "2881190",
    "url": "https://cloud.skytap.com/configurations/4745364/networks/2881190",
    "name": "API Network",
    "network_type": "manual",
    "subnet": "10.0.1.0/24",
    "subnet_addr": "10.0.1.0",
    "subnet_size": 24,
    "gateway": "10.0.1.254",
    "primary_nameserver": null,
    "secondary_nameserver": null,
    "region": "US-West",
    "vpn_attachments": [],
    "tunnelable": false,
    "tunnels": []
}

Edit network

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}.json

{
    "name": "New network name"
}

Required parameters

One or more of the following:

name	Network name
subnet	Subnet address and subnet mask size
domain	Network domain
gateway	Network gateway
primary_nameserver	Primary custom DNS server
secondary_nameserver	Secondary custom DNS server; can only be specified if a primary name server is specified
tunnelable	If true, network can be connected to other networks
nat_subnet	NAT subnet address and subnet mask size

name and tunnelable are the only fields that can be edited while the network is in use. To edit most fields, you will need to shut down all VMs connected to the network.

Response

Representation of the updated network

Sample response

{
    "id": "1231234",
    "url": "https://cloud.skytap.com/configurations/9999999/networks/1231234",
    "name": "New network name",
    "network_type": "automatic",
    "subnet": "10.0.1.0/24",
    "subnet_addr": "10.0.1.0",
    "subnet_size": 24,
    "gateway": "10.0.1.254",
    "primary_nameserver": null,
    "secondary_nameserver": null,
    "region": "US-West",
    "domain": "sampledomain.com",
    "vpn_attachments": [],
    "tunnelable": false,
    "tunnels": []
}

Attach a network to a VPN or Private Network Connection

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}/vpns.json

{
    "vpn_id": "vpn-12345"
}

Response

A representation of the VPN or Private Network Connection attachment:

{
    "id": "111111-vpn-1234567",
    "connected": false,
    "network": {
        "id": "1111111",
        "subnet": "10.0.0.0/24",
        "network_name": "Network 1",
        "configuration_id": "1212121"
    },
    "vpn": {
        "id": "vpn-1234567",
        "name": "CorpNet",
        "enabled": true,
        "nat_enabled": true,
        "remote_subnets": "10.10.0.0/24, 10.10.1.0/24, 10.10.2.0/24, 10.10.4.0/24",
        "remote_peer_ip": "199.199.199.199",
        "can_reconnect": true
    }
}

Connect an Attached Network to a VPN or Private Network Connection

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}/vpns/{vpn-id}.json

{
    "connected": true
}

Response

The attached network will be connected to the VPN or Private Network Connection.

Disconnect an attached network from a VPN or Private Network Connection

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}/vpns/{vpn-id}.json

{
    "connected": false
}

Response

The network will be disconnected from the VPN or Private Network Connection.

Detach a network from a VPN or Private Network Connection

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}/vpns/{vpn-id}

Response

The network will be detached from the VPN or Private Network Connection.

List the VPNs and Private Network Connections the network is attached to

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}/vpns.json

Response

An array of attachments, indicating the connection status for each.

Delete network

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/networks/{network-id}

Response

Network element is deleted.

Environment notes v2 resource

The environment resource contains a notes sub-resource that must be directly accessed from its own URI.

Environment notes v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/notes.json

Environment notes v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
created_at	timestamp	ro	Date and time the note was created.
id	integer	ro	Note identifier.
text	string	rw	Contents of the note.
time	timestamp	ro	Date and time the note was created.
updated_at	timestamp	ro	Date and time the note was last edited.
user	object	ro	Representation of the user who created the note.
user_id	integer	ro	ID of the user who created the note.

Operations on environment notes

Get environment notes

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/notes.json

Response

Sample response body:

[
    {
        "id": "1234",
        "user_id": 9999,
        "user": {
            "id": "9999",
            "url": "https://cloud.skytap.com/v2/users/9999",
            "first_name": "Docs",
            "last_name": "User",
            "login_name": "docsuser",
            "email": "docsuser@internet.com",
            "title": "",
            "deleted": false
            },
        "created_at": "2015/09/08 00:26:48 -0800",
        "updated_at": "2015/09/08 00:26:48 -0800",
        "text": "Defect found"
    },
    {
        "id": "1235",
        "user_id": 8888,
        "user": {
            "id": "8888",
            "url": "https://cloud.skytap.com/v2/users/8888",
            "first_name": "Docs",
            "last_name": "Admin",
            "login_name": "docsadmin",
            "email": "docsadmin@internet.com",
            "title": "",
            "deleted": false
        },
        "created_at": "2015/09/09 00:23:12 -0800",
        "updated_at": "2015/09/09 00:23:12 -0800",
        "text": "See JIRA-1234"
    }
]

Add environment note

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/notes.json

{
    "text": "Contents of the note"
}

Required parameters

text	Any text you want saved as a note.

Response

New note.

Edit environment note

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/notes/{note-id}.json

{
    "text": "Edited version of the note"
}

Required parameters

text	New text you want saved in the note; this will override the previous note text.

Response

Updated note.

Delete environment note

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/notes/{note-id}

Response

Status.

Sharing portals are nested within the environments resource. An environment can have zero, one, or many sharing portals.

https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets/{publish-set-id}

Throughout the Skytap API, sharing portals are referred to as publish_sets. Skytap no longer uses the term publish_sets in the web interface; however, this name has been maintained in the API for backward-compatibility.

The element name is publish_sets and the following fields are defined:

Field Name Type Access Description

configuration_name string ro Name of the environment that the sharing portal provides access to.

custom_content

string

The content you want displayed in the custom content tab. The string can contain plain text or HTML. Limited to 32kb (approximately 32,000 characters).

For a list of supported HTML tags, see HTML Tags Allowed in Custom Content. For starter templates, see Custom Content for Published URLs - Starter Templates.

This field is required if custom_content_enabled is true.

custom_content_enabled Boolean rw If true, the sharing portal includes a tab with the contents of the custom_content field. The tab must have a name, defined in the custom_title field below.

custom_content_is_default Boolean rw If true, the custom content tab opens first in the sharing portal.

custom_title

string

Name of the custom content tab. Max. 32 characters.

This field is required if custom_content_enabled is true.

desktops_url string ro Access URL for single_url sharing portals. For multiple_url sharing portals, the access URLs are listed as desktop_url in the VMs array (see below).

end_time

string

(Optional) Used to restrict the time of day the sharing portal can be accessed.

When defining an access window, start_time and end_time must be entered as a pair. When editing an existing access window, start_time and end_time can be edited separately.
The start and end times are expressed in HH:MM format.
To delete an access window, enter `null` for start_time and end_time.

expiration_date

string

(Optional) The date and time the sharing portal expires. After this time, no VM can be accessed via the sharing portal. Use the format: yyyy/mm/dd hh:mm:ss (“2015/11/28 10:45:00”)

expiration_date and expiration_date_tz must be entered as a pair.

expiration_date_tz

string

(Optional) Time zone for the expiration date. For a list of time zones, see Time Zones and UTC Offsets.

expiration_date and expiration_date_tz must be entered as a pair.

id integer ro Unique ID for the sharing portal.

multiple_url Boolean ro Indicates whether the publish_set_type is multiple_url.

name string rw Descriptive name of sharing portal; doesn’t need to be unique.

password

string

If a password is included in this field, it’s required to access the sharing portal. If you don’t want to require a password for access, enter an empty string in this field.

You can't retrieve a password by viewing this field, but you can tell whether a password has been set:

If no password is set, the returned element is empty.
If a password is set, the API returns a string of 10 asterisks: **********

If ********** is sent as the value of the password element, it's ignored and the current password isn't changed.

publish_set_type

string

Type of sharing portal.

single_url	Single sharing portal
multiple_url	Sharing portal set

runtime_left_in_seconds integer ro For single_url sharing portals with a runtime_limit set, this field display the remaining time that the sharing portal is available. For all other conditions, this field is null.

runtime_limit integer rw (Optional) The number of minutes the VMs can be accessed via a sharing portal. Once this limit is met, the VMs will be set to “do_not_publish”; they won’t be suspended by this action. You can increase the limit to provide additional access. null if not in use.

sso_required Boolean rw This field is visible only for accounts with SSO enabled.
If true, SSO is used to authenticate users accessing the sharing portal. If true, password (above) must be empty.

start_time

string

(Optional) Used to restrict the time of day the sharing portal can be accessed.

When defining an access window, start_time and end_time must be entered as a pair. When editing an existing access window, start_time and end_time can be edited separately.
The start and end times are expressed in HH:MM format.
To delete an access window, enter null for start_time and end_time.

support_url

string

(Optional) Used to customize the support link that appears in the sharing portal. If this field is empty, the default help page is used (http://help.skytap.com/#help-with-vms.html).
String format must be one of the following:

http://example.com
https://example.com
mailto:support@example.com

time_zone string rw (Optional) Defines the time_zone for the access window. If this isn’t defined, your personal time zone is used. For a list of time zones, see Time Zones and UTC Offsets.

url string ro URL of the sharing portal resource for UI and API access.

vms

array

ro/rw

Representation of VMs in the sharing portal.

Field Name	Type	Access	Description
access	string	rw	VM access level. Must be one of: do_not_publish (Labeled "Excluded" in the UI). run_and_use (Labeled "Full Control" in the UI). use view_only For access level descriptions, see Sharing VMs and environments with sharing portals.
desktop_url	string	ro	Access URL for the VM.
error	Boolean	ro	Indicates whether the VM has an error.
error_details	obect	ro	Provides details about any errors with the environment.
name	string	ro	VM name
run_and_use.	Boolean	ro	true if the access level is run_and_use.
vm_ref	URI	rw	VM URI

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets.json?count=20&offset=0

Sort and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add query parameters to sort your request. For example, to return a list of the 10 most recently-created sharing portals in an environment, you could use the following request:

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets.json?count=10&offset=0</var>&sort=created_at

The following table contains a list of optional sort parameters:

Parameter Name	Type	Description
sort	string	Sorts the results either in ascending or descending order. Options Sort by date created: created_at or created_at_desc. Sort by name: name or name_desc. Sort by VM count: vm_count or vm_count_desc. Sort by sharing portal type: publish_set_type or publish_set_type_desc.

Response

Representation of sharing portals.

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets.json

{
    "name": "publishedsetname",
    "runtime_limit": 120,
    "publish_set_type": "multiple_url",
    "expiration_date": "2015/05/20 19:00:00",
    "expiration_date_tz": "Pacific Time (US & Canada)",
    "start_time": "08:00",
    "end_time": "17:00",
    "time_zone": "Pacific Time (US & Canada)",
    "password": "samplepassword",
    "sso_required": false,
    "vms": [
        {
        "vm_ref": "https://cloud.skytap.com/v2/configurations/111111/vms/123456",
        "access": "use"
        },
        {
        "vm_ref": "https://cloud.skytap.com/v2/configurations/111111/vms/789012",
        "access": "do_not_publish"
        }
    ],
    "custom_content_enabled": true,
    "custom_content": "<h1>Title</h1>Here is some custom content",
    "custom_title": "Resources",
    "custom_content_is_default": true,
    "support_url": "mailto:support@internet.com"
}

Required and optional parameters

Response

Representation of the new sharing portal.

Sample response when `name` is the only defined parameter in the POST request

{
    "id": "22222",
    "name": "default",
    "url": "https://cloud.skytap.com/v2/configurations/111111/publish_sets/22222",
    "configuration_name": "Demo environment",
    "publish_set_type": "multiple_url",
    "runtime_limit": null,
    "runtime_left_in_seconds": null,
    "expiration_date": null,
    "expiration_date_tz": null,
    "start_time": null,
    "end_time": null,
    "time_zone": null,
    "multiple_url": true,
    "password": null,
    "use_smart_client": true,
    "sso_required": false,
    "vms": [
        {
        "name": "Ubuntu Linux (64-bit)",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/v2/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/v2/vms/b62c0972cd373c801abcdefc316b54b8/desktops"
        },
        {
        "name": "Ubuntu Server",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/v2/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/v2/vms/b62c0972cd373c801abcdefc316b54b8/desktops"
        }
    ],
    "custom_content_enabled": false
}

Sample response based on the sample request used above

{
    "id": "22222",
    "name": "default",
    "url": "https://cloud.skytap.com/configurations/111111/publish_sets/22222",
    "configuration_name": "Demo environment",
    "publish_set_type": "multiple_url",
    "runtime_limit": 120,
    "runtime_left_in_seconds": null,
    "expiration_date": "2015/05/20 19:00:00",
    "expiration_date_tz": "Pacific Time (US & Canada)",
    "start_time": "08:00",
    "end_time": "17:00",
    "time_zone": "Pacific Time (US & Canada)",
    "multiple_url": true,
    "password": "**********",
    "use_smart_client": true,
    "sso_required": false,
    "vms": [
        {
        "name": "Something else",
        "access": "use",
        "run_and_use": false,
        "vm_ref": "https://cloud.skytap.com/vms/12345",
        "error": false,
        "desktop_url": "https://cloud.skytap.com/v2/vms/b62c0972cd373c801abcdefc316b54b8/desktops"
        }
    ],
    "custom_content_enabled": true,
    "custom_content": "<h1>Title</h1>Here is some custom content",
    "custom_title": "Resources",
    "custom_content_is_default": true,
    "support_url": "mailto:support@internet.com"
}

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets/{publish-set-id}.json

Response

The reference model in the body of the response.

All fields will be returned, even if they have no contents. Note that the password will be returned as an empty element if not configured or as the obfuscated value ********** if it’s set.

View desktop URL

Request

The desktop_url or desktops_url will be listed as a string (https://cloud.skytap.com/v2/vms/wo5wroeciastluhieboespoe4oekoami/desktops).

GET https://cloud.skytap.com/v2/vms/wo5wroeciastluhieboespoe4oekoami/desktops

By default, this GET request will be recognized by the auto-suspend timer as activity in the environment. This means that auto-suspend won’t take effect if this request is made within the auto-suspend window you’ve set (e.g., 5 minutes, 60 minutes, etc.). If you would like the auto-suspend timer to ignore this request and not treat it as activity, include ?keep_idle=true in the request.

Response

A representation of the desktop URL.

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets/{publish-set-id}.json

Enter the parameters you want to edit in the request body.

For example, to change the runtime limit to 5 hours, enter:

{
    "runtime_limit": 300
}

Or, to change the expiration to November 28, 2015 at 11:00 AM in the Athens time zone, enter:

{
    "expiration_date": "2015/11/28 11:00:00",
    "expiration_date_tz": "Athens"
}

Response

Updated representation of sharing portal.

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/publish_sets/{publish-set-id}

Response

Status code

Environment tags v2 resource

The environments resource contains a tags sub-resource that must be directly accessed from its own URI.

Environment tags v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/tags.json

Environment tags v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
id	integer	ro	ID of the tag.
value	string	ro	Tag value. Maximum length: 255 characters. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID. Tag values aren’t case-sensitive (for example, “test”, “Test”, and “TEST” will share the same ID).

Operations on v2 environment tags

Get a list of tags attached to the environment

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/tags.json

Response

A representation of tags attached to the environment.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    }
]

Add tags to the environment

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/tags.json

[
    {
        "value": "Class 101"
    }
]

Required parameters

An array of objects comprising one or more value definitions.

Response

Updated list of tags attached to the environment. Each value will be assigned a tag ID. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    }
]

Add tags to multiple environments

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id-1},{configuration-id-2}/tags.json

[
    {
        "value": "Class 101"
    }
]

Required parameters

An array of objects comprising one or more value definitions.

Response

Updated list of tags attached to each environment.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        },
        {
            "id": "12345677",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        }
    ]
}

Remove a tag from the environment

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/tags/{tag-id}.json

This won’t delete the tag from your customer account; it will simply detach the tag from its association with this environment.

Response

Updated list of tags attached to the environment.

Sample response

[
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    },
    {
        "id": 1237,
        "value": "In progress"
    }
]

Environment metadata v2 resource

The environment resource contains a metadata (user data) sub-resource that must be directly accessed from its own URI. This is a free-form text field used in automation scenarios. For more information, see Accessing the VM Metadata Service.

Environment metadata v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/user_data.json

Environment metadata v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
contents	string	rw	Contents of the user data field. `null` if empty. This field is limited to 16,384 characters.

Operations on environment metadata

Get environment metadata

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/user_data.json

Response

Representation of the user_data field.

Update environment metadata

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/user_data.json

{
    "contents": "Text saved in the user_data field."
}

Parameters

contents

Any text you want saved in the user_data field.

Response

Updated representation of the user_data field.

Remove environment metadata

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/user_data.json

{
    "contents": null
}

Response

Updated representation of the user_data field.

Environment VM sequencing stages v2 resource

Stages aren’t top-level elements of the API. Rather, they are elements contained within an environment.

You can use the stage resource to establish the VM start up and shut down order within an environment (VM Sequencing). The run sequence is composed of four stages and a set of VMs that should be excluded from the sequence. All of the VMs within an environment are placed into one of these four stages or in the excluded VMs set (Do not run on the VM Sequencing page).

By default, all of the VMs are placed in Stage 4 and all of the delays are set to 0. This means that all of the VMs will start up, suspend, shut down, or power off at the same time.

Environment VM sequencing stages v2 reference URI

https://cloud.skytap.com/v2/configurations/{configuration-id}/stages

Environment VM sequencing stages v2 resource model

stages is an array of four elements. Within these four elements, the following fields are defined:

Field Name	Type	Access	Description
delay_after_finish_seconds	integer	rw	The number of seconds to wait after completing this stage before starting the next stage; this can be between `0` and `3600` (e.g., `60` minutes). This field is only recognized for start up sequences. Delays are ignored during suspend or shut down sequences.
index	integer	ro	The index of this stage relative to the other stages in the environment; `0` indicates the first stage, `1` indicates the second stage, `n` indicates stage (`n` + 1).
vm_ids	array (string)	rw	The IDs of the VM instances in a stage.

Operations on v2 Environment VM sequencing stages

Get the VM sequence description

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/stages.json

Response

A list of the environment’s VM sequencing stages in the following format:

[
    {
        "delay_after_finish_seconds": 300,
        "index": 0,
        "vm_ids": [
            "123456",
            "123457",
            ...
        ]
    },
    {
        "delay_after_finish_seconds": 600,
        "index": 1,
        "vm_ids": [
            "456789",
            "456788",
            ...
        ]
    },
    ...
]

Note that the excluded_vms_ids array won’t be displayed. You can view the contents of this array by making a request to

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/stages/excluded_vms.json

Edit the whole VM sequence

Request

To edit the whole VM sequence for an environment , make a PUT request and include the vm_ids for each of the four stages. Place any VMs that you don’t want to run in the excluded_vms_ids array. You can optionally include the delay_after_finish_seconds and index fields.

An example is provided below:

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/stages.json

{
    "excluded_vms_ids": [
        "111111",
        "222222"
    ],
    "stages": [
        {
            "delay_after_finish_seconds": 300,
            "vm_ids": [
                "123451",
                "123452"
            ]
        },
        {
            "delay_after_finish_seconds": 600,
            "vm_ids": [
                "123453",
                "123454"
            ]
        },
        {
            "delay_after_finish_seconds": 900,
            "vm_ids": [
                "123455",
                "123456"
            ]
        },
        {
            "delay_after_finish_seconds": 1200,
            "vm_ids": [
                "123457",
                "123458"
            ]
        }
    ]
}

Response

If the request was properly formed, the response will be an updated stage list in the format.

Note that the excluded_vms_ids array won’t be displayed. You can view the contents of this array by making a request to

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/stages/excluded_vms.json

[
    {
        "delay_after_finish_seconds": 300,
        "index": 0,
        "vm_ids": [
            "123451",
            "123452"
        ]
    },
    {
        "delay_after_finish_seconds": 600,
        "index": 1,
        "vm_ids": [
            "123453",
            "123454"
        ]
    },
    {
        "delay_after_finish_seconds": 900,
        "index": 2,
        "vm_ids": [
            "123455",
            "123456"
        ]
    },
    {
        "delay_after_finish_seconds": 1200,
        "index": 3,
        "vm_ids": [
            "123457",
            "123458"
        ]
    }
]

If the request array doesn’t contain all four stages, the API will return an error response and Skytap won’t make any changes to the stages.

View a stage within the VM sequence

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/stages/{stage_index}.json

Response

Returns the specified stage in the following format:

{
  "delay_after_finish_seconds": 300,
  "index": 1,
  "vm_ids": [
    "vm1_id",
    "vm2_id",
    ...
    ]
}

Returns an error if stage_index is less than 0 or greater than 3.

Edit a stage within the VM sequence

Request

PUT https://cloud.skytap.com/v2/configurations/{configuration-id}/stages/{stage_index}.json

{
    "stage": {
        "delay_after_finish_seconds": 300,
        "vm_ids": [
            "vm1a_id",
            "vm2a_id"
        ]
    }
}

You must include delay_after_finish_seconds and vm_ids in the request body.

Response

An updated representation of the stage:

{
    "delay_after_finish_seconds": 300,
    "index": 0,
    "vm_ids": [
    "123451",
    "123452"
    ]
 }

Check the status of a running VM sequence

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/staged_execution.json

Note that this request is to the Staged Execution sub-resource, not the Stages sub-resource.

Response

Displays information about the current sequence step in the following format:

Field Name	Type	Description
action_type	string	The current action (run, suspend, shutdown, or poweroff).
current_stage_delay_after_finish_seconds	integer	The number of seconds to wait after completing this stage before starting the next stage; this can be between 0 and 3600 (e.g., 60 minutes). This field is recognized only for start up sequences. Delays are ignored during suspend, shut down, or power off sequences.
current_stage_index	integer	The index of this stage relative to the other stages in the configuration; `0` indicates the first stage, `1` indicates the second stage, `n` indicates stage (`n` + 1).
current_stage_finished_at	timestamp	Time that the current stage finished executing.
vm_ids	array (string)	The IDs of the VM instances whose run states are changing.

Example response body:

{
  "action_type": "suspend",
  "current_stage_delay_after_finish_seconds": 300,
  "current_stage_index": 1,
  "current_stage_finished_at": timestamp or null,
  "vm_ids": [
    "123453",
    "123454"
    ]
}

A 404 error will return if the environment isn’t running, shutting down, suspending, or powering off.

The current stage will be the stage containing VMs that are currently running, suspending, shutting down, or powering off, or the stage where you’re waiting on a delay.

Cancel a running VM sequence

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/staged_execution

This request affects the Staged Execution sub-resource, not the Stages sub-resource.

Response

The VM sequence will stop running. All of the VMs in the current stage will finish starting up, shutting down, suspending, or powering off. No other stages or delays will take place.

If the VM sequence isn’t currently running, a 404 error will be returned.

Templates v2 resource

A template contains one or more virtual machine images, plus associated resources such as network configurations, as well as metadata such as notes and tags.

A template is a blueprint from which any number of runnable environments can be created. As such, a template isn’t directly runnable, and many of the template attributes in the API can’t be modified. For example, the “runstate” attribute will list the state of the VMs in this template, but it can’t be changed in the API.

Templates v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}

Templates v2 resource model

The element name is templates, and the following fields are defined:

Field Name Type Access Description

busy

Boolean

Describes if the template is busy.

If you attempt to perform an operation on a busy template, you will likely receive an error.

can_copy Boolean ro The user’s permissions relative to this template, controlled by the user’s role, the user’s project permissions (if the template is in a project), and whether or not the template is a public template; public templates can’t be modified.

can_delete Boolean ro The user’s permissions relative to this template, controlled by the user’s role, the user’s project permissions (if the template is in a project), and whether or not the template is a public template; public templates can’t be modified.

can_share Boolean ro The user’s permissions relative to this template, controlled by the user’s role, the user’s project permissions (if the template is in a project), and whether or not the template is a public template; public templates can’t be modified.

can_tag Boolean ro The user’s permissions relative to this template, controlled by the user’s role, the user’s project permissions (if the template is in a project), and whether or not the template is a public template; public templates can’t be modified.

container_hosts_count integer ro Number of container host VMs in the template

containers_count integer ro Number of containers in the template

created_at timestamp ro The date and time that the template was created

description string rw User-defined description. Limited to 1000 characters. Null allowed. UTF-8character type.

errors array ro Lists any template errors

id string ro Template identifier

label_count integer ro Number of labels in the template (label = label category + label value key pair)

label_category_count integer ro Number of label categories used in the template

last_installed timestamp ro The date and time that an environment was last created from this template. If null, then no environments have been created from the template.

licensed_vm_count integer ro Number of licensed VMs in the template

name string rw User-defined name. Limited to 255 UTF-8 characters. Defaults to source environment’s name with - Copy added if null is provided.

network_count integer ro Number of networks in the template

networks array ro Array of networks in the template

owner integer wo User ID of the template owner. This field is only used to change the template owner; it isn’t displayed during a GET request, or if the template is in the Skytap public library.

owner_url URI ro Template owner’s full URL (e.g., https://cloud.skytap.com/v2/users/12345). This field doesn’t exist for Skytap-owned public templates.

owner_name string ro Template owner’s first name and last name, as displayed in the Skytap UI. This field doesn’t exist for Skytap-owned public templates.

owner_id integer ro Template owner’s ID number. This field doesn’t exist for Skytap-owned public templates.

project_count integer ro Number of projects that this template belongs to.

public Boolean ro Indicates whether the template is from the Skytap public library.

publish_sets array ro Array of sharing portals in the template.

region string ro Region that the resource is housed in (for example, US-West)

region_backend string ro Region that the resource is housed in (for example, US-West)

sharing_links

string

List of sharing links for the template.

Field Name	Type	Access	Description
created_at	string	ro	The time that the sharing link was created
expiration_date	string	ro	The expiration date of the template sharing link
id	string	ro	the ID of the template sharing link
template_id	string	ro	The ID of the shared template
url	string	ro	The URL for the template sharing link
user_id	string	ro	The ID of the user who created the template sharing link

storage integer ro Amount of storage space consumed by the template (in MB). This is calculated by adding the total storage space consumed by all disks in all of the template’s VMs.

svms integer ro The amount of Metered RAM an environment created from this template will consume when running. For information about how Metered RAM is calculated, see Usage Overview.

svms_by_architecture object ro Lists the amount of x86 and power Metered RAM consumed by VMs in the template (for example, "svms_by_architecture": { "x86": 0, "power": 2} )

tag_list string rw List of tags in the template. Individual tags are separated by commas (for example, template, API, test).
Tags are limited to 255 characters each.
UTF-8 character type.

tags array ro Array of tags attached to the template. To add or remove template tags, see Template tags sub-resource.

user_data

string

A free-form text field that is useful in automation scenarios. For more information, see Accessing the VM Metadata Service.

user_data doesn't appear in the normal representation of a template; it must be called directly via a GET request to
https://cloud.skytap.com/templates/<template-id>/user_data.

vm_count integer ro Number of VMs in the template

vms array ro Array of virtual machines in the template

url URI ro URI reference for template

Templates v2 sub-resources

The template resource contains several sub-resources that must be directly accessed from their own resource URIs. For documentation, see:

Template VMs sub-resource
Template networks sub-resource
Template labels sub-resource
Template sharing portals sub-resource
Template tags sub-resource
Template VM sequencing stages sub-resource

Supported operations on templates

Get template

Request

GET https://cloud.skytap.com/v2/templates/{template-id}.json

Response

Representation of the template resource.

Get list of templates

Request

GET https://cloud.skytap.com/v2/templates?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add query parameters to your request. For example, the following request will return a list of up to 50 templates that belong to a particular project, that are in the US-West region, and that have been created in the last 30 days.

GET https://cloud.skytap.com/v2/templates?query=project_id:12345,region:US-West&created_at=now-30d+to+now&count=50&offset=0

For a full list of query and sort parameters, see the table below:

Parameter Name

Type

Description

scope

string

Filters results by resource ownership. Scope options:

me	Returns all resources owned by the user
company	Returns all resources owned by the user or shared with the user through projects
public	Returns all Skytap-owned public resources (templates and assets only)
all	Returns all resources that the user has access to; for admins, this will include all resources in the account

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

has_container_hosts	Filters results by whether the environment contains container host VMs. Value must be `true` or `false`.
name	Filters results by keyword (e.g., CentOS).
project_id	Filters results to display templates in a particular project (e.g., 12345). To filter by templates that aren’t in a project, use none.
region	Filters results by region. Options: `All+Skytap` (includes environments from all Skytap-backed regions). A single region name (example, `US-Central`).
status	Filters results by template state. Options: busy copying error
user_id	Filters results by template owner (e.g., 67890). Limited to one user_id per request. This option isn’t available if the scope parameter is me or public.

created_at

string

Filters by template creation date. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

last_installed

string

Filters by last date that an environment was created from the template. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

sort

string

Sorts the list of templates either in ascending or descending order. Options:

Sort by date created: created_at or created_at_desc
Sort by date that an environment was last created from the template: last_installed or last_installed_desc
Sort by name: name or name_desc
Sort by region: region or region_desc
Sort by VM count: vm_count or vm_count_desc
Sort by Metered RAM amount: svms or svms_desc
Sort by network count: network_count or network_count_desc
Sort by storage size: storage or storage_desc

label_category_id

integer

Filters results by all values in a label category (example: 12312)

label_value_id

integer

Filters results by label value (example: 77777)

Response

Returns a list of templates owned by user, templates shared with the user via projects, and templates in the public templates library (if the user has access to that library).

When a template list is requested through the API, some fields won’t be returned. To see a full representation of a template, perform a GET request using the template ID (see Describe Template).

Export templates report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/templates/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/templates/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/templates/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/templates/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request:

GET https://cloud.skytap.com/templates/exports/123456.csv

Response

Templates CSV report.

Request

GET https://cloud.skytap.com/v2/templates{id}/sharing_links.json

Response

Representations of the sharing links for this template.

Example:

{
    id: 1,
    expiration_date: "2020/09/10 10:10:00 -0700",
    created_at: "2020/09/09 11:11:00 -0700",
    user_id: 88,
    template_id: 8,
    url: "https://www.cloud.skytap.com/templates/sharing_links/88bb8888-88bb-8b88-b8bb-8b88bbb8bbbb"
},
{
    id: 2,
    expiration_date: "2020/09/12 10:10:00 -0700",
    created_at: "2020/09/11 11:11:00 -0700",
    user_id: 88,
    template_id: 8,
    url: "https://www.cloud.skytap.com/templates/sharing_links/88bb8888-88bb-8b88-b8bb-8b88bbb8bbb8"
}

Request

GET https://cloud.skytap.com/v2/templates/{id}/sharing_links/{id}.json

Response

Representations of the sharing links specified.

Example:

{
    id: 1,
    expiration_date: "2020/09/10 10:10:00 -0700",
    created_at: "2020/09/09 11:11:00 -0700",
    user_id: 88,
    template_id: 8,
    url: "https://www.cloud.skytap.com/templates/sharing_links/88bb8888-88bb-8b88-b8bb-8b88bbb8bbbb"
}

Request

POST https://cloud.skytap.com/v2/templates/{id}/sharing_links

Response

Representations of the new sharing link.

Exceptions:

Error: 400	Tried to create more than five sharing links for a single template.
Not Found: 404	Invalid template.

Request

DELETE https://cloud.skytap.com/v2/templates/{id}/sharing_links/{id}

Response

Status only.

Template VMs v2 resource

The template VM resource represents an image of a single virtual machine inside of a template. Note that:

VMs don’t exist outside of environments or templates.
An environment or template can have multiple VMs.
Each VM is a unique resource. Therefore, a VM in a template will have a different ID than a VM in an environment created from that template.

Template VMs v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}

Template VMs v2 resource model

Template VMs have the same resource model as environment VMs. However, the template VM resource fields are read-only. Select template VM sub-resources can be edited, as documented below:

Template VMs v2 sub-resources

The template VM resource contains several sub-resources that must be directly accessed from their own resource URIs. For documentation, see:

VM credentials sub-resource
VM metadata sub-resource
VM labels sub-resource
VM notes sub-resource
VM network adapters sub-resource
Published services sub-resource

Operations on template VMs

Get VM

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/vms/{vm-id}.json

Response

Representation of selected virtual machine element.

Template networks v2 resource

Networks aren’t top-level elements of the API. Rather, they are elements properly contained within a template. Operations on them are implicitly on the containing template.

Template networks v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}/networks/{network-id}

Template networks v2 resource model

Template networks have the same resource model as environment networks. However, the template network resource fields are read-only.

Operations on v2 template networks

Get template network

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/networks/{network-id}.json

Response

Representation of the network

Template labels v2 resource

The template resource contains a labels sub-resource that must be directly accessed from its own URI.

Template labels v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}/labels

Template labels v2 resource model

Field Name	Type	Access	Description
id	integer	ro	Label identifier.
value	string	wo on creation, then ro	Name of the label. Max. 255 characters.
label_category	string	wo on creation, then ro	Name of the label category that the label belongs to.
label_category_id	integer	ro	ID of the label category that the label belongs to.
label_category_single_value	Boolean	ro	If `true`, the label belongs to a single value label category.

Operations on template labels

Get template labels

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/labels.json

Optional pagination parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

If count and offset aren’t defined, the API will return 100 results. Example request:

GET https://cloud.skytap.com/v2/templates/{template-id}/labels.json?count=20&offset=0

Response

Representation of the template labels

Sample response

[
    {
        "id": "111",
        "value": "ValueCorp",
        "label_category": "Customer",
        "label_category_id": "123456",
        "label_category_single_value": false
    },
    {
        "id": "333",
        "value": "Update home page",
        "label_category": "Feature",
        "label_category_id": "123457",
        "label_category_single_value": false
    }
]

Add labels to template

Request

PUT https://cloud.skytap.com/v2/templates/{template-id}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Each label must contain:

label_category	the name of an existing label category
value	the label value

Sample request to add two new labels to a template

PUT https://cloud.skytap.com/v2/templates/{template-id}/labels.json

[
    {
        "label_category": "Feature",
        "value": "BlackHat 2016 Demo"
    },
    {
        "label_category": "Team",
        "value": "Security"
    }
]

Notes

A template can have up to 30 labels.
Each label category can contain up to 2,000 label values.
If the label category is single_value, you can apply only one label from that category to each template. If the template already contains a label from that category, the new label will replace the old label.
You can't edit existing label values. Instead, detach the label and then attach a new label in the same category.

Response

Updated representation of the template labels sub-resource.

Sample response

[
    {
        "id": "333",
        "value": "Operations",
        "label_category": "Team",
        "label_category_id": "123452",
        "label_category_single_value": false
    }
]

Add labels to multiple templates

Request

PUT https://cloud.skytap.com/v2/templates/{template-id-1},{template-id-2}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Required parameters

An array or of one more label objects. Each label must contain:

label_category	the name of an existing label category
value	the label value

Response

Updated list of labels attached to each template.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        },
        {
            "id": "12345677",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        }
    ]
}

Edit template label

Template labels can’t be edited. Instead, delete the label and add a new one.

Remove template label

Request

DELETE https://cloud.skytap.com/v2/templates/{template-id}/labels/{label-id}.json

The label won’t be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Template sharing portals are read-only representations of sharing portals that were saved with a template. A template can have zero, one, or many sharing portals.

https://cloud.skytap.com/v2/templates/{template-id}/publish_sets/{publish-set-id}

Throughout the Skytap API, sharing portals are referred to as ‘publish_sets.’ This legacy term has been maintained in the API for backward-compatibility.

Template publish sets v2 resource model

Template sharing portals have the same resource model as environment sharing portals. However, the template sharing portal resource fields are read-only.

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/publish_sets/{publish-set-id}.json

Response

The reference model in the body of the response.

All fields will be returned, even if they have no contents. Note that the password will be returned as an empty element if not configured or as the obfuscated value ********** if it’s set.

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/publish_sets.json

Response

Representation of sharing portals.

Template tags v2 resource

The templates resource contains a tags sub-resource that must be directly accessed from its own URI.

Template tags v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}/tags.json

Template tags v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
id	integer	ro	ID of the tag.
value	string	ro	Tag value. Max. 255 characters. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID. Tag values aren’t case-sensitive (for example, “test”, “Test”, and “TEST” will share the same ID).

Operations on v2 template tags

Get a list of tags attached to the template

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/tags.json

Response

A representation of tags attached to the template.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    }
]

Add tags to the template

Request

PUT https://cloud.skytap.com/v2/templates/{template-id}/tags.json

[
    {
        "value": "Class 101"
    },
    {
        "value": "In progress"
    }
]

Required parameters

An array containing one or more value definitions.

Response

Updated list of tags attached to the template. Each value will be assigned a tag ID. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    },
    {
        "id": 1237,
        "value": "In progress"
    }
]

Add tags to multiple templates

Request

PUT https://cloud.skytap.com/v2/templates/{template-id-1},{template-id-2}/tags.json

[
    {
        "value": "Class 101"
    }
]

Required parameters

An array of objects comprising one or more value definitions.

Response

Updated list of tags attached to each template.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        },
        {
            "id": "12345677",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        }
    ]
}

Remove a tag from a template

Request

DELETE https://cloud.skytap.com/v2/templates/{template-id}/tags/{tag-id}.json

This won’t delete the tag from your customer account; it will simply detach the tag from its association with this template.

Response

Updated list of tags attached to the template.

Sample response

[
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    },
    {
        "id": 1237,
        "value": "In progress"
    }
]

Template VM sequencing stages v2 resource

Stages aren’t top-level elements of the API. Rather, they are elements contained within a template.

Template VM sequencing stages v2 reference URI

https://cloud.skytap.com/v2/templates/{template-id}/stages

Template VM sequencing stages v2 resource model

Template VM sequencing stages have the same resource model as environment VM sequencing stages. However, the template VM sequencing stage resource fields are read-only.

Operations on v2 template VM sequencing stages

Get the VM sequence description

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/stages.json

Response

A list of the VM sequencing stages.

Note that the excluded_vms_ids array won’t be displayed. You can view the contents of this array by making a request to
GET https://cloud.skytap.com/v2/templates/<templates-id>/stages/excluded_vms.json

View a stage within the VM sequence

Request

GET https://cloud.skytap.com/v2/templates/{template-id}/stages/{stage_index}.json

Response

Returns the specified stage.

Returns an error if stage_index is less than 0 or greater than 3.

Account details v2 resource

The account details resource provides information about your user account from the My Account page in Skytap.

Account details v2 reference URI

https://cloud.skytap.com/v2/account

Account details v2 reference URI, including email preferences

https://cloud.skytap.com/v2/account?email_preferences=true

Account details v2 resource model

The element name is account and the following fields are defined:

Field Name	Type	Access	Description
account_name	string	ro	The name of your Skytap customer account.
account_role	string	ro	Your user role. This determines your level of access across the Skytap account. One of restricted_user, standard_user, user_manager, or admin.
country_of_residence	string	rw	The ISO 3166-1 alpha-3 code for your country of residence. Note that PRK, CUB, SYR, IRN, and SDN aren’t accepted values.
country_of_residence_name	string	ro	The full name of your country of residence. For example: United States of America.
default_region	string	rw	The default region for your VM imports, asset uploads, new VPNs, and new public IP addresses.
department_id	integer	ro	The identifier of the department you belong to.
department_name	string	ro	The name of the department you belong to.
email	string	rw	Email associated with your user account; this is the email address that Skytap sends notifications to.
email_preferences	string	rw	Array of email preferences. Currently supported parameters are research and marketing.
email_validated	Boolean	ro	Indicates whether you’ve verified your email address.
first_name	string	ro	Your first name.
last_name	string	ro	Your last name.
login_name	string	ro	Your Skytap user name.
primary_contact	object	ro	Provides information about your account administrator. Includes the administrator’s first_name, last_name, login_name, and email.
title	string	ro	Optional title associated with the user; doesn’t affect Skytap permissions.
time_zone	string	rw	The time zone associated with your Skytap activities (for example, project creation time).
wants_email	Boolean	ro	`null` – This is a legacy field that was deprecated in May 2018.

Operations on v2 account details

Get my account details

Request

GET https://cloud.skytap.com/v2/account.json

Response

A representation of your account information.

Get a list of groups I am a member of

Request

GET https://cloud.skytap.com/v2/account/groups?count=20&offset=0

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Response

Representation of the groups you’re a member of.

Sample response

[
  {
    "id": 123,
    "name": "QA",
    "description": "Members of the QA team",
    "notification_count": 0,
    "project_count": 0,
    "user_count": 10
  },
  {
    "id": 111,
    "name": "Project Managers",
    "description": "Project managers across divisions",
    "notification_count": 0,
    "project_count": 15,
    "user_count": 6
  }
]

Get all of my API tokens

Request

GET https://cloud.skytap.com/v2/account/api_tokens.json

With the following request headers:

Accept-Type: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Replace QWxhZGRpbjpvcGVuIHNlc2FtZQ== with the base64 encoding of your user name and password (username:password).

Response

Representation of your API tokens.

Sample response

{
  "id": "8888",
  "api_token": "5678aaaa5678aaaa",
  "created_at": "2020/11/11 08:08:08 -0800",
  "expiration_date": "2021/02/09 08:08:08 -0800"
},
{
  "id": "8989",
  "api_token": "1977abba1977abba",
  "created_at": "2020/11/11 11:11:11 -0800",
  "expiration_date": "2021/02/09 11:11:11 -0800"
}

Add a new API token

Request

POST https://cloud.skytap.com/v2/account/api_tokens.json

With the following request headers:

Accept-Type: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Replace QWxhZGRpbjpvcGVuIHNlc2FtZQ== with the base64 encoding of your user name and password (username:password).

Response

A successful request returns a representation of the API token information.

Sample response

{
  "id": "8888",
  "api_token": "5678aaaa5678aaaa",
  "created_at": "2020/11/11 11:11:11 -0800",
  "expiration_date": "2021/02/09 11:11:11 -0800"
}

Delete an API token

Request

DELETE https://cloud.skytap.com/v2/account/api_tokens/{id}.json

With the following request headers:

Accept-Type: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Replace QWxhZGRpbjpvcGVuIHNlc2FtZQ== with the base64 encoding of your user name and password (username:password).

Response

No response body.

Reset my stored browser activations

Request

POST https://cloud.skytap.com/v2/account/reset_browser_activation.json

Response

No response body.

Change my password

Request

Sample request

PUT https://cloud.skytap.com/v2/account

{
  "old_password": "password123",
  "new_password": "$47v6xm^cV!u",
  "confirm_password": "$47v6xm^cV!u"
}

Required parameters

old_password	String value containing the existing password.
new_password	String value containing the new password. The password must adhere to the length and history rules set in the account Password Policy. The password can't match the user sign-in name. The password must contain at least one non-alphabetical character.
confirm_password	String value containing the new password. This must match the string value in new_password.

Response

A successful request returns a representation of the account information.

A 400 error response is returned if:

The old_password is incorrect.
The new_password and confirm_password fields don’t match.
The new_password matches the sign-in name, doesn’t contain a non-alphabetical character, or doesn’t adhere to the account password policy requirements.

Edit my account details

Request

Sample request

PUT https://cloud.skytap.com/v2/account

{
  "email": "newemail@email.com"
}

From this resource, you can edit only the account email, password (see Change my password above), time zone, email preferences, and default region. All other account information must be edited by an administrator using the Users resource.

Response

Updated representation of your account information.

Account limits v2 resource

An account limit manages the consumption of max concurrent Metered RAM, Metered RAM hours, storage, concurrent VMs, public IPs, and networks across all of the users in your account.

Notes

You must be a Skytap administrator to access the Account limits resource.
All users (including non-administrator users) can view limits for their account. See List all customer limits.

Account limits v2 reference URI

https://cloud.skytap.com/v2/company/quotas

When you use the above URI, Skytap automaticallys detect your customer account based on your user information.

Account limits v2 resource model

The element name is quotas and the following fields are defined:

Field Name Type Access Description

id string ro The type of resource the quota is measuring. One of concurrent_svms, concurrent_vms, storage, svm_hours, public_ips, or networks.

limit

integer

(various, see description)

Current resource limit for the account.

Field Name	Type	Access	Description
concurrent_svms	integer	rw	The maximum amount of Metered RAM that may be used at the same time; applies to Metered RAM consumed by x86 VMs.
concurrent_svms_power	integer	rw	The maximum amount of Metered RAM that may be used at the same time; applies to Metered RAM units consumed by Power VMs. Available only if your account is enabled for Power VMs.
concurrent_vms	integer	rw	Number of VMs that can be used at the same time.
storage	integer	rw	Maximum storage limit for the account, units specified in MB.
svm_hours	integer	rw	Maximum number of hours of cumulative Metered RAM usage for x86 VMs.
svm_hours_power	integer	ro	Maximum number of hours of cumulative Metered RAM usage for Power VMs.Returned only if your account is enabled for Power VMs.
public_ips	integer	ro	Maximum number of public IP addresses.
networks	integer	ro	Maximum number of networks.

max_limit integer ro Max settable limit for the account; this is highest value that can be set for the quota. If max_limit is null, then the max limit is equal to the current limit.

region string ro The name of the region that the limit applies to. If limit applies to the whole account, this parameter contains global.

subscription integer ro The amount of resources you have budgeted for monthly usage; if you set the limit above the reserved capacity, you can allow additional usage at an additional cost.

units string ro Specifies the unit of measure (for example, MB or integer).

usage integer ro The amount of resource in use or consumed (depending on the resource).

Operations on v2 account limits

List all customer limits

Request

GET https://cloud.skytap.com/v2/company/quotas.json

Response

A representation of all customer limits will be displayed.

If you have regional limits enabled in your account, each customer limit will be grouped into one of several arrays. For example, all global quotas will be included in a global array, while all limits for US-West will be grouped in a US-West array. For illustration, see the sample responses below.

Sample response if account doesn't have regional limits

[
  {
    "id": "concurrent_vms",
    "units": "integer",
    "limit": 10,
    "region": "global",
    "usage": 5,
    "subscription": 10,
    "max_limit": 10
  },
  {
    "id": "concurrent_svms",
    "units": "integer",
    "limit": 20,
    "region": "global",
    "usage": 10,
    "subscription": 20,
    "max_limit": 20
  },
  {
    "id": "svm_hours",
    "units": "hours",
    "limit": 100,
    "region": "global",
    "usage": 0,
    "subscription": 100,
    "max_limit": 100
  },
  {
    "id": "storage",
    "units": "MB",
    "limit": 102400,
    "region": "global",
    "usage": 20480,
    "subscription": 102400,
    "max_limit": 102400
  },
  {
    "id": "networks",
    "units": "integer",
    "limit": 20,
    "region": "global",
    "usage": 4
  },
  {
    "id": "public_ips",
    "units": "integer",
    "limit": 6,
    "region": "global",
    "usage": 2
  }
]

Sample response if account has regional limits

{
  "global": [
    {
      "id": "concurrent_vms",
      "units": "integer",
      "limit": 10,
      "region": "global",
      "usage": 5,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "svm_hours",
      "units": "hours",
      "limit": 100,
      "region": "global",
      "usage": 50,
      "subscription": 100,
      "max_limit": 100
    }
  ],
  "US-West": [
    {
      "id": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-West",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "storage",
      "units": "MB",
      "limit": 51200,
      "region": "US-West",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "networks",
      "units": "integer",
      "limit": 10,
      "region": "US-West",
      "usage": 2
    },
    {
      "id": "public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-West",
      "usage": 1
    }
  ],
  "US-East-2": [
    {
      "id": "concurrent_svms",
      "units": "integer",
      "limit": 10,
      "region": "US-East-2",
      "usage": 0,
      "subscription": 10,
      "max_limit": 10
    },
    {
      "id": "storage",
      "units": "MB",
      "limit": 51200,
      "region": "US-East-2",
      "usage": 10240,
      "subscription": 51200,
      "max_limit": 51200
    },
    {
      "id": "networks",
      "units": "integer",
      "limit": 10,
      "region": "US-East-2",
      "usage": 2
    },
    {
      "id": "public_ips",
      "units": "integer",
      "limit": 3,
      "region": "US-East-2",
      "usage": 1
    }
  ]
}

View customer limits in a region

Request

GET https://cloud.skytap.com/v2/company/quotas.json?region=US-West

Response

Representation of the region’s limits.

Sample response

[
  {
    "id": "concurrent_svms",
    "units": "integer",
    "limit": 10,
    "region": "US-West",
    "usage": 0,
    "subscription": 10,
    "max_limit": 10
  },
  {
    "id": "storage",
    "units": "MB",
    "limt": 51200,
    "region": "US-West",
    "usage": 10240,
    "subscription": 51200,
    "max_limit": 51200
  },
  {
    "id": "networks",
    "units": "integer",
    "limit": 10,
    "region": "US-West",
    "usage": 2
  },
  {
    "id": "public_ips",
    "units": "integer",
    "limit": 3,
    "region": "US-West",
    "usage": 1
  }
]

Edit a customer limit

Request

Select customer limits can be edited through the API. Each list modification must be a separate request.

If you would like to edit a limit that is read only or where the max settable limit is null, contact your Skytap representative.

PUT https://cloud.skytap.com/v2/company/quotas/{quota-id}.json

{
  "limit": 150
}

Required parameters

limit	The new limit (integer).
region	If you’re editing a regional limit, you must include a region parameter. If you’re editing a global limit, no region is required.

Response

The updated limit.

Account settings v2 resource

The account settings resource provides global account configuration settings.

You must be a Skytap administrator to access the Account settings resource.

Settings v2 reference URI

https://cloud.skytap.com/v2/admin/settings.json

When you use the above URI, Skytap automaticallys detect your customer account based on your user information.

Settings v2 resource model

The following fields are defined:

Field Name Type Access Description

billing_contact_email string rw Email address to which billing notifications may be sent. Not validated at submit time.

default_publish_set_support_url

string

http://example.com
https://example.com
mailto:support@example.com

default_usage_control_action string rw Automatic power option. Allowed values are suspend and shutdown.

ibmi_vms_enabled Boolean rw Whether IBM i VMs are enabled.

primary_contact

object

Array of details for the Primary Administrator defined by primary_contact_id.

Field Name	Type	Access	Description
id	string	ro	Identifier.
url	string	ro	URI reference for the user.
login_name	string	ro	Sign-in name for the user.
first_name	string	ro	First name string used for display in the UI. Not validated for uniqueness.
last_name	string	ro	Last name string used for display in the UI. Not validated for uniqueness.
email	string	ro	Email address to which notifications may be sent. Not validated at submit time.
role	string	ro	Defines the user's access to features and settings. One of: restricted_user standard_user user_manager admin For more information on user roles, see User Roles and Access Permissions.
deleted	Boolean	ro	Indicates whether the user account has been deleted.

primary_contact_id string rw Identifier.

security_contact_email string rw Email address to which security notifications may be sent. Not validated at submit time.

usage_control_by_default Boolean rw Whether default auto-shutdown options are enabled.

usage_control_idle_timeout integer rw Automatic power option. Number of seconds before default_usage_control_action is invoked.

webhooks

array

Array of settings for webhooks.

Field Name	Type	Access	Description
category	string	ro	Type of webhook. Allowed values are auditing and usage.
certificate	string	ro	Public key of the TLS certificate.
created_at	timestamp	ro	Date and time the webhook was created.
enabled	Boolean	ro	If true, the webhook is on.
id	string	ro	Webhook identifier.
updated_at	timestamp	ro	Date and time the webhook was last edited.
url	string	ro	URL of the webhook data endpoint.

To interact with the webhooks API resources, see Webhooks v2 resource

Operations on v2 settings

List account settings

Request

GET https://cloud.skytap.com/v2/admin/settings.json

Response

A representation of all account settings will be displayed.

Sample response

{
    "usage_control_by_default": true,
    "usage_control_idle_timeout": 300,
    "default_usage_control_action": "shutdown",
    "primary_contact_id": 1000,
    "primary_contact": {
        "id": 1000,
        "url": "https://cloud.skytap.com/v2/users/1000",
        "login_name": "1000_user",
        "first_name": "One",
        "last_name": "Thousand",
        "email": "1thousand@skytap.com",
        "role": "admin",
        "deleted": false
    },
    "security_contact_email": "security@company.com",
    "billing_contact_email": "billing@company.com",
    "default_publish_set_support_url": "www.plshlp.com",
    "shared_drives": [
        {
            "region": "West",
            "address": "ftp-west.skytap.com",
            "username": "10x100",
            "password": "10x10x10",
            "drive_size": 50,
            "units": "GB"
        }, {
            "region": "East",
            "address": "ftp-east.skytap.com",
            "username": "10x100",
            "password": "10x10x10",
            "drive_size": 11,
            "units": "GB"
        }
    ],
    "webhooks": [
        {
            "id": "1",
            "url": "https://some_url.com",
            "certificate": "",
            "category": "auditing",
            "enabled": true
        }, {
            "id": "2",
            "url": "https://some_url_2.com",
            "certificate": "",
            "category": "usage",
            "enabled": true
        }
    ]
}

Update auto-shutdown action

Request

Default auto-shutdown options can be edited through the API

PUT https://cloud.skytap.com/v2/admin/settings

Required and optional parameters

Required parameters

usage_control_by_default If true default auto-shutdown options are enabled.

Optional parameters

usage_control_idle_timeout	Number of seconds before default_usage_control_action is invoked.
default_usage_control_action	URL of the webhook data endpoint.

Response

{
    "usage_control_by_default": true,
    "usage_control_idle_timeout": 300,
    "default_usage_control_action": "suspend",
}

Edit account contacts

Request

PUT https://cloud.skytap.com/v2/admin/settings

Required and optional parameters

Required parameters

primary_contact_id

User ID for the primary administrator.

Optional parameters

security_contact_email	Email address for security contact.
billing_contact_email	Email address for billing contact.

Response

{
    "primary_contact_id": 123
    "security_contact_email": "new_security@company.com",
    "billing_contact_email": "new_billing@company.com"
}

Request

PUT https://cloud.skytap.com/v2/admin/settings

Required parameters

default_publish_set_support_url

Default URL or email address of custom Support/Help link displayed in new sharing portals.

Response

{
    "default_publish_set_support_url": "www.ineedhelp.com"
}

Assets v2 resource

Files uploaded to your account are called assets. Assets can be downloaded onto VMs, as well as shared with other users via projects.

Assets can’t be created or modified. You can view assets and reference them.

Assets v2 reference URI

https://cloud.skytap.com/v2/assets/{asset-id}

Assets v2 resource model

The element name is assets and the following fields are defined:

Field Name	Type	Access	Description
can_delete	Boolean	ro	The user’s permissions relative to this asset, controlled by the user’s role, the user’s project permissions (if the asset is in a project), and whether or not the asset is a public asset (public assets can’t be modified).
can_modify	Boolean	ro	The user’s permissions relative to this asset, controlled by the user’s role, the user’s project permissions (if the asset is in a project), and whether or not the asset is a public asset (public assets can’t be modified).
can_share	Boolean	ro	The user’s permissions relative to this asset, controlled by the user’s role, the user’s project permissions (if the asset is in a project), and whether or not the asset is a public asset (public assets can’t be modified).
can_tag	Boolean	ro	The user’s permissions relative to this asset, controlled by the user’s role, the user’s project permissions (if the asset is in a project), and whether or not the asset is a public asset (public assets can’t be modified).
created_at	timestamp	ro	Date and time that the asset was created.
id	string	ro	Identifier.
name	string	ro	Human-friendly name. Limited to 255 characters. UTF-8 character type.
owner	string	wo	Used to change the asset owner (see Change asset owner).
owner_id	string	ro	Asset owner’s ID number. This field doesn’t exist for Skytap-owned public assets.
owner_name	string	ro	Asset owner’s first and last name, as displayed in the UI. This field doesn’t exist for Skytap-owned public assets.
owner_url	URI	ro	Asset owner’s user-ref . This field doesn’t exist for Skytap-owned public assets.
public	Boolean	ro	Indicates whether the asset is in the Skytap public library.
region	string	ro	Region where the asset is housed (for example, us-west).
size	integer	ro	Size (in bytes).
tags	array	ro	Array of tags attached to the asset. To add or remove asset tags, see Asset tags sub-resource.
url	URI	ro	URI reference for the asset.

Assets v2 sub-resources

The assets resource contains sub-resources that must be directly accessed from their resource URIs. For documentation, see:

Asset tags sub-resource
Asset labels sub-resource

Operations on assets

Get asset description

Request

GET https://cloud.skytap.com/v2/assets/{asset-id}

Response

An asset element.

List assets

Request

GET https://cloud.skytap.com/v2/assets?count=10&offset=0

Required and optional parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return a list of 50 assets that belong to a particular project, that are in the US-West region, and that have been created in the last 30 days, use the following request:

GET https://cloud.skytap.com/v2/assets?query=project_id:12345,region=US-West&created_at=now-30d+to+now&count=50&offset=0

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

created_at

string

Filters by asset creation date. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

query

string

extension	Filters results by file extension (for example, iso, gz, jpg).
name	Filters results by keyword (e.g., iso).
region	Filters results by region: APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-London-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West
user_id	Filters results by asset owner (for example, `67890`). Limited to one user_id per request. This option isn’t available if the scope parameter is me or public.

scope

string

Filters results by asset ownership. Scope options:

all	Returns all assets that the user has access to. For admins, this includes all assets in the account.
company	Returns all assets owned by the user or shared with the user through projects.
me	Returns all assets owned by the user.
public	Returns all Skytap-owned public assets.

Response

Returns a list of assets. Data within the assets isn’t returned.

Change asset owner

Request

PUT https://cloud.skytap.com/v2/assets/{asset-id}

{
    "owner": "1234"
}

Required parameters

owner

ID of the user you want to be the new asset owner.

If the user is a restricted user, you must also include project_id with the ID of a project that the user has editor or manager privileges in.

Response

An updated representation of the asset.

The operation will fail if the new owner doesn’t have the correct permissions or enough storage to own the asset.

Delete assets

Request

DELETE https://cloud.skytap.com/v2/assets/destroy_multiple.json

{
    "multiselect": [
        "123456",
        "123457",
        "123458",
        "123459"
    ]
}

Parameters

multiselect

Array of IDs for the assets that you want to delete.

Deleted assets can’t be recovered.

Response

Status only

Export an assets report (.CSV)

Request

Step 1: Create the report

POST https://cloud.skytap.com/v2/assets/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Response

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/assets/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Request

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report URL.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/assets/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/assets/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true,, access the report at the report URL listed in the response body. Append .csv to the report URL. Sample request:

GET https://cloud.skytap.com/assets/exports/123456.csv

Response

The report is downloaded.

Asset tags v2 resource

The assets resource contains a tags sub-resource that must be directly accessed from its own URI.

Asset tags v2 reference URI

https://cloud.skytap.com/v2/assets/{asset-id}/tags.json

Asset tags v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
id	integer	ro	ID of the tag.
value	string	ro	Tag value. Max. 255 characters. If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID. Tag values aren’t case-sensitive (for example, “test”, “Test”, and “TEST” will share the same ID).

If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID.

Operations on v2 asset tags

Get a list of tags attached to the asset

Request

GET https://cloud.skytap.com/v2/assets/{asset-id}/tags.json

Response

A representation of tags attached to the asset.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    }
]

Add tags to the asset

Request

PUT https://cloud.skytap.com/v2/assets/{asset-id}/tags.json

[
    {
        "value": "Class 101"
    }
]

Required parameters

An array of objects comprising one or more value definitions.

Response

Updated list of tags attached to the asset. Each value will be assigned a tag ID. Tags that have the same value (across all environments, templates, and assets), will share the same ID.

Sample response

[
    {
        "id": 1233,
        "value": "archived"
    },
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    }
]

Add tags to multiple assets

Request

PUT https://cloud.skytap.com/v2/assets/{asset-id-1},{asset-id-2}/tags.json

[
    {
        "value": "Class 101"
    }
]

Required parameters

An array of objects comprising one or more value definitions.

Response

Updated list of tags attached to each asset.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        },
        {
            "id": "12345677",
            "tags": [
                {
                    "id": "1236",
                    "value": "Class 101"
                }

            ]
        }
    ]
}

Remove a tag from the asset

Request

DELETE https://cloud.skytap.com/v2/assets/{asset-id}/tags/{tag-id}.json

This won’t delete the tag from your customer account; it will simply detach the tag from its association with this asset.

Response

Updated list of tags attached to the asset.

Sample response

[
    {
        "id": 1234,
        "value": "QA complete"
    },
    {
        "id": 1236,
        "value": "Class 101"
    },
    {
        "id": 1237,
        "value": "In progress"
    }
]

Asset labels v2 resource

The asset resource contains a labels sub-resource that must be directly accessed from its own URI.

Asset labels v2 reference URI

https://cloud.skytap.com/v2/assets/{asset-id}/labels

Asset labels v2 resource model

Field Name	Type	Access	Description
id	integer	ro	Label identifier.
label_category	string	wo on creation, then ro	Name of the label category that the label belongs to.
label_category_id	integer	ro	ID of the label category that the label belongs to.
label_category_single_value	Boolean	ro	If `true`, the label belongs to a single value label category.
value	string	wo on creation, then ro	Name of the label. Max. 255 characters.

Operations on asset labels

Get asset labels

Request

GET https://cloud.skytap.com/v2/assets/{asset-id}/labels.json

Optional pagination parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

If count and offset aren’t defined, the API will return 100 results.

Example request:

GET https://cloud.skytap.com/v2/assets/{asset-id}/labels.json?count=20&offset=0

Response

Representation of the asset labels

Sample response

[
  {
    "id": "111",
    "value": "ValueCorp",
    "label_category": "Customer",
    "label_category_id": "123456",
    "label_category_single_value": false
  },
  {
    "id": "333",
    "value": "Update home page",
    "label_category": "Feature",
    "label_category_id": "123457",
    "label_category_single_value": false
  }
]

Add labels to asset

Request

PUT https://cloud.skytap.com/v2/assets/{asset-id}/labels.json

[
  {
    "label_category": "Team",
    "value": "Operations"
  }
]

Required parameters

Each label must contain:

label_category	the name of an existing label category.
value	the label value.

Example request to add two labels to an asset

PUT https://cloud.skytap.com/v2/assets/{asset-id}/labels.json

[
  {
    "label_category": "Feature",
    "value": "BlackHat 2016 Demo"
  },
  {
    "label_category": "Team",
    "value": "Security"
  }
]

Notes

An asset can have up to 30 labels.
Each label category can contain up to 1000 label values.
If the label category is single_value, you can only apply one label from that category to each asset. If the asset already contains a label from that category, the new label will replace the old label.
You can't edit existing label values. Instead, detach the label and then attach a new label in the same category.

Response

Updated representation of the asset labels sub-resource.

Sample response

[
  {
    "id": "121",
    "value": "Operations",
    "label_category": "Team",
    "label_category_id": "123452"
  }
]

Add labels to multiple assets

Request

PUT https://cloud.skytap.com/v2/assets/{asset-id-1},{asset-id-2}/labels.json

[
  {
    "label_category": "Team",
    "value": "Operations"
  }
]

Required parameters

An array or of one more label objects. Each label must contain:

label_category	the name of an existing label category.
value	the label value.

Response

Updated list of labels attached to each asset.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
  "results": [
    {
      "id": "1234566",
      "labels": [
        {
          "id": "333",
          "value": "Operations",
          "label_category": "Team",
          "label_category_id": "123452",
          "label_category_single_value": false
        }
      ]
    },
    {
      "id": "12345677",
      "labels": [
        {
          "id": "333",
          "value": "Operations",
          "label_category": "Team",
          "label_category_id": "123452",
          "label_category_single_value": false
        }
      ]
    }
  ]
}

Edit asset label

Asset labels can’t be edited. Instead, delete the label and add a new one.

Remove asset label

Request

DELETE https://cloud.skytap.com/v2/assets/{asset-id}/labels/{label-id}.json

The label won’t be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Containers v2 resource

Containers v2 reference URI

https://cloud.skytap.com/v2/containers/{container-id}

Containers v2 resource model

The element name is containers and the following fields are defined:

Field Name	Type	Access	Description
can_change_state	Boolean	ro
can_delete	Boolean	ro	The current user’s permissions relative to this container.
cid	string	ro	ID assigned to the container by Docker.
command	string	ro	Displays any Docker commands (for example, “nginx -g daemon off;”).
configuration_id	integer	ro	Environment ID for the VM container host and container.
container_links	array	ro	Links to other containers.
created_at	timestamp	ro	Date and time the VM Agent recognized the container.
entry_point	string	ro	ENTRYPOINT command executed when the container starts.
error	string	ro	Description of any errors.
finished_at	timestamp	ro	Date and time the container was last stopped or exited.
id	integer	ro	ID assigned to the container by Skytap. (Use `id` for API operations on containers.)
image	string	ro	Docker image the container is based on.
ip_address	string	ro	IP address of the container.
labels	dictionary	ro	Docker metadata labels attached to this container. Represented as key/value pairs.
last_run	timestamp	ro	Date and time the container was last run or `null` if the container hasn’t yet been run.
mounts	array	ro	Filesystem mounts for the container.
name	string	rw	Container name. Restricted to uppercase letters, lowercase letters, numbers, underscores (_), and periods.
ports	array	ro	Port bindings for the container.
privileged	Boolean	ro	If true, the container has super privileges on the VM container host. `null` if the container hasn’t yet been run.
spawned_at	timestamp	ro	Date and time the container was created on the VM.
status	string	ro	Current status of the container. One of: busy, created, running, restarting, paused, exited, dead, or error.
vm_id	integer	ro	ID of the VM container host.
vm_name	string	ro (from this endpoint)	Name of the VM container host.
vm_runstate	string	ro (from this endpoint)	Runstate of the VM container host.

Supported operations on containers

Get list of containers in an environment

See the Environment containers resource.

Get container details

Request

GET https://cloud.skytap.com/v2/containers/{id}.json

Response

The API will return a detailed, read-only representation of the container.

Sample response body

{
    "id": 1122,
    "cid": "123456789abcdefghijk123456789abcdefghijk123456789abcdefghijk",
    "name": "nginxtest1",
    "image": "nginx:latest",
    "created_at": "2016/06/16 11:58:50 -0700",
    "last_run": "2016/06/16 11:58:51 -0700",
    "can_delete": true,
    "can_change_state": true,
    "status": "running",
    "privileged": false,
    "vm_id": 111000,
    "vm_name": "Docker 1.10.3 - Ubuntu Desktop 14.04 - 64-bit",
    "vm_runstate": "running",
    "configuration_id": "1234567",
    "spawned_at": "2016/06/20 10:18:18 -0700",
    "finished_at": null,,
    "command": null,
    "entry_point": null,
    "labels": {},
    "ip_address": "172.17.0.2",
    "ports": [],
    "container_links": null,
    "mounts": []
}

Start, stop, pause, unpause or kill container

Request

PUT https://cloud.skytap.com/v2/containers/{id}

{
    "runstate": "start"
}

runstate must be one of start, stop, pause, unpause, or kill.

Response

HTTP status code	Explanation
200	Success.
400	Invalid runstate or runstate is missing in request payload.
404	Container doesn’t exist.
409	VM agent isn’t responding, container doesn’t exist (or was removed since the last API request), or the runstate change is invalid (attempting to pause a stopped container). See the returned error message for more detail.

Sample response body

{
    "id": 1122,
    "cid": "123456789abcdefghijk123456789abcdefghijk123456789abcdefghijk",
    "name": "nginxtest1",
    "image": "nginx:latest",
    "created_at": "2016/06/16 11:58:50 -0700",
    "last_run": "2016/06/16 11:58:51 -0700",
    "can_delete": true,
    "can_change_state": true,
    "status": "running",
    "privileged": false,
    "vm_id": 111000,
    "vm_name": "Docker 1.10.3 - Ubuntu Desktop 14.04 - 64-bit",
    "vm_runstate": "running",
    "configuration_id": "1234567",
    "spawned_at": "2016/06/20 10:18:18 -0700",
    "finished_at": null,
    "command": null,
    "entry_point": null,
    "labels": {},
    "ip_address": "172.17.0.2",
    "ports": [],
    "container_links": null,
    "mounts": []
}

Rename container

Request

PUT https://cloud.skytap.com/v2/containers/{container-id}

{
    "name": "new_container_name"
}

name must not duplicate the current container name or the name of other containers in the environment. name is restricted to uppercase letters, lowercase letters, numbers, underscores (_), and periods.

Response

Updated representation of the container.

Sample response body

{
    "id": 1122,
    "cid": "123456789abcdefghijk123456789abcdefghijk123456789abcdefghijk",
    "name": "new_container_name",
    "image": "nginx:latest",
    "created_at": "2016/06/16 11:58:50 -0700",
    "last_run": "2016/06/16 11:58:51 -0700",
    "can_delete": true,
    "can_change_state": true,
    "status": "running",
    "privileged": false,
    "vm_id": 111000,
    "vm_name": "Docker 1.10.3 - Ubuntu Desktop 14.04 - 64-bit",
    "vm_runstate": "running",
    "configuration_id": "1234567",
    "spawned_at": "2016/06/20 10:18:18 -0700",
    "finished_at": null,
    "command": null,
    "entry_point": null,
    "labels": {},
    "ip_address": "172.17.0.2",
    "ports": [],
    "container_links": null,
    "mounts": []
}

View container log

Request

GET https://cloud.skytap.com/v2/containers/{container-id}/logs.json?line_count=25

line_count must be an integer between 1 and 500, inclusive.

Response

Representation of the container, with a populated logs field. If the container log is empty, the logs field contains an empty string.

{
    "id": 12345,
    "image": "couchdb:latest",
    ...
    "logs": "WARNING: CouchDB is running in Admin Party mode.\r\n
    This will allow anyone with access to the\r\n
    CouchDB port to access your database. In\r\n
    Docker's default configuration, this is\r\n
    effectively any other container on the same\r\n
    system.\r\n
    Use \"-e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password\"\r\n
    to set it in \"docker run\".\r\n
    ****************************************************\r\n
    Apache CouchDB 1.6.1 (LogLevel=info) is starting.\r\n
    Apache CouchDB has started. Time to relax.\r\n
    [info] [<0.32.0>] Apache CouchDB has started on http://0.0.0.0:5984/\r\n
    ****************************************************\r\n
    WARNING: CouchDB is running in Admin Party mode.\r\n
    This will allow anyone with access to the\r\n
    CouchDB port to access your database. In\r\n
    Docker's default configuration, this is\r\n
    effectively any other container on the same\r\n
    system.\r\n
    Use \"-e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password\"\r\n
    to set it in \"docker run\".\r\n
    ****************************************************\r\n
    Apache CouchDB 1.6.1 (LogLevel=info) is starting.\r\n
    Apache CouchDB has started. Time to relax.\r\n
    [info] [<0.32.0>] Apache CouchDB has started on http://0.0.0.0:5984/\r\n"}

View container inspection report

Request

GET https://cloud.skytap.com/v2/containers/{container-id}/inspect.json

Response

Representation of the container, with a populated inspect_report field. The inspection report is returned as a string with unparsed JSON.

Sample response

{
    "id": 12345,
    "image": "index.docker.io/nginx:latest",
    ...
    "inspect_report": "{\"Id\":\"fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02\",\"Created\":\"2016-12-22T19:30:42.953339364Z\",\"Path\":\"nginx\",\"Args\":[\"-g\",\"daemon off;\"],\"State\":{\"Status\":\"running\",\"Running\":true,\"Paused\":false,\"Restarting\":false,\"OOMKilled\":false,\"Dead\":false,\"Pid\":6670,\"ExitCode\":0,\"Error\":\"\",\"StartedAt\":\"2016-12-22T19:30:58.932151653Z\",\"FinishedAt\":\"0001-01-01T00:00:00Z\"},\"Image\":\"sha256:19146d5729dc303af0b89be53ddfe8ece1920d9467e2b5a903d846f2fe0e9b5d\",\"ResolvConfPath\":\"/var/lib/docker/containers/fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02/resolv.conf\",\"HostnamePath\":\"/var/lib/docker/containers/fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02/hostname\",\"HostsPath\":\"/var/lib/docker/containers/fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02/hosts\",\"LogPath\":\"/var/lib/docker/containers/fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02/fb2b5fe87db11660f8e88eb00333c97e2863813b764f116f9558ea59cce2de02-json.log\",\"Name\":\"/nginx-test-ports\",\"RestartCount\":0,\"Driver\":\"aufs\",\"MountLabel\":\"\",\"ProcessLabel\":\"\",\"AppArmorProfile\":\"\",\"ExecIDs\":null,\"HostConfig\":{\"Binds\":[],\"ContainerIDFile\":\"\",\"LogConfig\":{\"Type\":\"json-file\",\"Config\":{}},\"NetworkMode\":\"bridge\",\"PortBindings\":{\"80/tcp\":[{\"HostIp\":\"\",\"HostPort\":\"1102\"}]},\"RestartPolicy\":{\"Name\":\"\",\"MaximumRetryCount\":0},\"AutoRemove\":false,\"VolumeDriver\":\"\",\"VolumesFrom\":null,\"CapAdd\":null,\"CapDrop\":null,\"Dns\":null,\"DnsOptions\":null,\"DnsSearch\":null,\"ExtraHosts\":null,\"GroupAdd\":null,\"IpcMode\":\"\",\"Cgroup\":\"\",\"Links\":null,\"OomScoreAdj\":0,\"PidMode\":\"\",\"Privileged\":false,\"PublishAllPorts\":false,\"ReadonlyRootfs\":false,\"SecurityOpt\":null,\"StorageOpt\":null,\"UTSMode\":\"\",\"UsernsMode\":\"\",\"ShmSize\":67108864,\"ConsoleSize\":[0,0],\"Isolation\":\"\",\"CpuShares\":0,\"Memory\":0,\"CgroupParent\":\"\",\"BlkioWeight\":0,\"BlkioWeightDevice\":null,\"BlkioDeviceReadBps\":null,\"BlkioDeviceWriteBps\":null,\"BlkioDeviceReadIOps\":null,\"BlkioDeviceWriteIOps\":null,\"CpuPeriod\":0,\"CpuQuota\":0,\"CpusetCpus\":\"\",\"CpusetMems\":\"\",\"Devices\":null,\"DiskQuota\":0,\"KernelMemory\":0,\"MemoryReservation\":0,\"MemorySwap\":0,\"MemorySwappiness\":-1,\"OomKillDisable\":false,\"PidsLimit\":0,\"Ulimits\":null,\"CpuCount\":0,\"CpuPercent\":0,\"BlkioIOps\":0,\"BlkioBps\":0,\"SandboxSize\":0},\"GraphDriver\":{\"Name\":\"aufs\",\"Data\":null},\"Mounts\":[],\"Config\":{\"Hostname\":\"fb2b5fe87db1\",\"Domainname\":\"\",\"User\":\"\",\"AttachStdin\":false,\"AttachStdout\":false,\"AttachStderr\":false,\"ExposedPorts\":{\"443/tcp\":{},\"80/tcp\":{}},\"Tty\":false,\"OpenStdin\":false,\"StdinOnce\":false,\"Env\":[\"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\",\"NGINX_VERSION=1.11.7-1~jessie\"],\"Cmd\":[\"nginx\",\"-g\",\"daemon off;\"],\"Image\":\"index.docker.io/nginx:latest\",\"Volumes\":null,\"WorkingDir\":\"\",\"Entrypoint\":null,\"OnBuild\":null,\"Labels\":{}},\"NetworkSettings\":{\"Bridge\":\"\",\"SandboxID\":\"2c1b48c7fccabf7298c5f5eb7a45a2b9ec47a20ce5dffd742887954202d62bba\",\"HairpinMode\":false,\"LinkLocalIPv6Address\":\"\",\"LinkLocalIPv6PrefixLen\":0,\"Ports\":{\"443/tcp\":null,\"80/tcp\":[{\"HostIp\":\"0.0.0.0\",\"HostPort\":\"1102\"}]},\"SandboxKey\":\"/var/run/docker/netns/2c1b48c7fcca\",\"SecondaryIPAddresses\":null,\"SecondaryIPv6Addresses\":null,\"EndpointID\":\"c71980b822fc26b33804d33e1cbc9e32f728fc4f6617542df07242093b72b868\",\"Gateway\":\"172.17.0.1\",\"GlobalIPv6Address\":\"\",\"GlobalIPv6PrefixLen\":0,\"IPAddress\":\"172.17.0.4\",\"IPPrefixLen\":16,\"IPv6Gateway\":\"\",\"MacAddress\":\"02:42:ac:11:00:04\",\"Networks\":{\"bridge\":{\"IPAMConfig\":null,\"Links\":null,\"Aliases\":null,\"NetworkID\":\"60de714df6c3a5a08d6c4e9ec09af20f1b0a678a4386a67dce722a23386651fa\",\"EndpointID\":\"c71980b822fc26b33804d33e1cbc9e32f728fc4f6617542df07242093b72b868\",\"Gateway\":\"172.17.0.1\",\"IPAddress\":\"172.17.0.4\",\"IPPrefixLen\":16,\"IPv6Gateway\":\"\",\"GlobalIPv6Address\":\"\",\"GlobalIPv6PrefixLen\":0,\"MacAddress\":\"02:42:ac:11:00:04\"}}}}\n"
}

Control the runstate of multiple containers in an environment

See the Environment containers resource.

Create container from a container registry listed in Skytap

Request

POST https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/containers

{
    "container_registry_id": 1000,
    "repository": "Acme",
    "tag": "latest",
    "name": "dynamite",
    "operation": {
        "env_vars": [
            {
                "key": "CONTAINER_USER",
                "value": "uname"
            }
        ],
        "labels": [
            {
                "key": "version",
                "value": "2.3"
            }
        ],
        "command": "/usr/sbin/httpd –f httpd.conf",
        "entry_point": "",
        "privileged": false,
        "restart_policy": "always",
        "max_restarts": 0,
        "cpu_shares": 1,
        "memory_limit": 2048,
        "expose_all_ports": false,
        "volume_bindings": [
            {
                "host_source": "/path/on/host/volume",
                "container_dest": "/path/on/container/volume",
                "writeable": true
            }
        ],
        "network_mode": "bridge",
        "port_bindings": [
            {
                "container_port": "22",
                "host_port": "11022",
                "protocol": "tcp"
            }
        ],
        "host_name": "host-name",
        "domain_name": "example.net"
    }
}

Required and optional parameters

Required parameters

container_registry_id	ID of a container registry from the Skytap container registries resource.
repository	Name of the repository in the container registry.

Optional parameters

tag	ID of a container registry from the Skytap container registries resource. The tag must follow the Docker tag naming restrictions.
name	Name for the container. Restricted to uppercase letters, lowercase letters, numbers, underscores (_), and periods. If no name is provided, the container will be named `New_Container_[timestamp]`.
operation	Object with one or more additional container settings (see configuration options in the table below).

Field name

Type

Description

env_vars

array

Environment variables to set in the container. Formatted as a list of objects with key and value attributes.

If no environment variables are provided, this field will contain an empty array.

labels

array

Docker labels to attach to the container. Formatted as a list of objects with key and value attributes.

If no labels are provided, this field will contain an empty array.

command

string

Command that will be executed when the container starts.

If no command is provided, this field will contain an empty string. Docker will default to using the command in the image spec (if applicable).

entry_point

string

Arguments to be passed to the container.

If no entry point is provided, the field will contain an empty string.

privileged

Boolean

Indicates whether the container be given access to the host operating system.

false by default.

restart_policy

string

Provides Docker with conditions for restarting container. If specified, one of:

always
on-failure
unless-stopped

Otherwise, an empty string is interpreted as “never restart”.

max_restarts

integer

The maximum number of retry attempts for restarting the container (when the on-failure is selected as the restart_policy).

0 by default. If max_restarts is 0, the container will never be restarted.

cpu_shares

integer

Relative priority over other containers for CPU resources.

0 by default. Higher values indicate higher priority.

memory_limit

integer

Max MBs of memory the container is allowed to use.

0 by default; this means no limit should be applied.

expose_all_ports

Boolean

Whether or not to expose all container ports to the host.

false by default.

volume_bindings

array

Array of host directories to mount as data volumes on the container. Formatted as a list of objects with the following attributes:

Attribute name	Type	Description
host_source	string	Path of the directory on the container host VM. Example: `/path/on/host/volume`
container_dest	string	Path of the directory on the container. Example: `/path/on/container/volume`
writeable	Boolean	Whether the container can write to the container host volume.

network_mode

string

Connects the container to one of several network options:

bridge
none
host
container:<id>
container:<name>
<docker-network-id>

For more information, see the Docker network settings documentation.

port_bindings

string

Array of port bindings between the container and container host. Formatted as a list of objects with the following attributes:

Attribute name	Type	Description
container_port	string	Open port on the container. Example: `22`
host_port	string	Open port on the container host. Example: `11022`
protocol	string	Either tcp or udp.

When port_bindings are included, network_mode is a required field.

host_name

string

Hostname for the container

domain_name

string

Domain name for the container

Response

Representation of the new container. While the container is being created, the representation will contain an operation field with the container status and a dictionary of any error messages. Once the container is created, the operation field will no longer be present.

The possible status values are listed below:

Status	Description
new	Parameters have been passed to the VM agent for use.
downloading	The image is being downloaded.
creating	A container is being created from the image.
running	The container is running.
error	An error occurred.

Sample response

{
    "id": 1133,
    "cid": "123456789abcdefghijk123456789abcdefghijk123456789abcdefghijk",
    "name": "dynamite",
    "image": "Acme:latest",
    "created_at": null,
    "last_run": null,
    "status": "busy",
    "privileged": false,
    "vm_id": 111000,
    "vm_name": "Docker 1.10.3 - Ubuntu Desktop 14.04 - 64-bit",
    "vm_runstate": "running",
    "configuration_id": "1234567",
    "spawned_at": null,
    "finished_at": null,
    "operation": {
        "created at": "2016/12/01 10:18:18 -0700",
        "status": "downloading",
        "errors": []
    }
}

Delete container

Request

DELETE https://cloud.skytap.com/v2/containers/{container-id}

Response

Container is deleted.

Delete multiple containers in an environment

Request

DELETE https://cloud.skytap.com/v2/configurations/{configuration-id}/containers/destroy_multiple

{
    "multiselect": [
        "1234567",
        "8901234"
    ]
}

multiselect must be an array of container IDs. All containers must be in the same environment.

Response

Containers are deleted.

Container registries v2 resource

Container registries v2 reference URI

https://cloud.skytap.com/v2/container_registries

Container registries v2 resource model

The element name is container_registries and the following fields are defined:

Field Name	Type	Access	Description
email	string	rw	Email address of the container registry user.
enabled	Boolean	rw	If `true`, the container registry is enabled for use by users in the account.
has_password	Boolean	ro	If `true`, the container registry has a set password. If `false`, the password field is set to `null` or an empty string.
id	integer	ro	ID assigned to the container registry by Skytap.
last_updated_by	object	ro	Representation of the user who last updated the container registry. `null` for Docker public registry entry.
name	string	rw	Container registry name.
password	string	wo	Optional password associated with the container registry user.
readonly	Boolean	ro	`true` for Docker public registry. `false` for all other container registries.
server	string	rw	Host (and optional port) of the container registry server.
updated_at	timestamp	ro	Date and time the container registry was last updated.
username	string	rw	User name of the container registry user.
url	string	ro	URL of the container registry in Skytap.

Supported operations on container registries

Get container registry information

Request

GET https://cloud.skytap.com/v2/container_registries/{container-registry-id}.json

Response

The API will return container registry details, excluding the password (if set). The has_password field will indicate whether a password is set.

Sample response body

{
    "id": 111,
    "url": "/v2/container_registries/111",
    "name": "Project 123 private registry",
    "server": "123.123.123.123:5000",
    "email": "docker-admin@vaporvalve.com",
    "username": "",
    "readonly": false,
    "enabled": true,
    "updated_at": "2016/09/21 12:24:44 -0700",
    "has_password": false,
    "last_updated_by": {
        "id": "123",
        "url": "https://cloud.skytap.com/v2/users/123",
        "first_name": "Earl",
        "last_name": "Maynard",
        "login_name": "emaynard",
        "email": "admin@vaporvalve.com",
        "title": "",
        "deleted": false
    }
}

Get list of container registries

Request

GET https://cloud.skytap.com/v2/container_registries.json

Response

The API will return a list of container registries.

Sample response body

[
    {
        "id": 1,
        "url": "/v2/container_registries/1",
        "name": "Public Docker Hub",
        "server": "index.docker.io/v1/",
        "email": null,
        "username": null,
        "readonly": true,
        "enabled": true,
        "updated_at": "2016/08/23 17:15:17 -0700",
        "has_password": false,
        "last_updated_by": null
    },
    {
        "id": 111,
        "url": "/v2/container_registries/111",
        "name": "Project 123 private registry",
        "server": "123.123.123.123:5000",
        "email": "docker-admin@vaporvalve.com",
        "username": "",
        "readonly": false,
        "enabled": true,
        "updated_at": "2016/09/21 12:24:44 -0700",
        "has_password": false,
        "last_updated_by": {
            "id": "123",
            "url": "https://cloud.skytap.com/v2/users/123",
            "first_name": "Earl",
            "last_name": "Maynard",
            "login_name": "emaynard",
            "email": "admin@vaporvalve.com",
            "title": "",
            "deleted": false
        }
    }
]

Create container registry

Request

POST https://cloud.skytap.com/v2/container_registries.json

{
    "name": "Project123 private registry",
    "server": "123.123.123.123:5000"
}

Required and optional parameters

Required parameters

name	Name of the registry.
server	Host (and optional port) of container registry server.

Optional parameters

email	Email address of container registry user.
enabled	Either `true` or `false`. If not specified, this will be set to true.
username	User name of container registry user.
password	Password of container registry user.

Notes

The password can be null, an empty string, or a string value.
If the password field isn't included in the request body, the password is set to null.

Response

Representation of the new container registry.

Sample response body

{
    "id": 111,
    "url": "/v2/container_registries/111",
    "name": "Project 123 private registry",
    "server": "123.123.123.123:5000",
    "email": "docker-admin@vaporvalve.com",
    "username": "",
    "readonly": false,
    "enabled": true,
    "updated_at": "2016/09/21 12:24:44 -0700",
    "has_password": false,
    "last_updated_by": {
        "id": "123",
        "url": "https://cloud.skytap.com/v2/users/123",
        "first_name": "Earl",
        "last_name": "Maynard",
        "login_name": "emaynard",
        "email": "admin@vaporvalve.com",
        "title": "",
        "deleted": false
    }
}

Edit container registry

Request

PUT https://cloud.skytap.com/v2/container_registries/{container-registry-id}.json

{
    "username": "newuser",
    "password": "newpassword"
}

To update the container registry password, include the password field with the new password. Example: "password": "newpassword"
To remove a password, include the password field with a null value.
Example: "password": null

Response

Updated representation of the container registry.

Delete container registry

Request

DELETE https://cloud.skytap.com/v2/container_registries/{container-registry-id}.json

Response

Container registry is deleted.

Export container registries report (.CSV)

Request

Step 1: Create the report

POST https://cloud.skytap.com/v2/container_registries/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Response

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/container_registries/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Request

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/container_registries/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/container_registries/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request

GET https://cloud.skytap.com/container_registries/exports/123456.csv

Response

The report is downloaded.

Departments v2 resource

A department is a top-level resource used to:

Map your organization’s internal departments or working groups into Skytap
Monitor and limit the resource usage of the department’s members

Notes

You must be a Skytap administrator to access the Departments resource.
All users (including non-administrator users) can view limits for their own departments. See List department limits.

Departments v2 reference URI

https://cloud.skytap.com/v2/departments

Departments v2 resource model

The element name is departments and the following fields are defined:

Field Name	Type	Access	Description
created_at	string	ro	Date the department was created.
description	string	rw	Optional description of department.
id	integer	ro	Unique ID of department.
last_updated_by	object	ro	Representation of the user who last updated the department.
name	string	rw	Descriptive name of the department.
updated_at	string	ro	Date the department was last updated.
url	string	ro	Link to department’s details page.
user_count	integer	ro	Number of users in the department.

Operations on v2 departments

Get department description

Request

GET https://cloud.skytap.com/v2/departments/{department-id}.json

Response

Representation of the department

List departments

Request

GET https://cloud.skytap.com/v2/departments?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return 50 results sorted by name, use the following request:

GET https://cloud.skytap.com/v2/departments?count=50&offset=0&sort=name

The following table contains a full list of optional sort parameters:

Parameter name	Type	Descrtiption
sort	string	Sorts the list of departments either in ascending or descending order. Options: Sort by department name: name or name_desc Sort by number of users: user_count or user_count_desc Sort by date created: created_at_count or created_at_desc Sort by date modified: updated_at or updated_at_desc

Response

Representation of departments in your account. The response will optionally include a Content-Range header and Link header.

Create department

Request

POST https://cloud.skytap.com/v2/departments.json

{
    "name": "Sales",
    "description": "Sales employees."
}

Required and optional parameters

Required parameters

name	Department name

Optional parameters

description

Department description

Response

Representation of the new department

Sample response body

{
    "id": "1234",
    "url": "https://cloud.skytap.com/departments/1234",
    "name": "Sales",
    "description": "Sales employees",
    "created_at": "2015/07/23 14:36:19 -0700",
    "updated_at": "2015/07/23 14:36:19 -0700",
    "user_count": 0,
    "last_updated_by": {
        "id": "5678",
        "url": "https://cloud.skytap.com/users/5678",
        "login_name": "corrina_corrina",
        "first_name": "Corrina",
        "last_name": "Corrina",
        "title": "",
        "email": "corrina@internet.net",
        "created_at": "2014-07-18T17:58:12-07:00",
        "deleted": false
        }
}

View department users

Request

GET https://cloud.skytap.com/v2/departments/{department-id}/users?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return 50 standard users in the department sorted by last name, use the following request:

GET https://cloud.skytap.com/v2/departments/users?count=50&offset=0&sort=last_name&query=account_role:standard_user

The following table contains a full list of optional filter and sort parameters:

Parameter Name Type Description

sort

string

Sorts the list of department users either in ascending or descending order.Options:

Sort by user’s first name: first_name or first_name_desc
Sort by user’s last name: last_name or last_name_desc
Sort by user’s login name: login_name or login_name_desc
Sort by user’s last sign-in date: last_login or last_login_desc
Sort by user account role: account_role or account_role_desc

activated string Filters by the user’s account activation status. If true, the user account has been activated.

last_login

string

Filters by user’s last sign in.

Options:

In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

account_role	Filters results to display users in a specific user role. Options: admin, user_manager, standard_user, or restricted_user.
All Admins	Filters results to display users in a specific group (for example, `1234`).
project_id	Filters results to display users in a particular project (for example, `1234`). To filter by environments that aren't in a project, use `none`.

Response

Representation of department users.

Add users to department

Request

POST https://cloud.skytap.com/v2/departments/{department-id}/users/{user-id}.json

POST https://cloud.skytap.com/v2/departments/{department-id}/users.json

{
    "user_ids": "123,124"
}

Response

Representation of added users.

Users can belong to only one department. Users are automatically removed from their old department when they are added to a new department.

If this action would result in a quota violation, an error will be returned with details of the overages.

Sample response body

[
    {
        "id": "5678",
        "url": "https://cloud.skytap.com/users/5678",
        "first_name": "Peter",
        "last_name": "Kelly",
        "login_name": "Peter_Kelly",
        "email": "pkelly@internet.net",
        "title": "",
        "deleted": false,
        "can_add_resources": true,
        "account_role": "standard_user",
        "activated": true,
        "email_validated": true,
        "last_login": null,
        "sso_enabled": false,
        "department_name": "Sales",
        "department_id": "1234"
    }
]

Remove users from department

Request

DELETE https://cloud.skytap.com/v2/departments/{department-id}/users/{user-id}

DELETE https://cloud.skytap.com/v2/departments/{department-id}/users.json

{
    "user_ids": "123,124"
}

This removes a user or users from a department without assigning them to a new department; it doesn’t delete the users.

Response

Empty response body

List department limits

Request

GET https://cloud.skytap.com/departments/{department-id}/quotas

Note that this request is to the Department Quotas sub-resource, which is contained with the Department resource.

Response

List of limits defined for department. Includes the following fields:

Field Name	Type	Description
id	string	Name of the limit. One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, svm_hours, or svm_hours_power.
units	string	Unit of measure for the limit. For example, the unit for storage is MB.
limit	integer	The defined department limit. `null` is used for no limit.
usage	integer	Amount of the resource in use or consumed by department users.

Add, edit, or remove department limits

Request

By default, departments limits are set to null.

To add a limit, you can change null to a defined limit.
To delete a defined limit, you can change the defined limit to null.

The process for adding and removing a limit is the same as the process for editing a limit (see the sample request below).

PUT https://cloud.skytap.com/v2/departments/{department-id}/quotas.json

[
    {
        "id": "svm_hours",
        "limit": 600
    }
]

Note that this request is to the Department Quotas sub-resource, which is contained with the Department resource.

Required parameters

id	One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, or svm_hours. The svm_hours_power quota can’t be edited.
limit	New limit.

Response

Representation of updated limit.

Delete department

Request

DELETE https://cloud.skytap.com/v2/departments/{department-id}

The delete request will fail if the department contains any users. To remove users, see Remove User from Department.

Response

Department is deleted.

Export a departments report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/departments/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/departments/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/departments/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/departments/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request:
```
 GET https://cloud.skytap.com/departments/exports/123456.csv
```

Response

The report is downloaded.

Groups v2 resource

A group is a top-level resource that represents a collection of users. A representation of a group will contain identifying information for the group (such as the group’s name), as well as representations of all the users in the group.

You must be a Skytap administrator or user manager to access the Groups resource.

Groups v2 reference URI

https://cloud.skytap.com/v2/groups/{group-id}

Groups v2 resource model

The element name is groups and the following fields are defined:

Field Name	Type	Access	Description
description	string	rw	Optional description of group.
id	integer	ro	Unique ID of group.
name	string	rw	Descriptive name of the group.
notification_count	integer	ro	Number of account notifications set to monitor activity by this group or notify this group.
project_count	integer	ro	Number of projects the group is a member of.
url	string	ro	Link to group’s details page.
user_count	integer	ro	Number of users in the group.
users	array	rw	Representation of users within the group Does not appear in the representation of a list of groups; appears in the representation of a single group (requested via GET https://cloud.skytap.com/v2/groups/`<group-id>`.json).

Operations on v2 groups

Get group description

Request

GET https://cloud.skytap.com/v2/groups/{group-id}.json

Response

Representation of group.

List groups

Request

GET https://cloud.skytap.com/v2/groups?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add query parameters to your request. For example, the following request will return a list of up to 50 groups that user 12345 is a member of.

GET https://cloud.skytap.com/v2/groups?query=user_id:12345&count=50&offset=0

For a full list of query parameters, see the table below:

Parameter Name

Type

Description

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

name	Filters results by keyword (e.g., QA).
user_id	Filters results by users within the group (e.g., 12345). Limited to one user_id per request.

sort

string

Sorts the list of groups either in ascending or descending order. Options:

Sort by the number of users in the group: user_count or user_count_desc
Sort by the number of projects the group is a member of: project_count or project_count_desc
Sort by the group’s name: name or name_desc
Sort by the number of notifications: notification_count_desc or notification_count_desc

Response

List of groups.

Create group

Request

POST https://cloud.skytap.com/v2/groups.json

{
    "name": "Product 1 sales team",
    "description": "Sales employees working with Product 1."
}

Required and optional parameters

Required parameters

name	Group name

Optional parameters

description

Group description

Response

Representation of new group.

Sample response

{
    "id": "434",
    "url": "https://cloud.skytap.com/groups/434",
    "name": "Product 1 sales team",
    "description": "Sales employees working with Product 1.",
    "users": []
}

Add user to group

Request

PUT https://cloud.skytap.com/v2/groups/{group-id}/users/{user-id}.json

Response

Representation of the updated group.

Sample response

{
    "url": "https://cloud.skytap.com/groups/434/users/7568",
    "group": {
        "id": "434",
        "ref": "https://cloud.skytap.com/groups/434",
        "name": "Product 1 sales team",
        "user_count": 1,
        "project_count": 0
        },
    "user": {
        "id": "7568",
        "ref": "https://cloud.skytap.com/users/7568"
        }
}

Remove user from group

Request

DELETE https://cloud.skytap.com/v2/groups/{group-id}/users/{user-id}

Response

User is removed from group.

Delete group

Request

DELETE https://cloud.skytap.com/v2/groups/{group-id}

Response

Group is deleted.

Delete multiple groups

Request

DELETE https://cloud.skytap.com/v2/groups/{group-id},{group-id}

Response

Groups are deleted.

Export a groups report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/groups/exports

To request the report be emailed to you when it’s complete, append ?notify_by_email=1 to the URL.

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/groups/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report URL.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/groups/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/groups/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When "ready": true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request:

GET https://cloud.skytap.com/groups/exports/123456.json

Response

The report is downloaded.

Inter-Configuration Network Routes (‘Tunnels’) v2 resource

Tunnels are top-level resources that define a network route between two networks. A representation of the tunnel resource will include information about the connected networks, as well as the status of the connection.

Inter-Configuration Network Route (ICNR) v2 tunnels reference URI

https://cloud.skytap.com/v2/tunnels/{tunnel-id}

Inter-Configuration Network Route (ICNR) v2 tunnels resource model

The element name is tunnels and the following fields are defined:

Field Name	Type	Access	Description
error	string	ro	Describes any errors with the ICNR connection.
id	string	ro	Identifier.
source_network	network	rw	Source network from where the connection was initiated. This network doesn’t need to be “tunnelable” (visible to other networks).
status	string	ro	Status of the tunnel.
target_network	network	rw	Target network to which the connection was made. The network needs to be “tunnelable” (visible to other networks). To check the tunnelable attribute of this network, perform a GET request on the network resource (see Get Network Description).

Operations on v2 ICNR tunnels

Get tunnel description

Request

GET https://cloud.skytap.com/v2/tunnels/{tunnel-id}.json

Response

Identified tunnel resource

Sample response

{
    "id": "tunnel-123456-789011",
    "status": "not_busy",
    "error": null,
    "source_network": {
        "id": "000000",
        "url": "https://cloud.skytap.com/configurations/249424/networks/0000000",
        "name": "Network 1",
        "network_type": "automatic",
        "subnet": "10.0.0.0/24",
        "subnet_addr": "10.0.0.0",
        "subnet_size": 24,
        "gateway": "10.0.0.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "skytap.example",
        "vpn_attachments": []
    },
    "target_network": {
        "id": "111111",
        "url": "https://cloud.skytap.com/configurations/808216/networks/111111",
        "name": "Network 2",
        "network_type": "automatic",
        "subnet": "10.0.2.0/24",
        "subnet_addr": "10.0.2.0",
        "subnet_size": 24,
        "gateway": "10.0.2.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "test.net",
        "vpn_attachments": []
    }
}

Create a tunnel

Request

POST https://cloud.skytap.com/v2/tunnels.json

{
    "source_network_id": 111111,
    "target_network_id": 222222
}

Required parameters

source_network_id	ID of the source network.
target_network_id	ID of the target network. This network needs to be “tunnelable” (visible to other networks). To check the “tunnelable” attribute of this network, perform a GET request on the network resource (see Get Network Description).

Notes

source_network_id and target_network_id can't be the same.
If the source network is a manual network, it can't be connected to a NAT-enabled network

Response

Representation of the new tunnel.

Sample response

{
    "id": "tunnel-123456-789012",
    "status": "not_busy",
    "error": null,
    "source_network": {
        "id": "111111",
        "url": "https://cloud.skytap.com/configurations/249424/networks/111111",
        "name": "Network 1",
        "network_type": "automatic",
        "subnet": "10.0.0.0/24",
        "subnet_addr": "10.0.0.0",
        "subnet_size": 24,
        "gateway": "10.0.0.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "skytap.example",
        "vpn_attachments": []
    },
    "target_network": {
        "id": "222222",
        "url": "https://cloud.skytap.com/configurations/808216/networks/222222",
        "name": "Network 2",
        "network_type": "automatic",
        "subnet": "10.0.2.0/24",
        "subnet_addr": "10.0.2.0",
        "subnet_size": 24,
        "gateway": "10.0.2.254",
        "primary_nameserver": null,
        "secondary_nameserver": null,
        "region": "US-West",
        "domain": "test.net",
        "vpn_attachments": []
    }
}

Delete a tunnel

Request

DELETE https://cloud.skytap.com/v2/tunnels/{tunnel-id}

Response

Tunnel is deleted

Labels v2 resource

Labels are nested within the label categories resource. This sub-resource describes the labels that have been created by users and administrators in the account.

Label values v2 reference URI

https://cloud.skytap.com/v2/label_categories/{label_category-id}/labels.json

Labels v2 resource model

Field Name	Type	Access	Description
counts	list	ro	Displays the number of labels in that category attached to environments, templates, assets and schedules in the account.
id	integer	ro	Label identifier.
label_category	string	ro	Name of the label category that the label belongs to.
label_category_id	integer	ro	ID of the label category that the label belongs to.
value	string	ro	Name of the label.

Operations on v2 label categories

Get labels in a label category

Request

GET https://cloud.skytap.com/v2/label_categories/{label_category-id}/labels.json

Optional filter parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

If count and offset aren’t defined, the API will return 100 results. Example request:

GET https://cloud.skytap.com/v2/label_categories/{label_category-id}/labels.json?count=20&offset=0

Response

Representation of the labels in the label category.

Sample response

[
    {
        "id": "111",
        "value": "ValueCorp",
        "label_category": "Customer",
        "label_category_id": "123456",
        "counts": {
            "environments": 1,
            "templates": 0,
            "schedules": 0,
            "assets": 0
        }
    },
    {
        "id": "222",
        "value": "Retail Mart",
        "label_category": "Customer",
        "label_category_id": "123456",
        "counts": {
            "environments": 0,
            "templates": 0,
            "schedules": 0,
            "assets": 0
        }
    }
]

Add labels to an environment, template, asset, or schedule

To add labels to an environment, template, asset, or schedule, use the labels sub-resource associated with each of those resources. For more infromation, see:

Environment labels v2 sub-resource
Template labels v2 sub-resource
Asset labels v2 sub-resource
Schedule labels v2 sub-resource

Label categories v2 resource

Each label is nested in a top-level label_categories resource, which is managed by account administrators.

Label categories reference URI

https://cloud.skytap.com/v2/label_categories

Labels resource model

Field Name	Type	Access	Description
counts	list	ro	Number of environments, templates, assets, and schedules a label in that label category has been applied to.
enabled	Boolean	rw	If `true`, the label category is enabled and available for use.
id	integer	ro	Label category identifier.
name	string	rw	Name of the label category. Restrictions:- Maximum of 128 characters- The name can’t start with “Skytap:”- The name can’t contain semicolons (;)- You can’t reuse a category name that already exists or existed (even if that category has been deleted).
single_value	Boolean	wo on creation, then ro	If true, users can apply one label from this category per environment and template. (Required for reporting) If false, users can apply multiple labels from this category per environment and template. This field can't be changed after the label category is created.

Operations on v2 label categories

Get label categories

Request

GET https://cloud.skytap.com/v2/label_categories.json

Scope, filter, sort, and paginate parameters

Optional parameters

By default, Skytap will hide disabled label categories from the response. To show disabled label categories, include a show_disabled=true query parameter.

sort	Sorts the results either in ascending or descending order.
count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Options for sort:

Sort by asset count: asset_count or asset_count_desc
Sort by environment count: environment_count or environment_count_desc
Sort by name: name or name_desc
Sort by schedule count: schedule_count or schedule_count_desc
Sort by template count: template_count or template_count_desc

If count and offset aren’t defined, the API will return the 100 enabled categories or 200 enabled and disabled categories.

Example request

GET https://cloud.skytap.com/v2/label_categories?show_disabled=true&count=20&offset=0&sort=environment_count

Response

Representation of the account’s label categories.

Sample response

[
    {
        "id": "1234",
        "name": "Class",
        "enabled": true,
        "single_value": true,
        "counts": {
            "environments": 1,
            "templates": 0,
            "schedules": 0,
            "assets": 0
        }
    },
    {
        "id": "1235",
        "name": "Project",
        "enabled": true,
        "single_value": true,
        "counts": {
            "environments": 1,
            "templates": 0,
            "schedules": 0,
            "assets": 0
        }
    }
]

Create label category

Request

POST https://cloud.skytap.com/v2/label_categories.json

{
    "name": "Customer"
}

Required and optional parameters

Required parameters

name	Name of the label category.

Optional parameters

enabled	By default, Skytap will enable this label category for use. To disable it, set enabled to `false`.
single_value	By default, only one label from this category can be applied to an environment or template. Set single_value to `false` if you want users to be able to apply multiple labels from this category to an environment or template.

Notes

This action must be performed by an account administrator.
Each account can have up to 100 enabled categories and 100 disabled categories.

Response

Representation of the new label category

Sample response

{
    "name": "Customer",
    "id": "123456",
    "enabled": true,
    "single_value": true,
    "counts": {
        "environments": 0,
        "templates": 0,
        "schedules": 0,
        "assets": 0
    }
}

Edit label category

Request

PUT https://cloud.skytap.com/v2/label_categories/{label_category-id}.json

{
    "enabled": false
}

Notes

This action must be performed by an account administrator.
Only name and enabled can be edited.

Response

Representation of the updated label category

Sample response

{
    "name": "Customer",
    "id": "123456",
    "enabled": false,
    "single_value": true,
    "counts": {
        "environments": 0,
        "templates": 0,
        "schedules": 0,
        "assets": 0
    }
}

Delete label category

Label categories can’t be deleted. However, they can be disabled, which will hide them from view. To disable a label category, set enabled to false.

Notification rules resource (account-wide)

Account-wide notification rules are created by an administrator to monitor usage against some or all account, department, or user limits. Administrators select who is notified when an event threshold is reached (for example, all of the administrators in the account, or the user who exceeded a threshold).

Notes

You must be an administrator to create, view, or delete account-wide notification rules.
Users can set their own notification rules with the User notifications resource.
For a detailed description of the various notification options, see Setting up usage notification emails.

Account-wide notification rules v2 reference URI

https://cloud.skytap.com/v2/notifications/<notification-id>

Account-wide notification rules v2 resource model

The element name is notification_rules and the following fields are defined:

Field Name

Type

Access

Description

string

Unique identifier for a notification rule

rule_type

string

The following is the list of supported notification rule types and the events being monitored for each type:

SVMHoursNotificationRule	Metered RAM hours usage against account, department, or user limits (as defined in the scope)
StorageNotificationRule	Storage usage against account, department, or user limits (as defined in the scope)
ConcurrentVMNotificationRule	Concurrent x86 Metered RAM usage against account, department, or user limits (as defined in the scope)
ConcurrentPowerVMNotificationRule	Concurrent Power Metered RAM usage against account, department, or user limits (as defined in the scope) Available only if your account is enabled for Power VMs.
IPAddressesUsedNotificationRule	Public IP addresses usage against the account limit
NetworksUsedNotificationRule	Networks in use against the account limit
VMUptimeNotificationRule	VM running for more than N number of hours by all users or by select users (as defined in the scope)

threshold_amount

integer

String defining the threshold level for the notification rule.

For VMUptimeNotificationRule rule, this value represents the number of hours.
For all other rules this value represents a percentage of limit or reserved capacity.

scope

string

A string that represents the scope at which events are being monitored. One of the following:

customer-quota	Monitor the global Subscription for the account
customer-limit	Monitor the global Limit for the account
all-users	Monitor all users
selected-users	Monitor selected users and/or groups of users
all-departments	Monitor all departments
selected-departments	Monitor selected departments
all-regions-quota	Monitor the regional Subscription for the account (for each enabled region)
all-regions-limit	Monitor the regional Limit for the account (for each enabled region)
selected-regions-quota	Monitor the regional Subscription for the account (for selected regions)
selected-regions-limit	Monitor the regional Limit for the account (for selected regions)

All scopes aren’t valid for every rule type. See the table below.

subjects

array

When scope is selected-users, selected-departments, selected-regions-limit, or selected-regions-quota, this array represents the list of users (and/or groups), departments, or regions being monitored.

The JSON representation of one element (subject) of the array is given below:

{
    ...  
    "subjects": [
        {
            "type": "User",
            "id": "11",
            "name": "Joe User"
        }
    ],
    ...
}

type

Represents the type of subject. Supported subject types are:

User	An individual user (valid when scope is selected-users)
Group	A group of users defined in the account (valid when scope is selected-users)
Department	A department (valid when scope is selected-departments)
Region	A Skytap region (valid when scope is selected-regions-limit or selected-regions-quota)

id If the resource type is a user, group, or department, id is a string representation of the identifier (for example: '1234') for the resource. If the resource type is a region, the id is the name of the region (for example: US-West).

name The full name of the user, group, department, or region resource.

recipients

array

This is an array of users and/or groups who will be notified when the rule is triggered.

The JSON representation of one element (recipient) of the array is given below:

{
    ...
    "recipients": [
        {
            "type": "MetaRecipient",
            "id": "1",
            "name": "Resource Consumer"
        }
    ],
    ...
}

type

Represents the type of recipient. The supported recipient types are:

User	An individual user
Group	A group of users defined in the account
MetaRecipient	A logical representation of a set of users in the account (for example, all Administrators)

If the recipient type is User or Group, this is the identifier for the user or group; if the recipient type is “MetaRecipient”, this field identifies the recipient, where:

1: Resource Consumer
2: All Admins
3: All User Managers
4: All Standard Users

name

If the recipient type is User or Group, this is the name of the user or group; if the recipient type is MetaRecipient, this field identifies one of four possible recipients:

Resource Consumer	the consumer of the resource being monitored (e.g., owner of a VM)
All Admins	all Administrators in the account
All User Managers	all User Managers in the account
All Standard Users	all Standard Users in the account

ordinal

integer

Used internally by Skytap. Don’t write dependencies on this value.

The following table lists the scopes that are valid for each rule type.

Scroll the table to see all of the available options.

	customer-quota	customer-limit	all-users	selected-users	all-departments	selected-departments	all-regions-quota	all-regions-limit	selected-regions-quota	selected-regions-limit
SVMHoursNotificationRule
StorageNotificationRule
ConcurrentVMNotificationRule
ConcurrentPowerVMNotificationRule
IPAddressesUsedNotificationRule
NetworksUsedNotificationRule
VMUptimeNotificationRule

Additionally…

customer-quota and customer-limit scopes are valid for monitoring Metered RAM hours in all accounts, and for monitoring concurrent Metered RAM, network, public IP address, and storage for accounts with global limits on these resources.
all-regions-quota, all-regions-limit, selected-regions-quota, and selected-regions-limit scopes are valid only for accounts with regional concurrent Metered RAM, network, public IP address, and storage limits.

Operations on v2 notification rules

Get account-wide notification rule

Request

GET https://cloud.skytap.com/v2/notifications/{notification-id}.json

You must be an administrator to perform this action.

Response

Representation of the notification rule.

Sample Response

{
    "id": "123456",
    "threshold_amount": 50,
    "rule_type": "StorageNotificationRule",
    "scope": "selected-users",
    "ordinal": 123,
    "subjects": [
        {
            "type": "User",
            "id": 11,
            "name": "John Doe"
        }
    ],
    "recipients": [
        {
            "type": "MetaRecipient",
            "id": 2,
            "name": "All Admins"
        }
    ]
}

List account-wide notification rules

Request

GET https://cloud.skytap.com/v2/notifications.json

You must be an administrator to perform this action.

Response

Returns a list of notification rules set for the account.

Sample Response

[
    {
        "id": "1234",
        "threshold_amount": 12,
        "rule_type": "VMUptimeNotificationRule",
        "scope": "all-users",
        "ordinal": 2,
        "subjects": [],
        "recipients": [
            {
                "type": "MetaRecipient",
                "id": 2,
                "name": "All Admins"
            }
        ]
    },
    {
        "id": "17214",
        "threshold_amount": 50,
        "rule_type": "StorageNotificationRule",
        "scope": "selected-users",
        "ordinal": 1,
        "subjects": [
            {
                "type": "User",
                "id": 1234,
                "name": "John Doe"
            },
            {
                "type": "User",
                "id": 5678,
                "name": "Jane Doe"
            }
        ],
        "recipients": [
            {
                "type": "User",
                "id": 1,
                "name": "Resource Consumer"
            }
        ]
    }
]

Create account-wide notification rule

Request

POST https://cloud.skytap.com/v2/notifications.json

{
    "notification_rule": {
        "rule_type": "StorageNotificationRule",
        "threshold_amount": 50,
        "scope": "selected-users",
        "subjects": [
            {
                "type": "User",
                "id": "11"
            }
        ],  
        "recipients": [
            {
                "id": 2,
                "type": "MetaRecipient"
            }
        ]
    }
}

Required parameters

rule_type	See the options in the Notifications resource model above.
threshold_amount	See the options in the Notifications resource model above.
subjects	If scope is selected-users, selected-departments, or selected-regions, you must include the id and type of the subjects being monitored.
recipients	Include the id and type of the users who aren’tified when the event occurs.

You must be an administrator to perform this action.

Response

Status and the new rule in the response body.

Sample Response

{
    "id": "123456",
    "threshold_amount": 50,
    "rule_type": "StorageNotificationRule",
    "scope": "selected-users",
    "ordinal": 123,
    "subjects": [
        {
            "type": "User",
            "id": 11,
            "name": "John Doe"
        }
    ],
    "recipients": [
        {
            "type": "MetaRecipient",
            "id": 2,
            "name": "All Admins"
        }
    ]
}

Delete account-wide notification rule

Request

DELETE https://cloud.skytap.com/v2/notifications/{notification-id}

You must be an administrator to perform this action.

Response

Status only

Notification rules resource (user-defined)

User notification rules are created by an individual user to monitor their personal Metered RAM usage, storage usage, or the amount of time a VM has been running. The user is the only person notified when an event threshold is reached.

Notes

Administrators can set more robust Account-wide notifications, with a range of monitoring scopes and recipients.
For a detailed description of the various notification options, see Setting up usage notification emails.

User notification rules v2 reference URI

https://cloud.skytap.com/v2/account/notifications/<notification-id>

User notification rules v2 resource model

The element name is notification_rules and the following fields are defined:

Field Name

Type

Access

Description

string

Unique identifier for a notification rule

rule_type

string

The following is the list of supported notification rule types and the events being monitored for each type:

SVMHoursNotificationRule	Metered RAM hours usage against the user limit
StorageNotificationRule	Storage usage against the user limit
ConcurrentVMNotificationRule	Concurrent Metered RAM (x86) usage against the user limit
ConcurrentPowerVMNotificationRule	Concurrent Metered RAM (Power) usage against the user limit Available only if your account is enabled for Power VMs.
VMUptimeNotificationRule	VM running for more than `n` number of hours

threshold_amount

string

String defining the threshold level for the notification rule.

For the VMUptimeNotificationRule rule type, this value represents the number of hours.
For all other rules this value represents a percentage of usage.

ordinal

integer

Used internally by Skytap. Don’t write dependencies on this value.

Operations on v2 user notification rules

Get user notification rule

Request

GET https://cloud.skytap.com/v2/account/notifications/{notification-id}.json

Response

Representation of the notification rule.

Sample Response

{
    "id": "12345",
    "threshold_amount": 100,
    "rule_type": "StorageNotificationRule",
    "scope": "rule-owner",
    "ordinal": 323
}

List user notification rules

Request

GET https://cloud.skytap.com/v2/account/notifications.json

Response

Returns a list of notification rules set by the user.

Sample Response

[
    {
        "id": "12344",
        "threshold_amount": 100,
        "rule_type": "StorageNotificationRule",
        "scope": "rule-owner",
        "ordinal": 222
    },
    {
        "id": "12346",
        "threshold_amount": 2,
        "rule_type": "VMUptimeNotificationRule",
        "scope": "rule-owner",
        "ordinal": 111
    },
]

Create user notification rule

Request

POST https://cloud.skytap.com/v2/account/notifications.json

{
    "notification_rule": {
        "threshold_amount": "100",
        "rule_type": "StorageNotificationRule"
    }
}

Required parameters

rule_type	See the options in the Notifications resource model above.
threshold_amount	See the options in the Notifications resource model above.

Response

Status and the new rule in the response body.

Sample Response

{
    "id": "12345",
    "threshold_amount": 100,
    "rule_type": "StorageNotificationRule",
    "scope": "rule-owner",
    "ordinal": 323
}

Delete user notification rule

Request

DELETE https://cloud.skytap.com/v2/account/notifications/{notification-id}

Response

Status only

Projects v2 resource

Projects are an access permissions model used to share environments, templates, and assets with other users.

Projects v2 reference URI

https://cloud.skytap.com/v2/projects/{project-id}

Projects v2 resource model

The element name is projects and the following fields are defined:

Field Name Type Access Description

auto_add_role_name string rw If this field is set to viewer, participant, editor, or manager, any new users added to your account are automatically added to this project at the specified project role. If the field is set to null, new users aren’t automatically added to the project. Existing users aren’t affected by this setting. For additional details, see Automatically adding new users to a project.

can_edit Boolean ro If true, the user viewing the project can edit it.

configuration_count integer ro Number of environments in the project.

created_at timestamp ro Date and time that the project was created.

id integer ro Identifier.

name string rw User-defined project name.

show_project_members Boolean rw Determines whether projects members can view a list of other project members.

summary string rw User-defined description of project.

template_count integer ro Number of templates in the project.

owner_name string ro Name of the user who owns the project.

owner_url URI ro URI of the user who owns the project.

url URI ro URI reference for resource.

user_role string ro Role of the user currently viewing the project.

user_count integer ro Number of users who are members of the project.

users

array

Representation of users who are members of the project.

Field Name	Type	Access	Description
account_role	string	rw	Defines the user’s access to features and settings. One of: restricted_user standard_user user_manager admin For more information on user roles, see User Roles and Access Permissions.
email	string	ro	Email address to which notifications may be sent. Not validated at submit time.
first_name last_name	string	ro	First and last name strings used for display in the UI. Not validated for uniqueness.
id	integer	ro	User identifier
is_owner	Boolean	ro	Designates whether this user is the project owner. This field is writable ony for the project owner.
login_name	string	rw	Sign-in name for the user
role	string	ro	Defines the user’s access to project resources. One of: viewer participant editor manager For more information on project roles, see Understanding project roles.
title	string	ro	Optional text field for user title.
url	URI	ro	URI reference for the user.

Operations on v2 projects

Get project description

Request

GET https://cloud.skytap.com/v2/projects/{project-id}.json

Response

Representation of projects. By default, the representation will display a limited number of fields.

List projects

Request

GET https://cloud.skytap.com/v2/projects?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return up to 50 projects where the project name starts with sprint, you could make the following request:

GET https://cloud.skytap.com/v2/projects?count=50&offset=0&scope=company&query=name:sprint

Parameter Name

Type

Description

scope

string

Filters results by project ownership. Scope options:

me	returns all projects owned by the user
company	will return all resources owned by the user or shared with the user

owner

string

Filters results by project ownership. Scope options:

me	returns all projects owned by the user
company	returns all projects owned by the user or shared with the user

query

string

Filters results by additional attributes; these are subfilters that can be separated by commas within the query parameter.

name	Filters results by keyword (example, sprint). Example: `query=name:sprint`.
user_id	Filters results by project owner (example, 67890). Limited to one user_id per request. This option isn’t available if the scope parameter is me. Example: `query=user_id:67890`.

created_at

string

Filters by project creation date. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

Response

Representation of projects. By default, the representation will display a limited number of fields and up to 10 projects.

View users or groups in project

Request

GET https://cloud.skytap.com/v2/projects/{project-id}/users/{user-id}.json

GET https://cloud.skytap.com/v2/projects/{project-id}/groups/{group-id}.json

Response

Representation of user or group (including project roles)

Add user or group to project

Request

POST https://cloud.skytap.com/v2/projects/{project-id}/users/{user-id}?role={account_role}

POST https://cloud.skytap.com/v2/projects/{project-id}/groups/{group-id}?role={account_role}

role	One of viewer, participant, editor, or manager.

Response

Representation of user or group (including project role).

List environments, templates, or assets in project

Request

GET https://cloud.skytap.com/v2/projects/{project-id}/configurations

GET https://cloud.skytap.com/v2/projects/{project-id}/templates

GET https://cloud.skytap.com/v2/projects/{project-id}/assets

Response

List of resources in project

Add environment, template, or asset to project

Request

POST https://cloud.skytap.com/v2/projects/{project-id}/configurations/{configuration-id}

POST https://cloud.skytap.com/v2/projects/{project-id}/templates/{template-id}

POST https://cloud.skytap.com/v2/projects/{project-id}/assets/{asset-id}

Response

Status

Remove environment, template, or asset from project

Request

DELETE https://cloud.skytap.com/v2/projects/{project-id}/configurations/{configuration-id}

DELETE https://cloud.skytap.com/v2/projects/{project-id}/templates/{template-id}

DELETE https://cloud.skytap.com/v2/projects/{project-id}/assets/{asset-id}

Response

Status

Public IPs v2 resource

Public IP resources represent static and dynamic public IP addresses that can be used to route network traffic to VMs over the Internet or as an endpoint for VPNs.

Public IPs v2 reference URI

https://cloud.skytap.com/v2/ips

Public IPs v2 resource model

The element name is ips and the following fields are defined:

Field Name	Type	Access	Description
address	string	ro	Unique IPv4 public IP address.
connect_type	string	ro	Either staticor dynamic.
dns_name	string	ro	For dynamic public IP addresses, the Skytap-managed DNS name assigned to the VM.For static public IP addresses, `null`.
id	string	ro	ID of the public IP address (same as address).
nic_count	integer	ro	Number of attached network adapters.
nics	array	ro	Representation of attached network adapters, if any. Includes network adapter id and deployed status. This field is only visible to admins.
region	string	ro	Region that the resource is housed in (for example, US-West).
vpn_id	string	ro	ID of attached VPN, if any. If not attached to a VPN, `null`.

Operations on v2 public IPs

List static public IP addresses and in use dynamic public IP addresses

Request

GET https://cloud.skytap.com/v2/ips.json?count=10&offset=0

Filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional filter parameters

Parameter name

Type

Description

query

string

Filters results by various attributes

attached_to	Filters results by attachment to a type of resource. One of: environment template vpn none (for example, `query=attached_to:environment`).
connect_type	Filters results by type of public IP address One of: dynamic static (for example, `query=type:dynamic`).
region	Filters results by region (for example: `query=region:US-West`).

sort

string

Sorts the results either in ascending or descending order (for example: sort=attached).

Options:

Sort by whether the public IP is attached to a resource: attached or attached_desc
Sort by region: region or region_desc
Sort by IP address: address or address_desc
Sort by resource count: resource_count or resource_count_desc

Response

Representation of public IP addresses in the account.

Get public IP address description

Request

GET https://cloud.skytap.com/v2/ips/{public_ip_address}.json

Response

Representation of public IP

Get counts of attached and unattached static public IP addresses

Request

GET https://cloud.skytap.com/v2/ips/attached_counts.json

Response

{
    "attached": 3,
    "unattached": 2
}

Acquire static public IP

Request

POST https://cloud.skytap.com/v2/ips/acquire.json

{
    "region": "US-West"
}

Required parameters

region

One of APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-London-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West

This request can only be made by administrators.

Response

Representation of newly-acquired public IP address.

Release static public IP address

Request

POST https://cloud.skytap.com/v2/ips/{public_ip_address}/release.json

This request can only be made by administrators.

Response

Public IP is released from account.

View available static public IP addresses

Request

GET https://cloud.skytap.com/v2/configurations/{configuration-id}/vms/{vm-id}/interfaces/{interface-id}/ips/available.json

Response

List of available public IPs that can be attached to network adapter.

Attaching static and dynamic public IPs to VMs

See Network v2 Adapters resource.

Schedules v2 resource

A schedule is a set of one or more automated actions applied to an environment or template. This resource functions identically to the schedules created in the Schedules tab in Skytap’s web interface. All operations that can be performed on schedules from the Schedules tab can also be performed and automated via operations on the schedules resource in the API.

For more information, see Automating Actions with Schedules.

Schedules v2 reference URI

The schedules reference URI is as follows:

https://cloud.skytap.com/v2/schedules/<schedule-id>

Schedules v2 resource model

The element name is schedules and the following fields are defined.

Schedules can be assigned to both templates and environments; some fields are unique to each resource type. These will be covered in separate tables below.

When a schedule is applied to a template, an environment will first be created from that template and all scheduled actions will apply to that environment.

Field Name Type Access Description

actions

array

Array of objects comprising all schedules actions in a schedule, with the exception of actions that can’t recur, such as creating or deleting an environment. Each object has two attributes, with the exception of the save object, which can have three:

type – A string that is one of the allowed action types: run, suspend, shut down, power off, or save.
offset – An integer equal to the number of seconds after start that this action will take place. For instance, if the action was scheduled to start two hours after the schedule was executed, the offset would be 7200.
live_copy – A Boolean that enables save for running VMs (without requiring a previous suspend, shut down, or power off action).

delete_at_end Boolean rw If end_at is set, this Boolean determines whether the schedule’s environment is deleted when the time specified in end_at is reached.

end_at

string

This string specifies the end date of a schedule. The format for the time is YYYY/MM/DD hh:mm. This string is only relevant if the schedule is set to recur (see recurring_days) and/or is set to delete at the end of its operations (see delete_at_end, below).

Notes

If set to recur, the end_at time will specify the date at which the schedule stops recurring.
If delete_at_end is set to true, then the end_at date will determine the time that the schedule's environment is deleted.
If both recurrence and deletion are enabled, the schedule will both cease recurring and delete the environment at this time.
If a UTC offset is included (for example 2017/07/28 11:09 -0400), the UTC offset supersedes the time_zone setting.

executions

array

Array of objects that collectively represent an action performed when the schedule runs.
The fields identify the resource targeted by the action, the action to be performed, and the time when the action will start.
Before a schedule has been run, the executions array will contain an empty list; once started, the array will detail the target of the next action and the action to be performed:

Field Name	Type	Description
id	string	The execution's ID
url	string	The execution's reference URL
schedule_id	string	ID of the schedule execution belongs to
schedule_url	string	URL of same schedule
configuration_id	string	ID of environment that the executions affects
configuration_url	string	URL of environment that the executions affects
next_action	object	A structure that details the target and scheduled time of the next action that will take place as part of the execution
user_id	string	This will display the ID of the execution's owner if that owner is an administrator; otherwise, it will be blank.
user_url	string	This will display the URL of the execution's owner if that owner is an administrator; otherwise, it will be blank.

id string ro Unique identifier for schedule.

next_action_name string ro The name of the next action that will execute as part of the schedule. This can be one of the legal actions (above), start (if the schedule hasn’t yet executed), or delete (if all scheduled actions have completed, end_at has a value, and delete_at_end is set as true).

next_action_time string ro The time when the next action (specified in next_action_name, above) will occur. The format is YYYY/MM/DD hh:mm.

notify_user Boolean rw Determines whether the schedule’s owner receives an email after the completion of a successful action. The user will always be notified when an action fails to complete, even if notify_user isn’t enabled.

recurring_days

array

Array that lists the days on which the schedule will recur.

If this array is blank, the schedule will run until its final operation has been performed, and then delete itself.
By entering one or more days in this string (Sunday, Monday, etc.) the schedule will continue to exist and will recur on those dates until the time set in end_at.

region string ro Region that the resource is housed in (for example, US-West).

start_at

string

A string specifying when the schedule will execute. The format for the time is YYYY/MM/DD hh:mm. For example: 2017/07/28 11:09.

Notes

In the above example, there is no UTC offset, as the time zone is determined by the time_zone string.
If a UTC offset is included (for example 2017/07/28 11:09 -0400), the UTC offset supersedes the time_zone setting.

time_zone string rw The time zone in which the scheduled action will run. Entered as English strings, e.g. Mumbai or Pacific Time (US & Canada). For a list of time zones, see Time Zones and UTC Offsets.

title string rw User-defined name of the schedule. Limited to 256 characters.

user

object

Key-value pairs representing the schedule’s owner. It contains the following fields:

id – the user's account name
url – the URL of the user's details page
login_name – the name used to sign in to Skytap
first_name – the user's first name
last_name – the user's last name
email – the email address registered with Skytap

url string ro Full URL for schedule.

Environment fields

These fields only apply to schedules operating on environments.

Field Name	Type	Access	Description
configuration_id	string	ro	The ID of the environment the schedule is applied to (e.g., `123`).
configuration_name	string	ro	A string representing the name of the environment the schedule is applied to.
configuration_url	string	ro	The URL of the environment the schedule schedule applies to, ending with the ID number. If the ID is `123`, the URL will be `https://cloud.skytap.com/v2/configurations/123`.

Template fields

These fields only apply to schedules operating on templates.

Field Name	Type	Access	Description
append_timestamp_to_name	Boolean	rw	Determines whether a timestamp will be appended to the new environment’s name. This timestamp will reflect the date and time that the configuration was created.
new_configuration_name	string	rw	Name of the environment that will be created from the target template once the schedule is started.
template_id	string	ro	The numerical ID of the template that the schedule is applied to.
template_name	string	ro	User-defined name of the template the schedule is applied to.
template_url	string	ro	The URL of the template the schedule applies to, ending with the ID number (e.g., https://cloud.skytap.com/v2/templates/123).
vm_ids	array	rw	An array of VM IDs for newly-created environment.

Schedules v2 sub-resource

The assets resource contains a labels sub-resource that must be directly accessed from its own resource URIs. For documentation, see:

Schedule labels sub-resource

Operations on v2 schedules

Get a schedule description

Request

GET https://cloud.skytap.com/v2/schedules/{schedule-id}.json

Response

Representation of the schedule.

List schedules

Request

GET https://cloud.skytap.com/v2/schedules?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

By default, the API will return a list of schedules that you own.

If you want to restrict or expand the results, you can add or edit the request parameters. For example, to return a list of 50 schedules owned by all users in the account, change the count to 50 and include &scope=admin.

GET https://cloud.skytap.com/v2/schedules?count=50&offset=0&scope=admin

For a list of optional parameters, see the table below:

Parameter Name

Type

Description

scope

string

Filters or expands the list of schedules. Options:

admin	Displays schedules created by anyone (available to admins only)
admin&query=<user_id>	Display schedules owned by a particular user (available to admins only)

query

string

Filters results by various attributes

configuration_id	Lists schedules that contain a specific environment; includes environments owned by other users in your customer account (for example: `query=configuration_id:12345`) You must have access to the environment to use this query.
template_id	Lists schedules that contain a specific template; includes templates owned by other users in your customer account (for example: `query=template_id:11111`) You must have access to the template to use this query.

sort

string

Sorts the list of schedules either in ascending or descending order. Options:

Sort by environment and/or template name (resource): configuration_name or configuration_name_desc
Sort by owner: user_id or user_id_desc
Sort by schedule name (title): title or title_desc
Sort by date and time of the next action: next_action_time or next_action_time_desc

Response

The response will optionally include a Content-Range header and Link header.

Create a schedule

Request

POST https://cloud.skytap.com/v2/schedules.json

{
    "title": "My New Schedule",
    "template_id": "123456",
    "new_configuration_name": "New Environment",
    "actions": [
            {
                "type": "run",
                "offset": "3600"
            },
            {
                "type": "save",
                "offset": "7200"
                "live_copy": true
            }
        ],
    "start_at": "2013/09/09 09:00",
    "time_zone": "Pacific Time (US & Canada)"
}

Required and optional parameters

Required parameters

title	Schedule name
configuration_id	(or template_id) ID of the environment or template the schedule is based on
start_at	In the format YYYY/MM/DD hh:mm
time_zone	For a list of time zones, see Time Zones and UTC Offsets.

Optional parameters

If you want to assign actions to the schedule during the POST, include an actions array, with type and offset defined. Optionally, include live_copy to save running VMs.

type	One of run, suspend, shut down, power off, and save.
offset	The number of seconds after start that this action will take place
live_copy	(optional save parameter) Enables save for running VMs (without a previous suspend, shut down, or power off action). Either `true` or `false`. If this parameter is omitted, it is interpreted as `false`.

Notes

In XML, you must specify a type attribute of "array" for Actions (<actions type = "array">…</actions>). Specifying this type isn’t necessary for JSON.
If you include live_copy, we strongly recommend that you ensure that VM activity is quiesced before the save action.

Response

Representation of the new schedule

Delete a schedule

Schedules are automatically deleted after the schedule completes. To delete a schedule before it completes, use the following request:

Request

DELETE https://cloud.skytap.com/v2/schedules/{schedule-id}.json

Response

Status

Schedule labels v2 resource

The schedule resource contains a labels sub-resource that must be directly accessed from its own URI.

Schedule labels v2 reference URI

https://cloud.skytap.com/v2/schedules/{schedule-id}/labels

Schedule labels v2 resource model

Field Name	Type	Access	Description
id	integer	ro	Label identifier.
label_category	string	wo on creation, then ro	Name of the label category that the label belongs to.
label_category_id	integer	ro	ID of the label category that the label belongs to.
label_category_single_value	Boolean	ro	If `true`, the label belongs to a single value label category.
value	string	wo on creation, then ro	Name of the label. Max. 255 characters.

Operations on schedule labels

Get schedule labels

Request

GET https://cloud.skytap.com/v2/schedules/{schedule-id}/labels.json

Optional pagination parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

If count and offset aren’t defined, the API will return 100 results. Example request:

GET https://cloud.skytap.com/v2/schedules/{schedule-id}/labels.json?count=20&offset=0

Response

Representation of the schedule labels

Sample response

[
    {
        "id": "111",
        "value": "ValueCorp",
        "label_category": "Customer",
        "label_category_id": "123456",
        "label_category_single_value": false
    },
    {
        "id": "333",
        "value": "Update home page",
        "label_category": "Feature",
        "label_category_id": "123457",
        "label_category_single_value": false
    }
]

Add labels to schedule

Request

PUT https://cloud.skytap.com/v2/schedules/{schedule-id}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Each label must contain:

label_category	the name of an existing label category
value	the label value

Example request to add two labels to a schedule

PUT https://cloud.skytap.com/v2/schedules/{schedule-id}/labels.json

[
    {
        "label_category": "Feature",
        "value": "BlackHat 2016 Demo"
    },
    {
        "label_category": "Team",
        "value": "Security"
    }
]

Notes

A schedule can have up to 30 labels.
Each label category can contain up to 1000 label values.
If the label category is single_value, you can only apply one label from that category to each schedule. If the schedule already contains a label from that category, the new label will replace the old label.
You can't edit existing label values. Instead, detach the label and then attach a new label in the same category.

Response

Updated representation of the schedule labels sub-resource.

Sample response

[
    {
        "id": "444",
        "value": "BlackHat 2016 Demo",
        "label_category": "Feature",
        "label_category_id": "123457",
        "label_category_single_value": false
    },
    {
        "id": "555",
        "value": "Security",
        "label_category": "Team",
        "label_category_id": "123452",
        "label_category_single_value": false
    }
]

Add labels to multiple schedules

Request

PUT https://cloud.skytap.com/v2/schedules/{schedule-id-1},{schedule-id-2}/labels.json

[
    {
        "label_category": "Team",
        "value": "Operations"
    }
]

Required parameters

An array or of one more label objects. Each label must contain:

label_category	the name of an existing label category
value	the label value

Response

Updated list of labels attached to each schedule.

If all of the actions succeeded, the API returns a 200 status code and the response body includes an array of results.
If one or more actions failed, the API returns a 207 status code and the response body contains an array of errors and an array of results.

Sample response

{
    "results": [
        {
            "id": "1234566",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        },
        {
            "id": "12345677",
            "labels": [
                {
                    "id": "333",
                    "value": "Operations",
                    "label_category": "Team",
                    "label_category_id": "123452",
                    "label_category_single_value": false
                }
            ]
        }
    ]
}

Edit schedule label

Schedule labels can’t be edited. Instead, delete the label and add a new one.

Remove schedule label

Request

DELETE https://cloud.skytap.com/v2/schedules/{schedule-id}/labels/{label-id}.json

The label won’t be deleted; it will still be available for reporting.

Response

Updated representation of the labels sub-resource.

Tags v2 resource

Tags can be applied to environments, templates, and assets. The top-level tags resource shows all of the tags in use across the account.

Tags v2 reference URI

https://cloud.skytap.com/v2/tags

Tags v2 resource model

The element name is tags and the following fields are defined:

Field Name

Type

Access

Description

counts

list

Contains:

environments	Number of environments that have this tag attached
templates	Number of templates that have this tag attached
assets	Number of assets that have this tag attached

integer

ID of the tag.

value

string

Tag value.

Notes

If two or more tags have the same value (across all environments, templates, and assets), they will share the same ID.
Tag values aren't case-sensitive (for example, test, Test, and TEST will share the same ID).

Operations on v2 tags

Request

GET https://cloud.skytap.com/v2/tags?count=20&offset=0

This request can be made by any user or administrator.

Required and optional parameters

Response

Representation of tags in the account.

Sample response

[
    {
        "id": 1233,
        "value": "archived",
        "counts": {
            "environments": 0,
            "templates": 10,
            "assets": 0
        }
    },
    {
        "id": 1235,
        "value": "bug",
        "counts": {
            "environments": 4,
            "templates": 0,
            "assets": 0
        }
    }
]

Add tags to an environment, template, or asset

To add tags to an environment, template, or asset, use the tags subresource associated with the environment, template, or asset.

For example, to add a tag to an environment, use the environment tags subresource at https://cloud.skytap.com/v2/configurations//tags.

For more information, see:

Environment tags v2 resource
Template tags v2 resource
Asset tags v2 resource

Usage reports v2 resource

The usage report resource represents a report of all account resource usage within a designated period. When generating the report, you can select:

The usage metric you want to generate reports on
How you want the report to be displayed
The reporting time period

Report request limits

Skytap limits the number of concurrent report requests:

1,000 per account
100 per user

Most requests (Skytap UI or API) persist for 15 minutes. Reports requested via “Email CSV” persist for one week.

The report response is limited to 5,000 report entries. For reports larger than 100 5,000 report entries, use CSV export to download results.

You must be a Skytap administrator to request usage reports.

Usage reports v2 reference URI

https://cloud.skytap.com/v2/reports

Usage reports v2 resource model

The element name is reports and the following fields are defined:

Not all fields are returnd for all customers.

Field Name Type Access Description

aggregate_by string rw Determines the increments in which data is displayed. One of month, day, or none. none displays activity as a lump sum in that period.
Reports grouped by raw must use none for aggregation.

email string ro Email address the report will be sent to; this is the email address of the API user.

end_level integer ro Amount of concurrent Metered RAM in use at the end of the report period selected.

error string ro Describes any errors with the report.

group_by string rw How usage data is grouped.
One of user, group, region, department, or raw.
user is the default.

high_count integer ro Maximum number of VMs running at the highest point in the report period (peak).

high_date string ro Point in time at which the high_level value was achieved.

high_level integer ro Maximum amount of concurrent Metered RAM running at the highest point in the report period (peak).

high_level_above_subscription string ro Amount of concurrent Metered RAM above the reserved capacity at the highest point in the report period.

id integer ro ID of usage report.

label_type

string

One of none , single, or all:

none	No label data will be included in the report.
single	Single value labels will be included in the report.
all	Single and multiple value labels will be included in the report.

Labels are only available for ungrouped reports. If label_type is single or all, group_by will automatically be set to raw.

low_date string ro Point in time at which the low_level value was achieved.

low_level integer ro Amount of concurrent Metered RAM running at the lowest point in the report period.

notify_by_email Boolean rw If true, the report will be emailed to you when it’s complete (CSV report only).

ready Boolean ro If true, the report is ready for access.

region string rw Region to report usage on (for example, US-West). all is the default.

resource_type

string

Type of resource usage to report.
One of storage , svms, or svms_power:

storage	Storage usage will be reported.
svms	Cumulative Metered RAM usage and max concurrent Metered RAM usage for x86 VMs will be reported. svms is the default.
svms_power	Cumulative Metered RAM usage and max concurrent Metered RAM usage for Power VMs will be reported.

results_format string rw File format of the report. One of csv or json.

start_date
end_date string rw Start and end date for data collection period. Either YYYY/MM/dd HH:mm:ss format or ISO 8601 format (2013-03-21T01:00:00.000Z). If blank, the report will include usage from the current calendar month.
Usage data is available from the past two years. If the start_date or end_date is outside of this period, the report may include partial data or no data.

start_level integer ro Amount of concurrent Metered RAM in use at the beginning of the report period selected.

total_concurrent_overage string ro Number of Metered RAM hours charged to the account.

total_usage string ro Total number of Metered RAM hours used by the account.

url string ro URL where the report can be accessed.

utc Boolean rw If true, the report will use the UTC time zone.
If false, the report will use the admin’s local time zone. False is the default.

Operations on v2 usage reports

Create CSV usage report

Request

Step 1: Request to create usage report

POST https://cloud.skytap.com/v2/reports.json

(Optional) Include a request body indicating the type of report you want. If no request body is included, the report uses the default parameters noted in the resource model field descriptions.
(Optional) If you want the report emailed to you, include a "notify_by_email": true parameter.

{
    "start_date": "2015/01/28 16:00:00 -0800",
    "end_date": "2015/02/28 16:00:00 -0800",
    "resource_type": "svms",
    "region": "US-West",
    "group_by": "raw",
    "aggregate_by": "none",
    "results_format": "csv",
    "time_zone": "UTC",
    "notify_by_email": true
}

Response

Initial response

A representation of the new report resource, with additional fields, including id and ready.

Sample response body:

{
    "id": "123456",
    "ready": false,
    "start_date": "2015/01/28 16:00:00 -0800",
    "end_date": "2015/02/28 16:00:00 -0800",
    "resource_type": "svms",
    "region": "all",
    "group_by": "raw",
    "label_type": "all",
    "aggregate_by": "none",
    "results_format": "csv",
    "time_zone": "UTC",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Request

Step 2 (Optional): Download the report via the API

If you want to download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.
Poll the report until the ready field equals true.

Check the response body to make sure than an error field isn’t returned.
If no error field is returned in the response body, when "ready": true, you can access the report at the report URL listed in the response body.

Sample request:

GET https://cloud.skytap.com/reports/{report-id}.csv

Response

The report is downloaded.

Sample response

[
    {
        "id": 1233,
        "value": "archived",
        "counts": {
            "environments": 0,
            "templates": 10,
            "assets": 0
        }
    },
    {
        "id": 1235,
        "value": "bug",
        "counts": {
            "environments": 4,
            "templates": 0,
            "assets": 0
        }
    }
]

Create JSON usage report

Request

Include a request body indicating the type of report you want.

You must generate an ungrouped report (“group_by”: “raw”).

POST https://cloud.skytap.com/v2/reports.json

To view additional pages, resend the report request with the next page number ( "page": 2) in the request body or query string. Example:

POST https://cloud.skytap.com/v2/reports.json?page=2

{
    "start_date": "2015/01/28 16:00:00 -0800",
    "end_date": "2015/02/28 16:00:00 -0800",
    "resource_type": "svms",
    "group_by": "raw",
    "group_by": "user",
    "label_type": "all",
    "results_format": "json"
}

Response

A representation of the report resource, with additional fields, including a null id and a results list. The results list will provide the total number of pages and the first 50 results of the report.

Sample response

{
    "id": null,
    "ready": true,
    "results_format": "json",
    "resource_type": "svms",
    "group_by": "raw",
    "region": "all",
    "aggregate_by": "none",
    "start_date": "2015/01/28 16:00:00 -0800",
    "end_date": "2015/02/28 16:00:00 -0800",
    "created_at": null,
    "time_zone": "Pacific Time (US & Canada)",
    "notify_by_email": false,
    "results": {
        "total_pages": 2,
        "page": 1,
        "items": [
            {
                "start_time": "2015-02-15 16:00:12",
                "end_time": "2015-02-16 09:25:01",
                "user": {
                    "name": "NewUserTest",
                    "url": "/users/1234"
                },
                "value": 1,
                "ram": 1024,
                "cores": 1,
                "usage": 17.4136111111111,
                "object_name": "NAT Template",
                "object_url": "/configurations/1234567",
                "vm_name": "Ubuntu Linux (64-bit)",
                "region": "US-West",
                "labels": [
                    {
                        "id": "111112",
                        "value": "QA",
                        "label_category": "team",
                        "label_category_id": "1234",
                        "label_category_single_value": true
                    }
                ]
            },
            {
                "start_time": "2015-02-15 16:00:12",
                "end_time": "2015-02-16 09:51:59",
                "user": {
                    "name": "NewUserTest",
                    "url": "/users/1234"
                },
                "value": 1,
                "ram": 1024,
                "cores": 1,
                "usage": 17.8630555555556,
                "object_name": "Shared Resources",
                "object_url": "/configurations/123456",
                "vm_name": "Windows Server 2008",
                "region": "US-West",
                "labels": [ ]
            },
            {...}
        ]
    }
}

Users v2 resource

Users are top-level elements in the API data model.

Notes

You must be a Skytap administrator or user manager to create and manage users.
All users can see can view their own user limts. See List user limits.

Users v2 reference URI

https://cloud.skytap.com/v2/users

Users v2 resource model

The element name is users and the following fields are defined:

Field Name	Type	Access	Description
account_role	string	rw	Defines the user’s access to features and settings. One of: restricted_user standard_user user_manager admin For more information on user roles, see User Roles and Access Permissions.
activated	Boolean	ro	Indicates whether the user has activated his or her account.
default_region	string	rw	Default region used for VM imports, asset uploads, new VPNs, and new public IP addresses.
department_id	integer	ro	The ID of the Skytap department that the user belongs to. This field is null if the user isn’t a member of a department.
department_name	string	ro	The name of the Skytap department that the user belongs to. This field is null if the user isn’t a member of a department.
id	string	ro	Identifier.
email	string	rw	Email address to which notifications may be sent. Not validated at submit time.
email_validated	Boolean	ro	Whether the user has validated the email address associated with the user’s account.
first_name	string	rw	First name string used for display in the UI. Not validated for uniqueness.
last_login	timestamp	ro	The date and time that the user last logged in.
last_name	string	rw	Last name string used for display in the UI. Not validated for uniqueness.
login_name	string	rw	Sign-in name for the user.
password	string	wo	The password field is write-only. A new password can be sent with this field, but it will always be returned as the special value `***`. If `***` is sent as the value of the password element, it’s ignored; the current password won’t be changed.
sso_enabled	Boolean	rw	This field will only appear if your customer account is enabled for single sign-on, or SSO. If set to false, this is a standard Skytap user account; if set to true, the account will use SSO to sign in to Skytap.
title	string	rw	Optional text field for user title.
url	URI	ro	URI reference for the user.

Because the v2 API doesn’t support most PUT and POST requests to the User resource, most rw fields must be edited from the v1 API User Resource.

Operations on users

Get user description

Request

GET https://cloud.skytap.com/v2/users/{user-id}.json

Response

A user element.

List users

Request

GET https://cloud.skytap.com/v2/users?count=10&offset=0

Scope, filter, sort, and paginate parameters

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

Optional parameters

You can add other query parameters to your request. For example, to return a list of 50 users who belong to a particular project and who have logged in during the last 30 days, use the following request:

GET https://cloud.skytap.com/v2/users?query=project_id:12345&last_login=now-30d+to+now&count=50&offset=0

The following table contains a full list of optional query and sort parameters:

Parameter Name

Type

Description

query

string

Filters results by various attributes; these are subfilters that can be separated by commas within the query parameter.

account_role	Filters results by user role. Options: admin user_manager standard_user restricted_user
department_id	Filters results to display users in a particular department (e.g., 12345). To filter by users who aren’t in a department, use none.
group_id	Filters results to display users in a particular group (e.g., 12345).
project_id	Filters results to display users in a particular project (e.g., 12345). To filter by users who aren’t in a project, use none.
name	Filters results by keyword (e.g., don).

sort

string

Sorts the results either in ascending or descending order. Options:

Sort by last name: last_name or last_name_desc
Sort by first name: first_name or first_name_desc
Sort by login name: login_name or login_name_desc
Sort by last login: last_login or last_login_desc
Sort by account role: account_role or account_role_desc

last_login

string

Filters by user’s last sign in. Options:

In the past xhours: now-xh+to+now
In the past xdays: now-xd+to+now
In the past xmonths: now-xm+to+now
Not in the past xdays: to+now-xd
Custom: timestamp+to+timestamp

activated

Boolean

Filters by whether the user has activated his or her account.

Response

A list of user elements.

When a user list is requested through the API, some fields won’t be returned. To see a full representation of a user, perform a GET request using the user ID (see Get User Description).

Resend user account activation email

Request

POST https://cloud.skytap.com/v2/users/{user-id}/send_activation_email

Resending the activation email causes the user to be deactivated. When the user clicks the activation link, the account is restored.

Response

The response body is empty if the API returns a 200 status code.

Get a list of environments, templates, or assets owned by the user

To request a list of the environments, templates, or assets owned by a user, perform a GET request to the Environments, Templates, or Assets resource collection, and use the filter and scope parameters to filter the list by the user’s ID. Be sure to set a company-wide scope.

You must be an administrator to perform this request.

For example:

To request a list of templates owned by a user:

GET https://cloud.skytap.com/v2/templates?query=user_id:12345&count=20&offset=0&scope=company
To request a list of environments owned by a user:

GET https://cloud.skytap.com/v2/configurations?query=user_id:12345&count=20&offset=0&scope=company
To request a list of assets owned by a user:

GET https://cloud.skytap.com/v2/configurations?query=user_id:12345&count=20&offset=0&scope=company

List user limits

Request

GET https://cloud.skytap.com/v2/users/{user-id}/quotas.json

Note that this request is to the User Quotas sub-resource, which is contained with the User resource.

Response

List of limits defined for user. Includes the following fields:

Parameter Name	Type	Description
id	integer	Name of the limit. One of concurrent_svms, concurrent_svms_power, concurrent_vms, storage, svm_hours, or svm_hours_power.
units	string	Unit of measure for the limit.
limit	integer	The defined limit. If a user does not have a limit of a particular type, the limit for the customer account is used by default.
usage	integer	Amount of the resource in use or consumed.

Create user limit

Request

POST https://cloud.skytap.com/v2/users/{user-id}/quotas.json

{
    "name": "concurrent_svms",
    "limit": 120
}

When creating a limit, the name and limit fields are required; the units and usage fields are ignored.

Notes

The name field is only used during the POST request. The name values are the same as the id values.
The cumulative_svms_power and svm_hours_power quota can't be edited.
This request is to the User Quotas sub-resource, which is contained with the User resource.

Response

Representation of the new limit.

Edit user limit

Request

PUT https://cloud.skytap.com/v2/users/{user-id}/quotas/{quota-id}?limit={value}

Note that this request is to the User Quotas sub-resource, which is contained with the User resource.

Response

Status

Delete user limit

Request

DELETE https://cloud.skytap.com/v2/users/{user-id}/quotas/{quota-id}

Note that this request is to the User Quotas sub-resource, which is contained with the User resource.

Response

Status

Edit report access

Request

PUT https://cloud.skytap.com/users/{user-id}?report_access={value}

Report access permits non-administrator users to create and view reports.

Valid values for report_access are:

customer	the user can create and view reports for the full account.
department	the user can create and view reports only for the department to which the user belongs.

Notes

Only administrators can grant report_access.
By default, administrators always have account-wide report_access.
report_access can't be granted to restricted users.

Response

Status

Delete user

Request

DELETE https://cloud.skytap.com/v2/users/{user-id}.json

{
    "transfer_user_id": "1234"
}

When deleting a user, a transfer_user_id must be specified. Any resources owned by the user will be assigned to the user specified. The transfer user must have sufficient quota to absorb the resources from the deleted user; otherwise, the transfer use will receive an error message and no resources will be transferred or deleted.

Because this request requires a response body, be sure to include a Content-Type header. For more information, see Required headers for API requests.

Response

Status

Export a user report (.CSV)

Step 1: Create the report

POST https://cloud.skytap.com/v2/users/exports

Include a request body indicating the type of report you want.

To export a quick report, include a “quotas”: false parameter.
To export a full report, include a “quotas”: true parameter.
To have the report emailed to you, include a “notify_by_email”: true parameter.

For more information about these reports, see Generating User Reports.

{
    "quotas": false,
    "notify_by_email": true
}

Initial response

Sample response body:

{
    "id": "123456",
    "ready": false,
    "url": "https://cloud.skytap.com/v2/users/exports/123456",
    "notify_by_email": true,
    "email": "user@internet.net"
}

Step 2 (Optional): Download the report via the API

To download the report through the API, follow this multi-step process:

Parse the response body from the POST request to locate the report ID.

Poll the report until the ready field equals true.

Sample request and response

GET https://cloud.skytap.com/v2/users/exports/123456.json

{
   "id": "123456",
   "ready": true,
   "url": "https://cloud.skytap.com/v2/users/exports/123456",
   "notify_by_email": true,
   "email": "user@internet.net"
}

When “ready”: true, access the report at the report URL listed in the response body. Append .csv to the report URL.

Sample request
```
 GET https://cloud.skytap.com/users/exports/123456.csv
```

Response

The report is downloaded.

VM exports v2 resource

An export represents a single export job. Each export starts with a VM contained in a template owned by the user.

Exports v2 reference URI

https://cloud.skytap.com/v2/exports/{export-id}

Exports v2 resource model

The element name is exports and the following fields are defined:

Field Name

Type

Access

Description

errors

string

Describes the error (when status contains error).

expiration_date

string

Date when export job will be deleted.

filename

string

File name created by Skytap, present in FTP URL.

ftp_host

string

Host name of FTP.

ftp_password

string

Password for FTP sign in.

ftp_url

string

Download location for VM image.

ftp_user_name

string

User name for FTP sign in.

string

Reference ID for the export job.

template_name

string

Name of source template.

status

string

Can equal one of four states:

complete	When the export is complete, the status reads complete.
error	If an error occurs, the status reads error and the error details display in the errors field.
new	The status is new upon initial creation.
processing	The VM is being exported.

template_url

string

URL of source template.

user

string

Array representing a user, same as in “import” resource.

vm_name

string

Name of source VM.

vm_url

string

URL of source VM.

Operations on v2 exports

Get export jobs

Request

GET https://cloud.skytap.com/v2/exports.json

Response

Representation of the export jobs.

Create a VM export

Request

POST https://cloud.skytap.com/v2/exports.json

{
    "vm_id": "12345"
}

Required parameters

vm_id

ID of the VM you want to export; the VM must be within a template.

Response

Representation of new export job.

Get VM export status

Request

GET https://cloud.skytap.com/v2/exports/{export-id}.json

Response

Representation of status field.

Delete VM export

Request

DELETE https://cloud.skytap.com/v2/exports/{export-id}

Response

The export file will be deleted from the Skytap FTP server.

VM imports v2 resource

An import represents a single import job. Each import job imports one or more VM images and their associated networks; these are added to a new Skytap environment. If no networks are defined, Skytap creates a single automatic network for the environment.

Importing is a multi-step process:

Create a New Import Job.
Upload the VM files to the Skytap SFTP site, IBM Cloud Object Storage bucket, or Microsoft Azure Blob Storage container. FTP uploads must be completed outside of the API, using an SFTP client. For FTP uploads, Skytap provides the SFTP site hostname and access credentials in the response body for the request to create a new import job.
Start the Import.
Get the Import Status; you will also be notified via email when the import is complete.

Imports v2 reference URI

https://cloud.skytap.com/v2/imports/{import-id}

Imports v2 resource model

The element name is imports and the following fields are defined:

Field Name Type Access Description

configuration_url string ro This field doesn’t exist until the “status” field equals “complete.” At this point, this field will contain the URL for the new Skytap environment.

errors string ro Describes general import errors (when status contains error). General import errors include mismatched MD5 checksums, unsupported file type, missing files, and import jobs that would exceed the user’s storage limit.

expiration_date timestamp ro Date import job will be deleted.

ftp_host string ro SFTP host name. Ignored for IBM or AZURE imports.

ftp_password string ro Password for SFTP sign in. Ignored for IBM or AZURE imports.

ftp_url string ro The full SFTP path to the upload repo:
sftp://<sftp-username-ref><sftp-password-ref>@<hostname-ref>/upload/
Ignored for IBM or AZURE imports.

ftp_user_name string ro User name for SFTP sign in. Ignored for IBM or AZURE imports.

id string ro Reference ID for import job.

includes_power Boolean rw Set to true for imports that include Power A CPU architecture that supports IBM i, AIX, and Linux (on Power) in Skytap. VMs.

is_released Boolean ro Completion status of the import job. If true, the import job is done and no more VMs can be uploaded for this import job.

provider string rw The source location from which VMs should be imported. Either FTP, AZURE or IBM. If no value is provided, FTP is assumed.

provider_parameters

string

Connection parameters for VM import source. Mbr>

FTP

Field Name	Type	Access	Description
user_name	string	ro	User name for SFTP sign in.
password	string	ro	Password for SFTP sign in.
host	URI	ro	SFTP host name.
url	URI	ro	The full SFTP path to the upload repo.

AZURE

Field Name	Type	Access	Description
container_name	string	rw	The Azure Blob Storage containter name.
connection_string	string	rw	The Azure Blod Storage connection string.

IBM

Field Name

Type

Access

Description

bucket_name

string

The name of the IBM Cloud storage bucket.

resource_crn

string

The CRN of the IBM Cloud storage bucket.

location

string

The IBM Cloud location of the bucket.

api_key

string

The IBM Cloud storage API key.

– OR –

hmac_keys

array

The IBM Cloud storage HMAC credentials.

Field Name	Type	Access	Description
access_key_id	string	rw	The IBM Cloud storage HMAC access key ID..
secret_access_key	string	rw	The IBM Cloud storage HMAC secret access key.

region string rw Region where the template will be stored. One of APAC-2, AU-Sydney-I-1, CAN-Toronto, CN-HongKong-M-1, DE-Frankfurt-1-1, EMEA, IE-Dublin-M-1, IN-Pune-M-1, NL-Amsterdam-M-1, SG-Singapore-M-1, UK-London-M-1, US-Central, US-East-2, US-Texas-M-1, US-Virginia-M-1, or US-West. Use the location closest to the majority of your users. If no region is specified, the import will default to US-West.

region_backend string rw Region that the resource is housed in (for example, US-West).

md5

string

Optional field for user-provided MD5 checksum . ASCII character type. The format must one of the following:

MD5 (HW10.7z) = bca6d3862c661b615a374d7ef61252c5
9f1001eb94538c5ca664e1e1740b3504 HW10.7z
9f1001eb94538c5ca664e1e1740b3504 *HW10.7z (for binary transfers)

status

string

Can equal one of four states:

new: The import job has been created.
processing: To start the import process, change the status to processing.
error: If an error occurs, the status is error and the error will be detailed in the errors field (below).
complete: The import is complete.

template_name string rw Name of environment to be created; required for all imports.

user

string

Array defining the user who created the import. Includes:

id
url
login_name
first_name
last_name

vms

array

Array of VMs in the import job. Includes:

error
errors (VM-level import errors, such as hardware version errors, prohibited characters in the file name, etc.)
id
is_finished
name

Operations on v2 imports

Get import jobs

Request

GET https://cloud.skytap.com/v2/imports.json

Response

Representation of the import jobs.

Create a new import job

To create an import job, make a POST request that includes template_name . You can optionally include a region and MD5 checksum.

Request

POST https://cloud.skytap.com/v2/imports.json

{
    "template_name": "name of environment",
    "region": "US-West",
    "md5": "MD5 (ExportedVM.7z) = cbde87673443077ce053fc57ec4ea8ec"
}

Required and optional parameters

Required parameters

template_name

Name of the new environment

provider

The source location from which VMs should be imported. Either FTP, AZURE or IBM. If no value is provided, FTP is assumed.

provider_parameters

Connection parameters for VM import source.

FTP

Field Name	Description
user_name	User name for SFTP sign in.
password	Password for SFTP sign in.
host	SFTP host name.
url	The full SFTP path to the upload repo.

AZURE

Field Name	Description
container_name	The Azure Blob Storage containter name.
connection_string	The Azure Blod Storage connection string.

IBM

Field Name

Description

bucket_name

The name of the IBM Cloud storage bucket.

resource_crn

The CRN of the IBM Cloud storage bucket.

location

The IBM Cloud location of the bucket.

api_key

The IBM Cloud storage API key.

– OR –

hmac_keys

The IBM Cloud storage HMAC credentials.

Field Name	Description
access_key_id	The IBM Cloud storage HMAC access key ID.
secret_access_key	The IBM Cloud storage HMAC secret access key.

Optional parameters

region	Name of the region to upload to. If no region is specified, your default region (in your user settings) is used.
md5	MD5 checksum. For more information about the valid formats, see Creating MD5 hash values for VM imports.
includes_power	Either `true` or `false`. Can be used only if Power VMs are enabled for your account. If `true`, Skytap checks that the region supports Power VMs; Skytap presents an error prior to processing the import if Power VMs aren’t supported in that region.

Response

Representation of the new import, including the hostname, user name, and password needed to upload the VM files to the SFTP server.

Start the import

Request

After uploading the VM files to the SFTP server, start the import with the following request:

PUT https://cloud.skytap.com/v2/imports/{import-id}.json

{
    "status": "processing"
}

Response

Representation of resource with updated status field.

Get the import status

Request

GET https://cloud.skytap.com/v2/imports/{import-id}.json

Response

Representation of status field.

Delete import

Request

DELETE https://cloud.skytap.com/v2/imports/{import-id}

Response

The import job and site will be deleted from Skytap’s SFTP server. The environment created from the import won’t be affected.

WANs v2 resource

The WANs resource contains two types of network connections:

VPN: a Virtual Private Network (VPN) is an IPsec network tunnel that securely connects networks in your Skytap account to another network over the public Internet.
Skytap on Azure ExpressRoute connection: Skytap on Azure ExpressRoute connection is a dedicated, secure network tunnel between a Skytap environment and an Azure virtual network, available to Skytap on Azure accounts.

WANs are commonly used to connect a network in your organization’s data center to the virtual networks in your Skytap environments.

Notes

At this time, the API supports create, read, update, and delete actions on VPNs, and limited view and edit actions on Skytap on Azure ExpressRoute connections. For help with creating or editing a Skytap on Azure ExpressRoute connection, contact support@skytap.com
You must be an administrator to perform most actions on WAN resources.

Creating a VPN is a multi-step process:

Create a VPN
Test the VPN
Enable the VPN

Connecting a virtual network to a WAN is a multi-step process:

Attach a network to a WAN
Connect the attached network to a WAN

WANs v2 reference URI

https://cloud.skytap.com/v2/vpns/{vpn-id}

Notes

Throughout the Skytap API, WANs (VPN or Skytap on Azure ExpressRoute connection) are referred to as VPNs. Skytap has modified the VPNs resource to include both VPNs and Skytap on Azure ExpressRoute connections.
The {vpn-id} must include the vpn- prefix.

WANs v2 resource model

The element name is vpns and the following fields are defined:

Most of these fields are read-only for Skytap on Azure ExpressRoute connections.

Field Name Type Access Description

acl

object

An array describing the access control list for the VPN or Skytap on Azure ExpressRoute connection. This array won’t appear in a standard request to the VPN Resource. To view or edit this resource, use the WAN ACL sub-resource at https://cloud.skytap.com/v2/vpns/&lt;vpn-id&gt;/acl

Visible only to administrators.

Field Name

Type

Description

default_access_level

string(rw)

One of two options:

use	All users in your account can use this WAN.
null	By default, only administrators in your account can use this WAN. You can grant additional custom access to individual users, groups, or departments.

grantee_counts

object(ro)

Contains:

totals: Contains:

users	The number of users granted custom access to the WAN.
groups	The number of groups granted custom access to the WAN.
departments	Number of departments granted custom access to the VPN.

These numbers don't include users, groups, or departments that inherit access from the default access level setting.

attached_network_count

integer

The number of networks attached to the WAN.

Visible only to administrators.

connected_network_count

integer

The number of networks connected to the WAN.

Visible only to administrators.

connection_type string ro The type of WAN. Either vpn or express_route.
vpn is a Virtual Private Network; express_route is an Skytap on Azure ExpressRoute connection connection.

default_access_level

string

One of:

use – All users in your account can use this WAN.
null – By default, only administrators in your account can use this WAN. You can grant additional custom access to individual users, groups, or departments.

You can edit this field from the WAN ACL sub-resource at https://cloud.skytap.com/v2/vpns/&lt;vpn-id&gt;/acl
(see acl above).

dpd_enabled

Boolean

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

If true, Dead Peer Detection is enabled.

Visible only to administrators.

enabled Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is enabled.

error

string

If there’s an error, this field contains information about the error. Otherwise, it’s blank.

Visible only to administrators.

id string ro Identifier, in the form vpn-#.

internet_key_exchange

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Internet Key Exchange version associated with the WAN.
One of ikev1 or ikev2

Visible only to administrators.

local_peer_ip

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Public IPv4 address associated with the WAN (must be an available Skytap public IP address).

Visible only to administrators.

local_subnet string rw for VPNs, ro for Skytap on Azure ExpressRoute connections Range of Skytap IP addresses routed through tunnel.
IPv4 address range.

maximum_segment_size

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

A maximum segment size can be implemented to resolve certain errors. This setting should not be enabled unless your IT organization or Skytap Support instructs you to do so. Valid range: 536 to 1460.

Visible only to administrators.

name string rw The user-defined name for the WAN. Limited to 255 characters. UTF-8 character type.

nat_local_subnet Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is NAT-enabled.

nat_pool_remaining

integer

Remaining assignable IP addresses for NAT.

Appears only if nat_local_subnet is true.

nat_pool_size

integer

Total size of IP address pool for NAT.

Appears only if nat_local_subnet is true.

network_attachments

array

A representations of the relationships between this WAN and any networks attached to it, including whether the network is currently connected. To view this array, make a GET request to GET https://cloud.skytap.com/v2/vpns/&lt;vpn-id&gt;.
Related: Network v2 Resource.

Visible only to administrators.

phase_1_dh_group

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Phase 1 Diffie-Hellman Group
One of modp1536 or modp2048.

Visible only to administrators.

phase_1_encryption_algorithm

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Phase 1 encryption algorithm. One of aes 256 or aes.

Visible only to administrators.

phase_1_hash_algorithm

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Phase 1 hash algorithm. One of sha1 or sha256.

Visible only to administrators

phase_1_pre_shared_key

string

wo for VPNs, N/A for Skytap on Azure ExpressRoute connections

Phase 1 pre-shared key.

Visible only to administrators.

phase_1_sa_lifetime

integer

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Value in seconds of Phase 1 SA lifetime. Valid range: 1 to 2147483647.

Visible only to administrators.

phase_2_authentication_algorithm**

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Phase 2 authentication algorithm. One of hmac_sha1, or hmac_sha256.

Visible only to administrators.

phase_2_encryption_algorithm

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Phase 2 encryption algorithm. One of aes, aes 256, or aes_gcm.

Visible only to administrators.

phase_2_perfect_forward_secrecy

Boolean

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

If true, Perfect Forward Secrecy (PFS) is used.

Visible only to administrators.

phase_2_pfs_group

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Shows name of PFS group if Phase 2 PFS is set to true.
One of modp1536 or modp2048.

Visible only to administrators.

phase_2_sa_lifetime

integer

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Value (in seconds) of Phase 2 SA Lifetime. Valid range: 1 to 2147483647.

Visible only to administrators.

region

string

Skytap region (for example: US-West).

Visible only to administrators.

region_backend

string

Region that the resource is housed in (for example, US-West).

Visible only to administrators.

remote_peer_ip

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Public IPv4 address associated with WAN endpoint on external network.

Visible only to administrators.

remote_subnets

array

List of remote subnets included or excluded from the WAN.

Included subnets are subnet ranges to which traffic from Skytap will be routed.
Excluded subnets are prevented from connecting to Skytap.

Remote subnets can only be added or removed via the WAN remote subnets sub-resource (https://cloud.skytap.com/v2/vpns/<vpn-id>/subnets). For more information, see Include or Exclude Remote Subnet and Delete Included or Excluded Remote Subnet.

Field Name	Type	Description
cidr_block	string	The IP address range of the subnet.
excluded	Boolean	If set to false, this string specifies an included subnet; if set to true, it specifies an excluded subnet.
id	string	The identifier of the remote subnet (for example, 22.22.0.0/16)In API responses, the id will be prefaced by `x` if the subnet is excluded (for example, x22.22.0.0/16).

The / character in the subnet ID and CIDR block will be escaped to %2F in URLs returned by the API.

route_based Boolean rw for VPNs, ro for Skytap on Azure ExpressRoute connections If true, the WAN is route-based.
If false, it’s policy-based.

sa_policy_level

string

rw for VPNs, ro for Skytap on Azure ExpressRoute connections

Security policy level, the options are null, require, or unique.

Visible only to administrators.

status string ro Status of the VPN tunnel (inactive or active).

test_results

collection

Results of 4 tests: Connect, Phase1, Phase2, and Ping.

Visible only to administrators. Always null for Virtual Private Networks.

url string ro URI for the WAN.

Operations on v2 WAN resources

List WANs

Request

GET https://cloud.skytap.com/v2/vpns.json

Response

Representation of WANs in the account.

Get WAN description

Request

GET https://cloud.skytap.com/v2/vpns/{vpn-id}.json

You must be an administrator to make this request.

Response

Representation of specified WAN.

Create Skytap VPN

Request

When creating VPN, include all of the fields shown in the example below.

POST https://cloud.skytap.com/v2/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "route_based": false,
    "local_peer_ip": "76.32.14.101",
    "remote_peer_ip": "74.2.147.3",
    "internet_key_exchange": "ikev2",
    "phase_1_encryption_algorithm": "aes 256",
    "phase_1_hash_algorithm": "sha256",
    "phase_1_pre_shared_key": "HelloWorld",
    "phase_1_sa_lifetime": 28800,
    "phase_1_dh_group": "modp1048",
    "phase_2_encryption_algorithm": "aes_gcm",
    "phase_2_authentication_algorithm": "hmac_sha256",
    "phase_2_perfect_forward_secrecy": true,
    "phase_2_pfs_group": null,
    "phase_2_sa_lifetime": 3600,
    "sa_policy_level": "require",
    "maximum_segment_size": null,
    "dpd_enabled": true
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Create Skytap-managed ExpressRoute

Request

When creating a Skytap-managed ExpressRoute, include all of the fields shown in the example below.

POST https://cloud.skytap.com/v2/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "local_peer_ip": "76.32.14.101",
    "connection_type": "express_route"
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Create customer-managed ExpressRoute

Request

When creating a customer-managed ExpressRoute, include all of the fields shown in the example below.

POST https://cloud.skytap.com/v2/vpns.json

{
    "name": "VPN",
    "local_subnet": "10.0.0.1/24",
    "nat_local_subnet": false,
    "local_peer_ip": "76.32.14.101",
    "connection_type": "express_route",
    "service_key": "abc-123"
}

You must be an administrator to make this request.

Response

Representation of the new VPN.

Test a VPN

Request

Send a POST request to the WAN test subresource.

POST https://cloud.skytap.com/v2/vpns/{vpn-id}/test.json
```
 {
     "address": "10.0.0.1",
     "port": "443"
 }
```

Required and optional parameters

Required parameters

address

An IP address from a machine that is running on the remote network and can respond to pings. The ping test will use the IP address to check the connection between Skytap and machines on your VPN.

Optional parameters

port	A remote port that is open on the remote machine; if you don’t enter a port, no TCP connectivity test is performed.

Notes

You must be an administrator to make this request.
You can't test Skytap on Azure ExpressRoute connections from the API.

2. Retrieve the test results with a GET request to the VPN resource or the VPN test.

GET https://cloud.skytap.com/v2/vpns/<vpn-id>.json

GET https://cloud.skytap.com/v2/vpns/<vpn-id>/test.json

Response

{
    "test_results": {
        "phase1": true,
        "phase2": true,
        "ping": true,
        "connect": true,
        }
}

Enable the VPN

Request

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}.json

{
    "enabled": true
}

Notes

You must be an administrator to make this request.
You can't test Skytap on Azure ExpressRoute connections from the API.

Response

Updated VPN resource.

Edit the WAN

Request

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}.json

Notes

You must be an administrator to make this request.

name is the only field that can be edited on a Private Network Connection.</li></ul></div>

Response

Updated VPN resource.

Include remote subnet

Request

POST https://cloud.skytap.com/v2/vpns/{vpn-id}/subnets.json

{
    "cidr_block": "10.0.0.0/24"
}

Notes

You must be an administrator to make this request.
You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.

Response

Representation of specified remote subnet

Exclude remote subnet

Request

POST https://cloud.skytap.com/v2/vpns/{vpn-id}/subnets.json

{
    "cidr_block": "10.0.0.0/24",
    "excluded": "true"
}

Notes

You must be an administrator to make this request.
You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.

Response

Representation of specified remote subnet

Delete included or excluded remote subnet

Request

DELETE https://cloud.skytap.com/v2/vpns/{vpn-id}/subnets/{subnet-id}

Notes

You must be an administrator to make this request.
You can't edit the remote subnet for Skytap on Azure ExpressRoute connections from the API.

Response

Deleted remote subnet

Attach/connect/disconnect/detach a virtual network to a WAN

To attach, connect, disconnect, or detach a network to a WAN, edit the Networks resource. For instructions, see Network v2 Resource.

View a summary of the access control list for a WAN

Request

GET https://cloud.skytap.com/v2/vpns/{vpn-id}/acl.json

This request can only be made by administrators.

Response

Representation of the access control list.

Sample Response

{
    "default_access_level": null,
    "grantee_counts": {
        "totals": {
            "users": 0,
            "groups": 0,
            "departments": 0
        }
    }
}

Edit the default access level granted to all users in the account

Request

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}/acl.json

{
    "default_access_level": "use"
}

Required parameters

default_access_level – One of use or null.

This request can only be made by administrators.

Response

Updated representation of the WAN access control list.

Sample response

{
    "default_access_level": "use",
    "grantee_counts": {
        "totals": {
            "users": 0,
            "groups": 0,
            "departments": 0
        }
    }
}

View the users, groups, or departments with custom access to the WAN

Request

GET https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/users.json?count=20&offset=0

GET https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/groups.json?count=20&offset=0

GET https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/departments.json?count=20&offset=0

Required parameters

count	Indicates the number of results to return. Used with offset to create paginated results.
offset	Indicates how many results to omit from the ordered list. For example, if you set the offset value to 20, the API response will omit the first 20 results in the list. The response will begin with the 21st result. Used with count to create paginated results.

This request can only be made by administrators.

Response

Representation of the users, groups, or departments that have been granted custom access to the VPN.

Sample response with groups

[
    {
        "type": "Group",
        "id": 123,
        "name": "QA",
        "description": "QA Group",
        "access_levels": [
            "use"
        ]
    },
    {
        "type": "Group",
        "id": 124,
        "name": "Devs",
        "description": "Development Group",
        "access_levels": [
            "use"
        ]
    }
]

Add WAN access for a user, group, or department

Request

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/users/{user-id}.json

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/groups/{group-id}.json

PUT https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/departments/{department-id}.json

{
    "access_level": "use"
}

Required parameters

access_level – use

This request can only be made by administrators.

Response

Updated representation of the user, group, or department within the VPN ACL sub-resource.

Sample Response with a Group

{
    "type": "Group",
    "id": 123,
    "name": "QA",
    "description": "QA Group",
    "access_levels": [
        "use"
    ]
}

Remove WAN access for a user, group, or department

Request

DELETE https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/users/{user-id}.json

DELETE https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/groups/{group-id}.json

DELETE https://cloud.skytap.com/v2/vpns/{vpn-id}/acl/departments/{department-id}.json

This request can only be made by administrators.

Response

Updated representation of the user, group, or department within the access control list sub-resource.

Sample response with a group

{
    "type": "Group",
    "id": 123,
    "name": "QA",
    "description": "QA Group",
    "access_levels": []
}

Delete VPN

Request

DELETE https://cloud.skytap.com/v2/vpns/{vpn-id}

Notes

You must be an administrator to make this request.
You can't delete Skytap on Azure ExpressRoute connections from the API.

Response

Deleted VPN.

Webhooks v2 resource

Webhooks provide real-time streaming data that can be sent to a URL that you choose.

Webhooks v2 reference URI

https://cloud.skytap.com/v2/admin/webhooks.json

Webhooks v2 resource model

The following fields are defined:

Field Name	Type	Access	Description
category	string	ro	Type of webhook. Allowed values are auditing and usage.
certificate	string	rw	Public key of the TLS certificate.
created_at	timestamp	ro	Date and time the webhook was created.
enabled	boolean	rw	If `true`, the webhook is on.
id	integer	rw	Webhook identifier.
updated_at	timestamp	ro	Date and time the webhook was last edited.
url	string	rw	URL of the webhook data endpoint.

Operations on v2 webhooks

Get webhook

Request

GET https://cloud.skytap.com/v2/admin/webhooks/{webhook-id}

Response

{
    "id": 456,
    "enabled": true,
    "url": "http://example.com/webhook",
    "certificate": "TLS-Public-Key",
    "category": "audit"
}

Create webhook

Request

POST https://cloud.skytap.com/v2/admin/webhooks.json

{
    "url": "http://example.com/webhook",
    "category": "audit",
    "certificate": "TLS-Public-Key",
    "enabled": "true"
}

Required parameters

url	URL of the webhook data endpoint.
category	Type of webhook. Allowed values are audit and usage.

Optional parameters

certificate

Public key of the TLS certificate for the webhook data endpoint (recommended).

Response

Representation of the webhook.

{
    "id": "13",
    "url": "https://test.net/",
    "certificate": "TLS-Public-Key",
    "category": "audit",
    "enabled": true
}

Required and optional parameters

Edit webhook

Request

PUT https://cloud.skytap.com/v2/admin/webhooks/{webhook-id}

{
    "url": "https://example.com/webhook",
    "certificate": "New-TLS-Public-Key"
}

Response

Updated representation of the webhook.

{
    "id": "13",
    "url": "https://example.com/webhook",
    "certificate": "New-TLS-Public-Key",
    "category": "audit",
    "enabled": true
}

v2 change log

January 2024

REST API changes:
- Removed shared drive Account settings.
- Added support for Precisely Assure MIMIX™ Software for Power VMs.

June 2023

REST API changes:
- Added support for Environment Multi-Attach Storage for Power VMs.

June 2022

REST API changes:
- Added support for Power VM guestOS and guestOS_version.

February 2022

REST API changes:
- SmartRDP is discontinued..

December 2020

REST API changes:
- Added api_tokens to Account details and removed api_token Get all of my API tokens.
- Added sharing_links to Templates.

October 2020

REST API changes:
- Added provider and provider_parameters to VM Imports to support VM imports from IBM Cloud Object Storage and Microsoft Azure Blob Storage VM imports resource.
- Added ibmi_vms_enabled to Account Settings Account settings v2 resource.

June 2020

REST API changes:
- Added the environment_lock resource Environment lock resource.

February 2020

REST API changes:
- Added entitled_capacity for Power VMs and cpw for IBM i VMs Environment VMs resource.

September 2019

REST API changes:
- Enabled copy/paste over SSH for Power VMs Environment VMs resource.

June 2019

REST API changes:
- Added report delegation to the Users resource. This enables administrators to grant the ability to create and view reports to user managers and standard users.
- Added usage webhook to the Webhooks v2 resource to add event-streaming for usage data. For more information, see Configuring the webhook service for usage data.

April 2019

REST API changes:
- Added delete operation to the Assets resource.

March 2019

REST API changes:
- Added multiple-monitor attributes to the VM Hardware resource. This enables a new multiple-monitor display mode for the SRA browser client.
Documentation improvements:
- Added {user-defined value} formatting to more clearly indicate values provided by the user.

January 2019

REST API changes:
- Added Webhooks v2 resource. This is a new event-streaming service, currently available for audit report data. For more information, see Configuring the webhook service for audit data.

September 2018

REST API changes:
- Added a rate_limited Boolean to the Environment VMs resource. If a VM is being rate-limited because of high amounts of activity in the account, rate_limited will be true.

August 2018

REST API changes:
- Added error_details attributes to Environment VMs resource resource model.
- Added error_details attributes to Sharing Portals resource resource model.

July 2018

REST API changes:
- Changed API navigation buttons to match Skytap UI styles.
- Corrected variable formatting in API requests.

June 2018

Added configuration_name attribute to Environments Sharing Portals resource
Documentation improvements:
- Added error field to Usage Reports resource model.
- In the Environments resource model, the errors field was incorrectly listed with the type string; the type is array.
- Edited the sample requests for enabling automatic shutdown or suspend in the Environments resource model; removed the erroneous suggestion to set unused automatic suspend or shutdown fields to null. When you send a request that updates one of the four suspend or shutdown options (suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time), the other three options are automatically nullified by the REST API; they don’t need to modified by the REST API user. This update corrected a documentation error; no REST API functionality changed for these operations.
- Corrected the sample requests for disabling automatic shutdown or suspend in the Environments resource model. To nullify the fields and disable automatic suspend, the values must be set to an empty string (""), not null.
- Removed descriptions of the /v2/users/<user-id>/configurations, /v2/users/<user-id>/assets, and /v2/users/<user-id>/templates endpoints in the Users resource model. These endpoints display a list of resources that are both owned by the user and that are directly shared with the API requester through projects. This may not be the full list of environments, templates, or assets owned by the user. We recommend that administrators follow the recommendations in Get a list of environments, templates, or assets owned by the user.

May 2018

Split API documentation for account-wide notification rules and user-defined notification rules into separate sections for clarity.
- Account-wide notification rules resource
- User-defined notification rules resource
Added new department limit and regional limit scope options for account-wide notification rules set by administrators. See the updated Account-wide notification rules resource).
Added shutdown_at_time, shutdown_on_idle, and auto_shutdown_description attributes to Environments resource resource model. Added instructions for enabling and disabling automatic shut down for environments.
Updated the Account Details resource model:
- Changed description of wants_email field. This field is now read-only, and entries have been changed to null. Marketing email preferences are now managed at http://research.skytap.com/Email-Preference-Center.html.
  - Attempts to edit this field will be ignored by the REST API.
- Added country_of_residence and country_of_residence_name.

April 2018

Edited description of the guestOS field in the Hardware element of the Environment VMs resource model. This field is now read/write for Power VMs; previously, it was read-only.
Removed modp768 as an option for the phase_1_dh_group and phase_2_pfs_group fields in the WANs resource model. Added aes_gcm an an option for the phase_2_encryption_algorithm field.

March 2018

Updated the documentation for inclusion of Private Network Connections:
- Renamed ‘VPNs’ resource to ‘WANs’ resource in the API documentation. The WANs resource now includes representations of VPNs and Private Network Connections. For backward-compatibility, the reference URI hasn’t changed. VPNs and Private Network Connections can both be accessed from:
  
  https://cloud.skytap.com/v2/vpns
- Updated the WANs resource model to include a new attribute: connection_type. This field is used to distinguish between VPNs and Private Network Connections.
- Updated the WANs resource model and supported operations to describe attributes and operations supported for Private Network Connections.
Added suspend_at_time and suspend_on_idle attributes to Environments resource resource model.
Documented v2 operations for enabling and disabling auto-suspend on an environment:

November 2017

Classrooms extension API updates: Added state attribute to Class Labs resource and updated description of state in the Classes resource.

October 2017

Added operation for changing the account password from the Account details resource.
Updated documentation throughout for inclusion of Power VMs. Generally, these fields are visible and applicable only if your account is enabled to use Power VMs.
- Added concurrent_svms_power and svm_hours_power usage limit types to user, department, and account limits. The svm_hours_power usage limit can’t be edited.
- Added svms_by_architecture attribute to environment and template resource models.
- Added notes that some VM hardware attributes can’t be edited and aren’t applicable to Power VMs, including vnc_keymap, uuid, rtc_start_time, time_sync_enabled, copy_paste_enabled, and nested_virtualization.
- Added notes that some VM network adapter attributes can’t be edited for Power VMs, including mac, nic_type, and promiscuous_mode_enabled.
- Added read-only architecture attribute to VM resource model; this is either power or x86.
- Added includes_power attribute that can be optionally included during POST requests to the Imports resource.
- Added svms_power option to resource_type in Usage reports.
- Added ConcurrentPowerVMNotificationRule option to rule_type in Notifications resource.
- Noted throughout that Power VMs can’t be suspended. In most cases, operations that would suspend a Power VM fail (for example: copying a environment with running Power VMs or creating a template from an environment that contains running Power VMs). However, there is one case where the operation succeeds: if you change an entire environment’s runstate to suspended, the x86 VMs are suspended and the Power VMs are skipped (they remain running)>. Refer to the documentation for a specific operation for more information about the expected behavior.
- NOTE: Skytap has edited the error messages associated with user, department, and account limits. If an SVM or SVM hours limit is reached, the system now provides more details about which type of SVM limit was reached.
  - “SVMs limit” is now either “x86 SVMs limit” or “Power SVMs limit”.
  - “SVM hours limit” is now either “x86 SVM hours limit” or “Power SVM hours limit”.

August 2017

Added connect_type and dns_name to Public IPs resource.
Updated options for filtering and sorting a list of public IP addresses in your account (Public IPs resource).
Updated Network Adapters resource to describe new dynamic public IPs operations.
Updated Network Adapters resource resource model to include new descriptions of the public_ips and public_ips_counts fields. Added new public_ip_attachments array to the resource model.
Added references to courses, classes, and class labs resources.

March 2017

Added containers and container registries v2 resources (see Containers v2 resource and Container registries v2 resource). Added supported operations for editing VMs as container hosts and viewing networks within a Docker container host.
Added display_server, audio_in, and audio_out fields to the environment VM resource model (see Environment VMs resource). These settings support bi-directional audio through the HTML5 browser client.

February 2017

Added optional sort parameters for requesting a list of public IP addresses (see Public IPs v2 resource).
Added operation to request counts of attached and unattached public IP addresses (see Public IPs v2 resource).
Documented operation to resend user account activation email (see Users v2 resource).
Noted that usage data is available from the past two years. The usage report start_date or end_date is outside of this period, the report may include partial data or no data (see Usage reports v2 resource).
Updated list of auditing activity names to include password changes, API token resets, browser activation, containers and container registry activities, public IP address activities, and published service activities.

November 2016

Added instructions for adding labels to multiple environments, templates, assets, or schedules (see Environment labels v2 resource, Template labels v2 resource, Asset labels v2 resource, and Schedule labels v2 resource).

October 2016

Added label_category_id filter to Environments v2 resource and Templates v2 resource.
Added instructions for adding tags to multiple environments, templates, or assets (see Environment tags v2 resource, Template tags v2 resource, and Asset tags v2 resource).
Added label_category_single_value to resource model in Environment labels v2 resource, Template labels v2 resource, Asset labels v2 resource, and Schedule labels v2 resource.

August 2016

Documented optional sort parameters for GET requests to the Label categories v2 resource.

July 2016

Added Labels v2 resource, Label categories v2 resource, and associated subresources (Environment labels v2 resource, Template labels v2 resource, Asset labels v2 resource, and Schedule labels v2 resource).
Added label_type option to Schedule labels v2 resource.
Added label_value_id filter to Environments v2 resource and Templates v2 resource.
Update: Reverted documentation error about PATCH method. A PUT request is still valid for adding labels to an environment, template, asset, or schedule.

June 2016

Added Tags v2 resource and associated subresources (Environment tags v2 resource, Template tags v2 resource, and Asset tags v2 resource). The top-level tags resource is used to view all of the tags in the account. The subresources are used to add to and remove tags from environments, templates, and assets.

May 2016

Added instructions for changing an asset’s owner. See Assets v2 resource.
Added new Account details v2 resource. This resource contains information presented on the My Account page within Skytap, including shared drive SFTP credentials.

April 2016

The API will now apply URL encoding to the / character in parameters; / will be escaped to %2F. For example, the URL for a remote subnet will now be returned as https://cloud.skytap.com/vpns/vpn-13232/subnets/10.0.0.0%2F16. The API will still accept requests with URLs that include / in parameters (https://cloud.skytap.com/vpns/vpn-13232/subnets/10.0.0.0/16
Updated Project v2 resource model to include new and previously undocumented parameters, including summary and can_edit.
Added instructions for generating a JSON usage report.
Added optional sort parameters for viewing a list of schedules. See Schedules resource.
Updated description of environment publish sets v2 to match new UI.
- API element and field names haven’t changed.
- Added required count and offset parameters for GET requests to the /v2/configurations/<config-id>/publish_sets resource collection. If these parameters are omitted, the API will return a 302 response.
- Added optional sort parameters for sorting a list of sharing portals.
Made anonymous_smart_rdp a read/write parameter in the environment publish sets v2 resource. Previously, this had been write only.
Added sample representation of vpn_attachments array in the Environment networks v2 resource.

March 2016

Fixed documentation bug by removing All Skytap option for filtering a list of assets by region. See Asset v2 resource.
Deprecated use as an option for a VPN’s SA policy level. See VPN v2 resource.
Fix documentation bug in sample request for adding a disk to a VM. Disk size must be included in an array. See VM v2 resource.
Added platform_errors array to the Configuration (Environment) v2 resource.
Edited Account limits v2 resource to support regional limits:
- Added region parameter to each limit.
- Added option to filter list of limits by region.
- Changed the response body data structure for customers with regional limits. If you have regional limits enabled in your account, each customer limit is now grouped into one of several arrays. For example, all global usage limits are included in a global array, while all limits for US-West are grouped in a US-West array. This change doesn’t affect customers who don’t have regional limits enabled.
Added rtc_start_time parameter to VM hardware element. This is used to set the VM BIOS clock at boot time.
Added default_access_level as an accepted parameter for editing a VPN’s default access level for all users in the account. access_level will continue to be accepted for backward-compatibility. See VPN v2 resource.
Added rtc_start_time parameter to VM hardware element. This is used to set the VM BIOS clock at boot time. See VM v2 resource.

February 2016

Added notification_count to the Group v2 resource model.
Added ability to sort list of groups by notification count. See Group v2 resource.
Added instructions for deleting multiple groups. See Group v2 resource.
Added default_region to the User v2 resource model.
Added ability to email .csv reports. For an overview, see Exporting CSV reports from the API.
Added instructions for generating a .csv report of all departments in the account. See Department v2 resource.
Added instructions for generating a .csv report of all groups in the account. See Group v2 resource.

January 2016

Added default_access_level to the VPN v2 resource model; this field is now returned in a GET request to the VPN resource.
Documented count and offset as required parameters for requesting a list of users, groups, or departments that have custom VPN access (see VPN v2 resource).

December 2015

Added a VPN ACL resource. Added instructions for changing a VPN’s default access level, as well as viewing and editing custom access levels for users, groups, and departments. See VPN v2 resource.
Added instructions for adding and removing multiple users from a department. See Department v2 resource.
Fixed the following documentation errors:
- Corrected restarted runstate value to reset.
- Corrected excluded_vm_ids to excluded_vms_ids in Stage (VM Sequencing) v2 resource.
- Removed “Delete Environment” from list of supported operations in Configuration (Environment) v2 resource.

November 2015

Removed Beta designation from API v2 documentation.
Updated the Group v2 resource
- Added project_count and user_count to the v2 representation of a group
- A GET request to pull a list of groups now requires count and offset parameters (GET https://cloud.skytap.com/v2/groups.json?count=10&offset=0). This matches the pagination pattern used by other v2 resources.
Updated the v2 Public IP resource (see Public IP v2 resource):
- A GET request to pull a list of public IPs in the account now requires count and offset parameters (GET https://cloud.skytap.com/v2/ips.json?count=10&offset=0). This matches the pagination pattern used by other v2 resources.
- The permission requirements have changed. Users can now request a list of public IPs in the account, although they won’t see details about which network adapters the public IPs are attached to.
- Added nic_count to the v2 representation of a public IP.
- Added instructions for requesting a public IP’s description and viewing a list of public IPs available to attach to a network adapter
Added a rate_limited Boolean to the Configuration (Environment) v2 resource. If an environment is being rate-limited due to high amounts of activity in the account, rate_limited will be true.
Added instructions for requesting a list of VPNs in the account (see VPN v2 resource).
Updated descriptions of fields within the VPN v2 resource, Public IP v2 resource, and Publish Set v2 resource.
Added notes documenting the permissions required for reviewing and requesting VPN data in the VPN v2 resource.
Added alternate request for viewing VPN test data (see VPN v2 resource).
Added excluded_vm_ids array in Stage (VM Sequencing) v2 resource to support Do not run option for VM Sequencing.
Documented required and optional parameters for requesting a list of department users (see Department v2 resource).

October 2015

Added project_id parameter to instructions on changing an environment’s owner. This parameter is required when reassigning ownership to a restricted user and optional when reassigning ownership to any other user type.
Added instructions for viewing environment notes to Configuration (Environment) v2 resource.
Added instructions for running, stopping, or suspending multiple VMs within an environment (see Configuration (Environment) v2 resource).
Added optional network_interface and vpn_key parameters for requesting specific RDP files if a VM has multiple published services or NAT VPN connections. See VM v2 resource.

September 2015

Added Secondary IP addresses v2 resource.
Added instructions for exporting a report of all network endpoints on the VM. See VM v2 resource.
Added new custom content tab fields to Publish Set v2 resource.
Added instructions for downloading RDP files via the API. See VM v2 resource.
Added hardware_version field to VM v2 resource.
Added instructions for viewing, adding, and deleting template labels. See Templates v2 resource.
Added vms read-only array to Import VM v2 resource.

August 2015

Documented operations for adding and deleting VM labels in the VM v2 resource.
Documented promiscuous mode permission in the Network Interface v2 resource.
Documented adding a network in the Network v2 resource.

July 2015

Significant updates to the Import VM v2 resource, including a simplified POST request for creating new import jobs that support multi-VM imports. The API will briefly support imports that use the legacy POST request fields. These requests will create single-VM imports where the VM is imported into a Skytap template.

Corrected sample request for a new schedule. Removed note stating that only one action can be listed during schedule creation.
Documented operations for adding, editing, and deleting VM disks in the VM v2 resource.
Documented operations for removing data from the VM and environment user_data fields.
Added query filters to the Schedule v2 resource that can show a list of schedules that include a specific environment or template.

June 2015

API v2 initial release.